Send SMS through one gateway
Apps send SMS requests to this Worker using an account app API key. The gateway validates the request,
stores the message, queues delivery, and sends through active provider profiles such as Fast2SMS and 2Factor.
Endpoint active on this deployment
Quick Start
- Create or select an account in the dashboard.
- Add at least one app key for that account.
- Add sender IDs if you want to restrict API callers to approved DLT headers.
- Add at least one active provider profile, such as Fast2SMS or 2Factor.
- Call
POST /api/v1/send with the app key in the Authorization header.
Authentication
Every API request uses a gateway app API key. The key is shown only once when you create an app key in the dashboard.
| Header | Value |
|---|
Authorization | Bearer YOUR_APP_API_KEY |
Content-Type | application/json |
Do not expose app API keys in public frontend code. Keep them in backend environment variables.
Send Endpoint
| Method | Path | Description |
|---|
POST | /api/v1/send | Queue an SMS for delivery. |
Payload Reference
| Field | Required | Description |
|---|
to | Yes | One phone number or an array of phone numbers. Use E.164 style, for example +919876543210. |
message | Yes | SMS body. Keep the text aligned with your approved DLT template when required. |
messageType | No | transactional, otp, or promotional. Defaults to transactional. |
senderId | No | DLT sender/header. If omitted, the provider profile default is used. |
templateId | No | DLT template ID for providers/routes that require it. |
entityId | No | DLT entity ID. Request value overrides the provider profile default. |
variables | No | Named template values passed to provider adapters. |
idempotencyKey | No | Prevents duplicate queued messages for the same app key and key. |
Full JSON example
Provider Setup
| Provider | Credential fields | Notes |
|---|
fast2sms | apiKey, optional endpoint | Transactional messages use the DLT manual route, OTP uses OTP route, promotional uses quick route. |
twofactor | apiKey, optional smsEndpoint, otpEndpoint, templateName | Endpoint overrides are available because 2Factor account/API versions can differ. |
Examples
cURL
JavaScript fetch
Node.js service function
Python requests
PHP cURL
Responses
| Status | Meaning |
|---|
202 | Message accepted and queued. |
200 | Same idempotency key was already used and the existing message was returned. |
400 | Invalid payload or sender ID is not configured. |
401 | Missing or invalid app API key. |
404 | Active app key was not found. |
Error Handling
Errors return a JSON object with an error message. Failed sends are visible in the dashboard and metrics pages.
Recommended Practices
- Use
idempotencyKey for OTPs, alerts, payment events, and any retryable workflow.
- Keep account-specific app keys so each application can be paused or revoked independently.
- Maintain provider failover by configuring more than one active profile per account.
- Match message text, template ID, sender ID, and entity ID with your DLT approvals.
- Use
transactional as the default message type; set otp or promotional only when needed.