Messages

The messages API provides endpoints to list, retrieve, and delete messages from your account.

List Messages

GET /api/v2/messages

Retrieve messages with filtering and pagination.

Query Parameters

Parameter	Type	Default	Description
limit	integer	100	Results per page (1-100)
offset	integer	0	Pagination offset
order_by	string	createdAt	Sort field
order_direction	string	desc	asc or desc
status	string	—	Filter by status
service	string	—	iMessage, SMS, or RCS
is_outbound	boolean	—	true or false
message_type	string	—	message or group
from_number	string	—	Sender phone
to_number	string	—	Recipient phone
number	string	—	Either party’s phone
group_id	string	—	Filter by group
sendblue_number	string	—	Your Sendblue number
created_at_gte	string	—	Created after (ISO 8601)
created_at_lte	string	—	Created before (ISO 8601)
sent_at_gte	string	—	Sent after (ISO 8601)
sent_at_lte	string	—	Sent before (ISO 8601)

Example

curl "https://api.sendblue.co/api/v2/messages?service=iMessage&is_outbound=true&limit=50" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET"

Response

{
  "status": "OK",
  "data": [
    {
      "message_handle": "5a17319e-cbcf-443e-897e-d8b0c04b1b09",
      "accountEmail": "[email protected]",
      "content": "Hello",
      "from_number": "+15551234567",
      "to_number": "+19998887777",
      "number": "+19998887777",
      "status": "DELIVERED",
      "service": "iMessage",
      "is_outbound": true,
      "date_sent": "2025-01-15T10:30:00.000Z",
      "date_updated": "2025-01-15T10:30:05.000Z",
      "media_url": "",
      "was_downgraded": false,
      "message_type": "message",
      "group_id": "",
      "group_display_name": "",
      "send_style": ""
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1
  }
}

Get Message

GET /api/v2/messages/:message_id

Retrieve a single message by ID.

curl "https://api.sendblue.co/api/v2/messages/5a17319e-cbcf-443e-897e-d8b0c04b1b09" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET"

Delete Message

DELETE /api/message/:message_handle

Remove a message from the Sendblue database.

Note: This is a soft delete. It removes the message from Sendblue’s database only. It does not unsend or recall the message from the recipient’s device.

curl -X DELETE "https://api.sendblue.co/api/message/5a17319e-cbcf-443e-897e-d8b0c04b1b09" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET"

Response

{
  "status": "OK",
  "message": "Message deleted"
}

Message Statuses

Status	Description
QUEUED	Message queued for sending
PENDING	Message being processed
SENT	Message sent to carrier
DELIVERED	Message delivered to recipient
ERROR	Delivery failed
DECLINED	Message rejected by system
RECEIVED	Inbound message received
ACCEPTED	Message accepted for processing
SUCCESS	Message processed successfully
REGISTERED	Message registered in system

Message Object

Field	Type	Description
message_handle	string	Unique message ID
content	string	Message text
from_number	string	Sender phone (E.164)
to_number	string	Recipient phone (E.164)
status	string	Current status
service	string	iMessage, SMS, or RCS
is_outbound	boolean	True if sent, false if received
date_sent	string	Send timestamp (ISO 8601)
date_updated	string	Last update (ISO 8601)
media_url	string	CDN URL for attachments
was_downgraded	boolean	True if fell back to SMS
message_type	string	message or group
group_id	string	Group identifier
participants	array	Phone numbers in conversation
send_style	string	iMessage effect used
opted_out	boolean	Recipient opted out
sendblue_number	string	Your Sendblue number
number	string	Contact phone number
accountEmail	string	Account email
group_display_name	string	Display name for group chats
error_code	integer	Error code if failed
error_message	string	Error description
error_reason	string	Machine-readable error
error_detail	string	Additional error context