Relay SMS Platform
Relay SMS API

Messages

Endpoint

Send and retrieve SMS messages

List messages

GET
https://api.relay.works
/v1/messages

Retrieve a paginated list of messages

List messages › query Parameters

  • pageinteger · min: 1

    Page number

    Default: 1
  • limitinteger · min: 1 · max: 100

    Number of messages per page

    Default: 20
  • statusstring · enum

    Filter by message status

    Enum values:
    queued
    pending
    sent
    delivered
    failed
  • directionstring · enum

    Filter by direction

    Enum values:
    inbound
    outbound

List messages › Responses

List of messages

  • dataobject[]
  • paginationobject

Send SMS message

POST
https://api.relay.works
/v1/messages

Send an SMS message to a recipient.

Note: Starter tier users cannot use this endpoint and will receive a 402 error. Starter tier must use POST /v1/messages/send-template with approved templates.

Idempotency: supply an Idempotency-Key header to make retries safe. See the idempotency guide.

Send SMS message › Headers

  • Idempotency-Keystring · minLength: 1 · maxLength: 255

    Client-generated key (1-255 chars). Retries with the same key + same body replay the first response.

Send SMS message › Request Body

  • tostring · required

    Recipient phone number in E.164 format

    Example: +15551234567
  • fromstring · required

    Sender phone number

    Example: +14155551234
  • messagestring · required

    Message content (max 1600 characters)

    Example: Hello from Relay!

Send SMS message › Responses

Message created successfully

  • idstring · required
    Example: msg_kL9mN2pQ4rS6tU8vW0xY
  • tostring · required
    Example: +15551234567
  • fromstring · required
    Example: +19285979076
  • messagestring · required
    Example: Hello from Relay!
  • statusstring · enum · required
    Enum values:
    queued
    pending
    sent
    delivered
    failed
    Example: queued
  • directionstring · enum · required
    Enum values:
    inbound
    outbound
    Example: outbound
  • created_atstring · date-time · required
    Example: 2024-01-15T10:30:00Z
  • aws_message_idstring
    Example: us-east-1/abc123def456

Send template message

POST
https://api.relay.works
/v1/messages/send-template

Send an SMS message using an approved template.

Required for Starter tier. Growth tier and above can optionally use templates for compliance.

Idempotency: supply an Idempotency-Key header to make retries safe. See the idempotency guide.

Send template message › Headers

  • Idempotency-Keystring · minLength: 1 · maxLength: 255

    Client-generated key (1-255 chars). Retries with the same key + same body replay the first response.

Send template message › Request Body

  • templatestring · required

    Template identifier

    Example: authentication
  • tostring · required

    Recipient phone number in E.164 format

    Example: +15551234567
  • fromstring

    Sender phone number (optional, uses shared number for Starter tier)

    Example: +19285979076
  • dataobject

    Template variables

    Example: {"code":"123456"}
  • variantstring

    Template variant (e.g., "en", "es")

    Example: en
  • fallbackstring

    Fallback message if template unavailable

    Example: Your code is: 123456
  • metadataobject

    Custom metadata

    Example: {"user_id":"user_123"}

Send template message › Responses

Template message created successfully

  • idstring · required
    Example: msg_kL9mN2pQ4rS6tU8vW0xY
  • tostring · required
    Example: +15551234567
  • fromstring · required
    Example: +19285979076
  • messagestring · required
    Example: Hello from Relay!
  • statusstring · enum · required
    Enum values:
    queued
    pending
    sent
    delivered
    failed
    Example: queued
  • directionstring · enum · required
    Enum values:
    inbound
    outbound
    Example: outbound
  • created_atstring · date-time · required
    Example: 2024-01-15T10:30:00Z
  • aws_message_idstring
    Example: us-east-1/abc123def456

Get message details

GET
https://api.relay.works
/v1/messages/{message_id}

Retrieve details for a specific message

Get message details › path Parameters

  • message_idstring · required

    Message ID

    Example: msg_kL9mN2pQ4rS6tU8vW0xY

Get message details › Responses

Message details

  • idstring · required
    Example: msg_kL9mN2pQ4rS6tU8vW0xY
  • tostring · required
    Example: +15551234567
  • fromstring · required
    Example: +19285979076
  • messagestring · required
    Example: Hello from Relay!
  • statusstring · enum · required
    Enum values:
    queued
    pending
    sent
    delivered
    failed
    Example: queued
  • directionstring · enum · required
    Enum values:
    inbound
    outbound
    Example: outbound
  • created_atstring · date-time · required
    Example: 2024-01-15T10:30:00Z
  • aws_message_idstring
    Example: us-east-1/abc123def456
API Keys