Connectors API

Connectors are communication channels for notifications and OTPs. All endpoints require authentication.

Base: /api/connectors

GET /api/connectors

List all connectors for the authenticated Host.

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "connectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "type": "email",
      "name": "SMTP Email",
      "is_verified": true,
      "priority": 0,
      "created_at": "2026-02-21T10:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "type": "sms",
      "name": "Twilio Primary",
      "is_verified": true,
      "priority": 1,
      "created_at": "2026-02-21T11:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
id	uuid	Unique identifier
type	string	Connector type (email, sms, whatsapp, telegram)
name	string	Display name
is_verified	boolean	Whether connector is working
priority	integer	Send priority (0 = highest)
created_at	timestamp	Creation time

---

POST /api/connectors

Create a new connector.

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request: Email (SMTP)

{
  "type": "email",
  "name": "SMTP Email",
  "config": {
    "smtp_host": "smtp.example.com",
    "smtp_port": 587,
    "username": "your-username",
    "password": "your-password",
    "from_address": "noreply@yourdomain.com"
  },
  "priority": 0
}

Request: SMS (Twilio)

{
  "type": "sms",
  "name": "Twilio Primary",
  "config": {
    "provider": "twilio",
    "api_key_sid": "SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "api_key_secret": "your_api_key_secret",
    "from_number": "+1234567890"
  },
  "priority": 1
}

Request: WhatsApp

{
  "type": "whatsapp",
  "name": "WhatsApp Business",
  "config": {
    "provider": "whatsapp",
    "access_token": "your_access_token",
    "phone_number_id": "123456789012345",
    "business_account_id": "987654321098765"
  },
  "priority": 2
}

Request: Telegram

{
  "type": "telegram",
  "name": "Telegram Bot",
  "config": {
    "provider": "telegram",
    "bot_token": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
  },
  "priority": 3
}

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "email",
  "name": "SMTP Email",
  "is_verified": false,
  "priority": 0,
  "created_at": "2026-02-21T10:00:00Z"
}

Config Schemas

Type	Required Config Fields
email	smtp_host, smtp_port, username, password, from_address
sms	provider, api_key_sid, api_key_secret, from_number
whatsapp	provider, access_token, phone_number_id, business_account_id
telegram	provider, bot_token

Errors

• 400 — Validation error
• 409 — Duplicate type+name

---

PUT /api/connectors/:id

Update a connector.

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request

{
  "name": "SMTP Updated",
  "priority": 1
}

Partial updates allowed. Include only fields to change.

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "email",
  "name": "SMTP Updated",
  "is_verified": true,
  "priority": 1,
  "created_at": "2026-02-21T10:00:00Z"
}

---

DELETE /api/connectors/:id

Delete a connector.

Headers

Authorization: Bearer <access_token>

Response (204 No Content)

No body returned.

Errors

• 409 — Cannot delete last connector when will is active

---

POST /api/connectors/:id/test

Test a connector by sending a test message.

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request

{
  "test_destination": "+1234567890"
}

Response (200 OK)

{
  "success": true,
  "message": "Test message sent successfully",
  "delivery_time_ms": 1250
}

Errors

• 400 — Invalid destination
• 502 — Connector delivery failed

---

Rate Limits

Endpoint	Limit	Window
GET /connectors	100 requests	1 minute
POST /connectors	10 requests	1 hour
POST /connectors/:id/test	10 requests	1 hour

---

Example: Create Email Connector

curl -X POST "https://api.example.com/api/connectors" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "name": "SMTP Email",
    "config": {
      "smtp_host": "smtp.example.com",
      "smtp_port": 587,
      "username": "your-username",
      "password": "your-password",
      "from_address": "noreply@yourdomain.com"
    },
    "priority": 0
  }'

Example: Test Connector

curl -X POST "https://api.example.com/api/connectors/550e8400-e29b-41d4-a716-446655440001/test" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"test_destination": "test@example.com"}'

---

Related Endpoints

• Storage API — Storage backend management
• Authentication — Login