Templates and campaigns are created in the dashboard, not through the API. The API lets you send messages (with inline content or a template_id), trigger and pause campaigns, and retrieve message history — but the flow builder and template editor are dashboard-only tools. See Identifiers to find template and campaign IDs for use in API calls.

​
How messaging works

Every message follows the same lifecycle regardless of channel:
1

You send — POST /v1/messages

Your server calls POST /v1/messages with your content and recipient. The platform validates your balance, verifies the channel is active, and places a billing hold. You receive a message_id immediately.
2

Platform queues and dispatches

The message is dispatched to the channel provider (the carrier network for RCS/SMS, the email infrastructure for email). This is asynchronous — the API returns queued straight away, not delivered.
3

You receive delivery events — via webhook

As the message moves through its lifecycle, events fire to your registered webhook endpoint: message.delivered, message.read, message.failed, etc. This is how you know the message was delivered — not from the original send response.
4

For RCS: user replies come in as webhook events too

When the user replies to your RCS message, the reply arrives at your webhook as a conversation.started event. A 24-hour session is now open for that agent + phone number pair. You can then send follow-up messages using message_type: CONVERSATION within that window.
Email is one-directional from the API perspective — you send, and you receive delivery status events (delivered, bounced, opened, clicked). There is no inbound email reply flow through this API.

​
Send a message

POST /v1/messages
All sends use this single endpoint. The channel is determined by which identifier you include in the body:
ChannelKey discriminators
Emailchannel_id + to (email address)
RCSagent_id + to (phone number)
SMSchannel_id + to (phone number)

​
Required headers

​
Authorization
string
required
Bearer <api_key> — see Authentication.
​
Idempotency-Key
string
A UUID to prevent duplicate sends on retry. Always include this for message sends.
​
Content-Type
string
required
application/json

​
Send response

The API responds immediately. status: "queued" means the message was accepted — not that it was delivered. Delivery confirmation comes via webhook. 
{
  "message_id": "msg_a1b2c3d4",
  "status": "queued",
  "created_at": "2026-03-27T14:30:00Z",
  "billing": {
    "channel": "RCS",
    "message_type": "basic_message",
    "hold_amount": 0.08,
    "message_price": 0.08,
    "balance": {
      "free": 49.92,
      "reserved": 0.08,
      "total": 50.0
    },
    "tier": {
      "channel": "RCS",
      "current": "tier_1",
      "volume_used": 12501
    }
  }
}
​
message_id
string
Save this. Use it to track status via GET /v1/messages/{id} and to correlate incoming webhook events.
​
status
string
Always queued on the send response. Final states (delivered, failed, etc.) arrive via webhook or GET /v1/messages/{id}.
​
billing.hold_amount
number
Balance reserved until delivery resolves. Released on failure; charged on success.
​
billing.message_price
number
Expected unit price for this message classification and tier. Equal to hold_amount on queued sends.

​
Send errors

StatusMeaningWhat to do
400Invalid payloadCheck details[] for field-level errors
402Insufficient balanceTop up via topup_url in the response
403Channel not authorisedSending domain not verified or RCS agent not approved
404Device not RCS-capableDevice capability is checked automatically at send time
422Consent / suppressionMissing or revoked consent, or recipient suppressed — see Consent API
429Rate limitBack off using retry_after seconds

​
Track delivery

Register a webhook endpoint and subscribe to delivery events. The platform pushes updates to your URL as they happen. Every event uses the same envelope: 
{
  "id": "evt_z9y8x7",
  "event": "message.delivered",
  "timestamp": "2026-03-27T14:30:05Z",
  "data": {
    "message_id": "msg_a1b2c3d4",
    "delivered_at": "2026-03-27T14:30:05Z"
  }
}
RCS and SMS delivery events use message.* names. Email delivery events use email.* names — email.delivered, email.bounced, email.opened, email.clicked. Subscription names matter: an endpoint subscribed to message.delivered will not receive email.delivered. See the Event types catalogue for the full list.
Key RCS / SMS delivery events:
EventMeaning
message.deliveredConfirmed delivery to the device
message.readUser opened the message (RCS only)
message.failedPermanent failure — hold released, not charged
message.expiredTTL elapsed before delivery — hold released
Key Email delivery events:
EventMeaning
email.deliveredAccepted by recipient mail server
email.bouncedHard or soft bounce received
email.openedOpen tracking pixel fired
email.clickedTracked link clicked

​
Option B — Poll GET /v1/messages/{id}

Poll the status endpoint to get the current state and full event timeline. Useful for debugging or one-off checks, but webhooks are more efficient for production. 
{
  "message_id": "msg_a1b2c3d4",
  "status": "delivered",
  "events": [
    { "type": "queued",    "at": "2026-03-27T14:30:00Z" },
    { "type": "sent",      "at": "2026-03-27T14:30:01Z" },
    { "type": "delivered", "at": "2026-03-27T14:30:05Z" }
  ]
}
See Revoke & status for full field documentation.

​
Receive user replies (RCS only)

When an RCS user replies to your message, the platform fires a webhook event to your endpoint. You do not poll for replies — they are pushed to you. 
{
  "id": "evt_a1b2c3",
  "event": "conversation.started",
  "timestamp": "2026-03-27T14:31:00Z",
  "data": {
    "agent_id": "ag_live_xxxx",
    "from": "+4917612345678",
    "session_expires_at": "2026-03-28T14:31:00Z",
    "user_message": {
      "type": "text",
      "text": "Yes, I'm interested!"
    }
  }
}
Once a session is open, you have 24 hours to send follow-up messages using message_type: CONVERSATION. Sends within this window use Conversation billing — see RCS conversation for the full session model.
Always store the phone + agent_id pair from a conversation.started event so your system knows an active session is open for that user.

​
Choose your send type

​
Email

Action-based email

MESSAGE — triggered by a user action or system event. No consent required beyond channel setup.

Subscription email

NEWSLETTER — opted-in list sends. Consent enforced at send time.

​
RCS

Text

Plain text — Basic or Single depending on length and chips.

Rich card

Image, title, description, action chips — always Single.

Carousel

2–10 cards in a horizontal scroll.

Conversation

Reply within a 24-hour session opened by a user reply — Conversation billing.

Newsletter

Opted-in bulk sends — MAU billing per subscriber per month.

​
SMS

SMS send is coming soon. Phone numbers (Mobile and Landline) can be purchased today via the dashboard — see SMS overview.

Revoke & status

Cancel a queued message or check its full delivery timeline.

Webhooks

Register endpoints, verify signatures, and see the full event catalogue.

RCS platform

Agents, messaging, and delivery tracking.

Billing units

How message types map to billing charges.

Conventions

Rate limits, idempotency, and error envelopes.