Messages (SMS/MMS)

Send outbound SMS and MMS messages, retrieve message logs, and inspect delivery statuses using your workspace phone numbers.

Firetell handles carrier dispatch, delivery receipts (DLR), and real-time event updates via Webhooks and Server-Sent Events (SSE).

Endpoints

Method	Endpoint	Description
`POST`	`/messages/send`	Send an outbound SMS or MMS message
`GET`	`/messages`	List message history with filters and pagination
`GET`	`/messages/:id`	Retrieve detailed information for a single message

The Message Object

Field	Type	Description
`id`	`string`	Unique message identifier prefixed with `msg_` (e.g. `msg_05f18045cba1452204774f`)
`workspace_id`	`string`	Workspace identifier (e.g. `yourcompany`)
`phone_number_id`	`string`	Identifier of the workspace phone number used (`pn_...`)
`from`	`string`	Sender phone number in E.164 format (e.g. `+13074295456`)
`to`	`string`	Recipient phone number in E.164 format (e.g. `+18647123123`)
`body`	`string`	Text content of the message (up to 1,600 characters)
`direction`	`string`	Direction of the message: `outbound` or `inbound`
`status`	`string`	Current delivery status (see Message Statuses)
`cost`	`number`	Total cost charged in USD including platform markup (or `null` if inbound or pending)
`media_urls`	`string[]`	Array of media attachment URLs for MMS messages
`error_code`	`string`	Error code returned by carrier if sending/delivery failed (e.g. `40001`, or `null`)
`error_message`	`string`	Human-readable error message explaining failure reason (or `null`)
`created_at`	`string`	ISO 8601 creation timestamp
`updated_at`	`string`	ISO 8601 last update timestamp

Message Statuses

Status	Direction	Description
`queued`	`outbound`	Message has been accepted by Firetell and queued for carrier delivery.
`sending`	`outbound`	Message is currently being processed by the carrier adapter.
`sent`	`outbound`	Carrier has accepted and dispatched the message to the destination network.
`delivered`	`outbound`	Delivery Receipt (DLR) received confirming delivery to the recipient's handset.
`failed`	`outbound`	Message could not be sent or delivered (see `error_code` and `error_message`).
`undelivered`	`outbound`	Carrier could not confirm delivery within the standard timeout window.
`received`	`inbound`	Incoming SMS/MMS received on your workspace phone number.

Send Message

POST /messages/send

Queue an outbound SMS or MMS message for delivery.

Authentication

Requires ApiKey with owner or editor role.

Request Headers

Header	Type	Description
`Authorization`	`string`	`ApiKey sk-YOUR_API_KEY`
`Content-Type`	`string`	`application/json`

Request Body

Field	Type	Required	Description
`from`	`string`	Yes	Sender phone number in E.164 format. Must belong to the workspace and have `sms` capability.
`to`	`string`	Yes	Destination phone number in E.164 format.
`body`	`string`	Yes	Text content of the message (maximum 1,600 characters).
`media_urls`	`string[]`	No	Array of publicly accessible media URLs (JPEG, PNG, GIF, audio) to send as an MMS message.

Requirements & Validations

Phone Number Capability: The sender number specified in from must belong to your workspace and have sms listed in its capabilities.
Account Credit Balance: Your workspace must maintain an available credit balance of at least $0.01 to initiate outbound SMS sends.
Format: Phone numbers must adhere to the standard international E.164 format (e.g. +13074295456).

Rate Limiting

The POST /messages/send endpoint operates on a dedicated SMS rate limit tier:

Tier	Window	Limit	Scope
`sms`	60 seconds (1 min)	30 req/min	Per API Key (`ApiKey`) or agent/user account

This dedicated quota prevents outbound SMS sending from exhausting your workspace's general REST API rate limit (100 req/min).

note

Need higher limits?

Enterprise customers can request custom rate limits. Contact us at enterprise@firetell.com with your workspace ID and use case.

Example Request

curl -X POST "https://{workspace_id}.firetell.app/api/v1/messages/send" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+13074295456",
    "to": "+18647123123",
    "body": "Your appointment is confirmed for tomorrow at 10:00 AM."
  }'

Example Request with MMS Media

curl -X POST "https://{workspace_id}.firetell.app/api/v1/messages/send" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+13074295456",
    "to": "+18647123123",
    "body": "Here is your digital receipt.",
    "media_urls": [
      "https://storage.yourcompany.com/receipts/inv_9981.png"
    ]
  }'

Response (`201 Created`)

{
  "id": "msg_05f18045cba1452204774f",
  "workspace_id": "yourcompany",
  "phone_number_id": "pn_e71c8caddbe5603f1d0522",
  "from": "+13074295456",
  "to": "+18647123123",
  "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
  "direction": "outbound",
  "status": "queued",
  "media_urls": [],
  "cost": null,
  "error_code": null,
  "error_message": null,
  "created_at": "2026-09-26T00:00:00.000Z",
  "updated_at": "2026-09-26T00:00:00.000Z"
}

tip

Delivery Tracking

When you submit a message, it is returned immediately with status: "queued". You do not need to poll for updates — register a Webhook for message.sent and message.delivered to receive real-time carrier delivery confirmations.

List Messages

GET /messages

Retrieve a paginated history of all inbound and outbound messages with rich search and filtering options.

Authentication

Requires ApiKey with any scope.

