Messages

Send email, WhatsApp, and SMS messages through a single unified endpoint. SendPipe routes each message through your configured providers with automatic failover.

Endpoints

POST

/v1/messages/channel

Send a message on any channel (email, whatsapp, sms)

GET

/v1/messages

List messages with pagination and filters

GET

/v1/messages/:id

Get message details with delivery events

DELETE

/v1/messages/:id/cancel

Cancel a queued message

Send Email

Request Body

Name	Type	Required	Description
`channel`	string	Yes	"email"
`from`	string	No	Sender email address (must be from a verified domain). Falls back to project default sender if omitted.
`to`	string[]	Yes	Array of recipient email addresses
`subject`	string	Yes	Email subject line
`html`	string	No	HTML body (provide html or text, or both)
`text`	string	No	Plain text body
`cc`	string[]	No	CC recipients
`bcc`	string[]	No	BCC recipients
`reply_to`	string	No	Reply-to address
`attachments`	object[]	No	Array of attachments (see Attachments section below)
`tags`	string[]	No	Tags for filtering and analytics
`idempotency_key`	string	No	Unique key to prevent duplicate sends (valid 24h)

curl -X POST https://api.sendpipe.io/v1/messages/channel \
  -H "X-SendPipe-Key: sp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "from": "noreply@yourapp.com",
    "to": ["user@example.com"],
    "cc": ["manager@example.com"],
    "bcc": ["audit@yourapp.com"],
    "reply_to": "support@yourapp.com",
    "subject": "Order Confirmation",
    "html": "<h1>Order #1234 confirmed</h1>",
    "tags": ["transactional", "orders"],
    "idempotency_key": "order-1234-confirm"
  }'

Send WhatsApp

Request Body

Name	Type	Required	Description
`channel`	string	Yes	"whatsapp"
`to`	string[]	Yes	Phone numbers in E.164 format (e.g., +2348012345678)
`channel_options.template_name`	string	Yes	WhatsApp template name (approved in your WABA)
`channel_options.template_language`	string	Yes	Template language code (e.g., "en")
`channel_options.template_params`	string[]	No	Dynamic template parameters

json

{
  "channel": "whatsapp",
  "to": ["+2348012345678"],
  "channel_options": {
    "template_name": "order_confirmation",
    "template_language": "en",
    "template_params": ["ORD-4821", "$129.00"]
  }
}

Send SMS

Request Body

Name	Type	Required	Description
`channel`	string	Yes	"sms"
`from`	string	Yes	Sender ID or phone number
`to`	string[]	Yes	Phone numbers in E.164 format
`text`	string	Yes	SMS message body

json

{
  "channel": "sms",
  "from": "YourApp",
  "to": ["+14155551234"],
  "text": "Your verification code is 483921"
}

Attachments

Attach files to email messages by including an attachments array. File content must be base64-encoded.

Attachment Object

Name	Type	Required	Description
`filename`	string	Yes	File name (e.g., "invoice.pdf")
`content`	string	Yes	Base64-encoded file content
`content_type`	string	No	MIME type (e.g., "application/pdf"). Auto-detected if omitted.
`encoding`	string	No	"base64" (default) or "utf-8"

curl -X POST https://api.sendpipe.io/v1/messages/channel \
  -H "X-SendPipe-Key: sp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "from": "billing@yourapp.com",
    "to": ["client@example.com"],
    "subject": "Your Invoice",
    "html": "<p>Please find your invoice attached.</p>",
    "attachments": [
      {
        "filename": "invoice-2026-03.pdf",
        "content": "JVBERi0xLjQK...",
        "content_type": "application/pdf"
      }
    ]
  }'

Response

json

{
  "id": "msg_abc123def456",
  "project_id": "proj_xyz789",
  "status": "queued",
  "channel": "email",
  "created_at": "2026-03-27T10:00:00Z"
}

Message Lifecycle

QUEUED→SENDING→SENT→DELIVERED

Messages can also move to: BOUNCED, SOFT_BOUNCE, FAILED, or COMPLAINED.

List Messages

Query Parameters

Name	Type	Required	Description
`status`	string	No	Filter by status (QUEUED, SENT, DELIVERED, FAILED, etc.)
`channel`	string	No	Filter by channel (email, whatsapp, sms)
`from`	string	No	Filter by sender address
`to`	string	No	Filter by recipient address
`limit`	number	No	Page size (default: 20, max: 100)
`cursor`	string	No	Cursor for pagination

bash

curl "https://api.sendpipe.io/v1/messages?status=DELIVERED&limit=10" \
  -H "X-SendPipe-Key: sp_live_xxx"