Sending SMS Messages

Send SMS messages to recipients with support for scheduling, templates, and drafts.

WARNING

SMS Live Mode Only: All SMS endpoints require a live mode API key (sk_live_*). Test API keys will not work for SMS operations.

Send SMS

Send an SMS message to a recipient.

Endpoint: POST /v1/sms

Authentication: Required (live API key)

Request Body:

Field	Type	Required	Description
`recipient_phone`	string	Yes*	Recipient phone number in E.164 format (e.g., `+2207654321`)
`contact_id`	string	Yes*	Contact ID (alternative to `recipient_phone`)
`message_body`	string	Yes**	SMS message text (required if `template_id` not provided)
`template_id`	string	Yes**	Template ID to use (required if `message_body` not provided)
`template_params`	object	No	Template parameters for variable substitution
`sender_id`	string	No	Custom sender ID
`scheduled_at`	string	No	Schedule message for future delivery (ISO 8601 format)
`is_draft`	boolean	No	Save as draft without sending (default: `false`)

*Either recipient_phone or contact_id must be provided
**Either message_body or template_id must be provided

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "id": "sms_abc123",
    "organization_id": "org_test123",
    "recipient_phone": "+2207654321",
    "message_body": "Hello! This is a test message from Jokoor.",
    "sender_id_used": "Jokoor",
    "status": "queued",
    "segments": 1,
    "cost": "0.25",
    "scheduled_at": null,
    "contact_id": null,
    "campaign_id": null,
    "template_id": null,
    "provider_message_id": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Error Response (402 - Insufficient Credits):

{
  "error": "Insufficient SMS credits. Please top up your account."
}

TIP

Scheduling Messages: Use the scheduled_at field to schedule messages for future delivery. The time must be in ISO 8601 format (e.g., 2024-12-25T10:00:00Z).

Get SMS Message

Retrieve details of a specific SMS message.

Endpoint: GET /v1/sms/{id}

Authentication: Required

Path Parameters:

Parameter	Type	Required	Description
`id`	string	Yes	SMS message ID

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "id": "sms_abc123",
    "organization_id": "org_test123",
    "recipient_phone": "+2207654321",
    "message_body": "Hello! This is a test message.",
    "sender_id_used": "Jokoor",
    "status": "delivered",
    "segments": 1,
    "cost": "0.25",
    "provider_message_id": "provider_msg_123",
    "sent_at": "2024-01-15T10:30:15Z",
    "delivered_at": "2024-01-15T10:31:00Z",
    "scheduled_at": null,
    "contact_id": null,
    "campaign_id": null,
    "template_id": null,
    "error_message": null,
    "metadata": {},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:31:00Z"
  }
}

Message Statuses:

draft - Saved as draft, not sent

pending - Pending submission

queued - Queued for sending

sending - Currently being sent

sent - Successfully sent to provider

delivered - Confirmed delivered to recipient

failed - Failed to send

undelivered - Sent but not delivered

cancelled - Cancelled before sending

List SMS Messages

Get a paginated list of SMS messages.

Endpoint: GET /v1/sms

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
`offset`	integer	No	Number of items to skip (default: 0)
`limit`	integer	No	Maximum number of items to return (default: 20, max: 100)
`status`	string	No	Filter by status (`draft`, `pending`, `queued`, `sending`, `sent`, `delivered`, `failed`, `undelivered`, `cancelled`)
`contact_id`	string	No	Filter by contact ID
`start_date`	string	No	Filter messages created after this date (ISO 8601)
`end_date`	string	No	Filter messages created before this date (ISO 8601)

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "items": [
      {
        "id": "sms_abc123",
        "organization_id": "org_test123",
        "recipient_phone": "+2207654321",
        "message_body": "Hello!",
        "sender_id_used": "Jokoor",
        "status": "delivered",
        "segments": 1,
        "cost": "0.25",
        "delivered_at": "2024-01-15T10:31:00Z",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "count": 1,
    "offset": 0,
    "limit": 10
  }
}

Sending SMS Messages

Send SMS#

Get SMS Message#

List SMS Messages#

Send SMS

Get SMS Message

List SMS Messages