API Reference
Messages
Send messages, check delivery status, list history, and manage bulk jobs.
POST /api/v1/messages
Send a message.
Request
| Field | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Phone number (E.164), Apple ID email, or group GUID |
body | string | Conditional | Message text. Required unless attachments is provided. |
attachments | string[] | No | Attachment URLs. Maximum 10. |
priority | number | No | 0–100. Higher = processed first. Default 0. |
fromNumber | string | No | Send from a specific registered phone number. |
Response 201
{
"id": "msg_abc123",
"status": "queued",
"to": "+15551234567",
"body": "Hello!",
"priority": 0,
"createdAt": "2025-01-15T10:30:00Z"
}GET /api/v1/messages
List sent and received messages.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
direction | string | — | sent or received |
participant | string | — | Filter by phone number or email |
page | number | 1 | Page number |
limit | number | 20 | Results per page (1–100) |
Response 200
Paginated list of messages.
GET /api/v1/messages/:id/status
Check delivery status of a message.
Response 200
{
"id": "msg_abc123",
"status": "delivered",
"attempts": 1,
"lastError": null,
"queuedAt": "2025-01-15T10:30:00Z",
"sentAt": "2025-01-15T10:30:02Z",
"deliveredAt": "2025-01-15T10:30:05Z"
}GET /api/v1/messages/:id/attachments
List attachments for a message. Returns download URLs.
GET /api/v1/messages/queue/stats
Queue counts by state.
Response 200
{
"pending": 5,
"processing": 2,
"failed": 0,
"deadLetter": 1
}POST /api/v1/messages/bulk
Create a bulk message job.
Request
| Field | Type | Required | Description |
|---|---|---|---|
messages | object[] | Yes | Array of {to, body} objects |
Response 201
{
"jobId": "bulk_xyz789",
"status": "processing",
"totalRecipients": 50,
"createdAt": "2025-01-15T10:30:00Z"
}GET /api/v1/messages/bulk
List bulk jobs.
GET /api/v1/messages/bulk/:jobId
Get job details and progress.
GET /api/v1/messages/bulk/:jobId/results
Per-recipient delivery results for a completed job.