Query Parameters

Parameter	Type	Default	Description
`page`	`number`	`1`	Page number (minimum: 1).
`limit`	`number`	`20`	Number of records per page (maximum: 100).
`search`	`string`	—	Case-insensitive search matching sender (`from`), recipient (`to`), or text content (`body`).
`direction`	`string`	—	Filter by direction: `outbound` or `inbound`.
`status`	`string`	—	Filter by status: `queued`, `sending`, `sent`, `delivered`, `failed`, `undelivered`, or `received`.
`phone_number_id`	`string`	—	Filter messages associated with a specific workspace phone number ID (`pn_...`).
`from`	`string`	—	Filter messages created on or after this ISO 8601 date (e.g. `2026-09-01T00:00:00Z`).
`to_date`	`string`	—	Filter messages created on or before this ISO 8601 date (e.g. `2026-09-30T23:59:59Z`).
`sort_field`	`string`	`created_at`	Sort field. Allowed values: `created_at`, `updated_at`, `status`.
`sort_order`	`string`	`desc`	Sort order: `asc` (oldest first) or `desc` (newest first).

Example Request

Filter for all delivered outbound messages sent in September 2026:

curl -X GET "https://{workspace_id}.firetell.app/api/v1/messages?direction=outbound&status=delivered&from=2026-09-01T00:00:00Z&page=1&limit=20" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"

Search Example

Search messages containing a specific customer phone number or keyword:

curl -X GET "https://{workspace_id}.firetell.app/api/v1/messages?search=appointment&limit=10" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"

Response (`200 OK`)

{
  "data": [
    {
      "id": "msg_05f18045cba1452204774f",
      "workspace_id": "yourcompany",
      "phone_number_id": "pn_e71c8caddbe5603f1d0522",
      "from": "+13074295456",
      "to": "+18647123123",
      "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
      "direction": "outbound",
      "status": "delivered",
      "cost": 0.0048,
      "media_urls": [],
      "error_code": null,
      "error_message": null,
      "created_at": "2026-09-26T00:00:00.000Z",
      "updated_at": "2026-09-26T00:00:05.000Z"
    },
    {
      "id": "msg_be52701819fa34a72ae414",
      "workspace_id": "yourcompany",
      "phone_number_id": "pn_99bf875464f1c096f46aff",
      "from": "+18647123123",
      "to": "+13074295456",
      "body": "Thank you! Can I reschedule for 11:00 AM instead?",
      "direction": "inbound",
      "status": "received",
      "cost": null,
      "media_urls": [],
      "error_code": null,
      "error_message": null,
      "created_at": "2026-09-26T00:01:10.000Z",
      "updated_at": "2026-09-26T00:01:10.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 20,
    "total_pages": 1
  }
}

Get Message

GET /messages/:id

Retrieve details and delivery status for a specific message by its unique ID.

Authentication

Requires ApiKey with any scope.

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	Message identifier (e.g. `msg_05f18045cba1452204774f`).

Example Request

curl -X GET "https://{workspace_id}.firetell.app/api/v1/messages/msg_05f18045cba1452204774f" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"

Response (`200 OK`)

{
  "id": "msg_05f18045cba1452204774f",
  "workspace_id": "yourcompany",
  "phone_number_id": "pn_e71c8caddbe5603f1d0522",
  "from": "+13074295456",
  "to": "+18647123123",
  "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
  "direction": "outbound",
  "status": "delivered",
  "cost": 0.0048,
  "media_urls": [],
  "error_code": null,
  "error_message": null,
  "created_at": "2026-09-26T00:00:00.000Z",
  "updated_at": "2026-09-26T00:00:05.000Z"
}

Error Responses

`404 Not Found`

Returned when the message ID does not exist in the requested workspace:

{
  "statusCode": 404,
  "message": "Message msg_invalid_id not found",
  "error": "Not Found"
}

Webhook Notifications

Configure your system to receive real-time HTTP callbacks whenever messaging events occur. See the Webhook Event Catalog for sample event payloads:

Event	Trigger
`message.received`	An inbound SMS/MMS is received on your workspace phone number.
`message.sent`	An outbound message was accepted and sent to the carrier network.
`message.delivered`	A delivery receipt (DLR) confirmed successful delivery to the recipient.
`message.failed`	An outbound message failed to send or deliver (includes carrier error codes).
`message.undelivered`	Delivery could not be confirmed by the carrier within the receipt window.

Endpoints​

The Message Object​

Message Statuses​

Send Message​

Authentication​

Request Headers​

Request Body​

Requirements & Validations​

Rate Limiting​

Example Request​

Example Request with MMS Media​

Response (201 Created)​

List Messages​

Authentication​

Query Parameters​

Example Request​

Search Example​

Response (200 OK)​

Get Message​

Authentication​

Path Parameters​

Example Request​

Response (200 OK)​

Error Responses​

404 Not Found​

Webhook Notifications​

Endpoints

The Message Object

Message Statuses

Send Message

Authentication

Request Headers

Request Body

Requirements & Validations

Rate Limiting

Example Request

Example Request with MMS Media

Response (`201 Created`)

List Messages

Authentication

Query Parameters

Example Request

Search Example

Response (`200 OK`)

Get Message

Authentication

Path Parameters

Example Request

Response (`200 OK`)

Error Responses

`404 Not Found`

Webhook Notifications