Developers / API

SMTP relay

Send mail from ESPs, MTAs, and apps that speak SMTP. Point your client at the relay host below, pick port 587 or 2525, enable STARTTLS when your mail stack supports it, and authenticate with SMTP credentials for your organization. Create and rotate credentials in Email and SMTP Operations after signing in.

Endpoint

smtp.commtunnel.cloud

Ports

587 — submission (use STARTTLS)

2525 — alternate submission port (same relay; enable STARTTLS when your client supports it)

Workspace session APIs for the control plane use /v1/emails, /v1/sms, and /v1/whatsapp (WhatsApp Cloud send, list, status, timeline) and /v1/account/whatsapp-cloud-line (organization Meta phone number id override; session + members:read / members:write). External integrations use scoped API keys against /v1/public/emails, /v1/public/sms, and /v1/public/whatsapp (scopes send:whatsapp / read:whatsapp; see OpenAPI). Customer webhooks deliver email lifecycle events, sms_* and whatsapp_* delivery signals, and sms_opt_out when subscribers add or remove handset opt-outs. Artifacts include OpenAPI, Postman, and webhook verification guidance for implementation-safe adoption.

SMS sends now require an organization-approved sender ID in request payloads (senderId on POST /v1/sms/send). Organizations submit sender ID requests via POST /v1/sms/sender-id-requests, then platform admins review via POST /v1/sms/sender-id-requests/:requestId/review. Approved values are listed at GET /v1/sms/sender-ids.

For operational listing, GET /v1/sms supports query filters:flow=OTP|STANDARD, status=QUEUED|PROCESSING|SENT|DELIVERED|FAILED, free-text query (recipient/body/external id), plus pagination with page and pageSize (max 100).

• OTP-only first page: GET /v1/sms?flow=OTP&page=1&pageSize=10
• Standard messages with delivery status: GET /v1/sms?flow=STANDARD&status=DELIVERED&page=1&pageSize=50
• Search recipient/body/external id: GET /v1/sms?query=2348067&page=1&pageSize=10

SMS event delivery

Provider callback ingestion and delivery receipt routing are internal platform implementation details. Integrators should consume normalized customer webhook events (for example sms_queued, sms_sent, sms_delivered, sms_failed, and sms_opt_out) rather than provider-facing ingress paths.

WhatsApp Cloud API (Meta) webhooks

Configure the callback URL on your Meta app to https://<API>/v1/webhooks/whatsapp. Use WHATSAPP_VERIFY_TOKEN for the GET verification handshake and WHATSAPP_APP_SECRET for X-Hub-Signature-256 on POST. Enable with WHATSAPP_CLOUD_API_ENABLED and set access token / phone number id (see .env.example). Default outbound line: platform WHATSAPP_PHONE_NUMBER_ID. Organizations can override in Settings (stored on the organization). Optional WHATSAPP_LINE_MAP maps Meta phone_number_id to organizationId for advanced routing.

WhatsApp Business line (workspace session)

Authenticated workspace members manage the dedicated Meta phone_number_id used for outbound sends when set; otherwise sends use the platform default from env. These routes are not in the public OpenAPI bundle (session JWT or equivalent).

• GET /v1/account/whatsapp-cloud-line — Returns whatsappPhoneNumberId, usesPlatformDefault, and platformLineConfigured. Requires members:read.
• PATCH /v1/account/whatsapp-cloud-line — JSON body with whatsappPhoneNumberId (string | null) and/or whatsappAccessToken (string | null). At least one field required; null clears that value. Token is stored encrypted (same key material as DKIM secret encryption). Requires members:write. Conflict 409 when the phone number id is already bound to another organization (WHATSAPP_PHONE_NUMBER_ID_IN_USE).