Skip to content
Helpdox
Relay API

Documentation

Browse all docs →
Search docs…⌘K
Open a ticket
v3Latest
Feedback

Send SMS, email and push with one call

One endpoint, three channels: set <code>channel</code> and Relay handles formatting, retries and fallbacks.

2 min read v3

On this page

One endpoint, three channels: set channel and Relay handles formatting, retries and fallbacks. Follow the steps below — it takes just a few minutes.

Before you begin#

  • A Relay account and a test-mode API key
  • curl or one of the official SDKs

Steps#

  1. Choose a channel#

    sms, email or push.

  2. Add a fallback#

    Set fallback: "email" to email the user if SMS fails.

  3. Track delivery#

    Each attempt appears in events on the message.

Tip

Use idempotency keys so a retried request never sends twice.

POST/v3/messages

Create a message#

Queues a message on one channel, with an optional fallback channel.

Requires messages:write

Parameters

channelstringrequired
sms, email or push.
tostringrequired
Phone number in E.164 format, email address or device token.
bodystringrequired
Message text. SMS longer than 160 characters is split.
fallbackstring
Channel to try if the first one fails.
send_atdatetime
Schedule for later (ISO 8601).
POST /v3/messages
curl https://api.relay.example/v3/messages \
  -H "Authorization: Bearer $RELAY_KEY" \
  -H "Idempotency-Key: order-1042-receipt" \
  -d channel=sms -d fallback=email \
  -d to=+15550100001 -d body="Order #1042 shipped"
Response202 Accepted
{
  "id": "msg_7Hq2kD",
  "channel": "sms",
  "status": "queued",
  "fallback": "email",
  "created_at": "2026-10-12T16:04:11Z"
}

Still stuck?#

Include the request ID from the Relay-Request-Id response header — it lets us find your call in seconds.

Was this article helpful?

Related articles