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.com/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": "user@example.com",
      "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.com/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.com/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
app_card	object	App Card data sent or received with the message. See App Cards.
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	The rule’s key when a rule declined the message (same as error_key), otherwise an error description
error_key	string	Stable key of the rule that declined the message, null otherwise. Branch on this field
error_reason	string	Human-readable text for display, do not parse
error_detail	string	Additional error context
reply_to	object	Immediate parent of an inline reply, with message_handle and optional server-reported part metadata
thread_originator	object	Thread root, with message_handle and optional opaque Apple part descriptor