Skip to content
SendBlue Docs
  • Auto
  • Light
  • Dark
Get Started

List

API Reference
Messages
Get messages
get/api/v2/messages

Retrieve a list of messages for the authenticated account with comprehensive filtering capabilities. Rate limited to 100 requests per 10 seconds per account.

Query Parameters
account_emailstring
optional

Filter by account email

created_at_gtestring
optional

Filter messages created after this date (ISO 8601 format)

formatdate-time
created_at_ltestring
optional

Filter messages created before this date (ISO 8601 format)

formatdate-time
from_numberstring
optional

Filter by sender phone number

group_idstring
optional

Filter by group ID

is_outboundenum
optional
"true" OR "false"

Filter by message direction

Hide ParametersShow Parameters
"true"
"false"
limitnumber
optional

Maximum number of messages to return

minimum1
maximum1000
message_typeenum
optional
"message" OR "group"

Filter by message type

Hide ParametersShow Parameters
"message"
"group"
numberstring
optional

Filter by any phone number (from or to)

offsetnumber
optional

Number of messages to skip

minimum0
order_byenum
optional
"createdAt" OR "updatedAt" OR "sentAt"

Field to order messages by

Hide ParametersShow Parameters
"createdAt"
"updatedAt"
"sentAt"
order_directionenum
optional
"asc" OR "desc"

Sort order

Hide ParametersShow Parameters
"asc"
"desc"
sendblue_numberstring
optional

Filter by Sendblue phone number

sent_at_gtestring
optional

Filter messages sent after this date (ISO 8601 format)

formatdate-time
sent_at_ltestring
optional

Filter messages sent before this date (ISO 8601 format)

formatdate-time
serviceenum
optional
"iMessage" OR "SMS"

Filter by service type

Hide ParametersShow Parameters
"iMessage"
"SMS"
statusenum
optional
"REGISTERED" OR "PENDING" OR "SENT" OR 7 more

Filter by message status

Hide ParametersShow Parameters
"REGISTERED"
"PENDING"
"SENT"
"DELIVERED"
"RECEIVED"
"QUEUED"
"ERROR"
"DECLINED"
"ACCEPTED"
"SUCCESS"
to_numberstring
optional

Filter by recipient phone number

updated_at_gtestring
optional

Filter messages updated after this date (ISO 8601 format)

formatdate-time
updated_at_ltestring
optional

Filter messages updated before this date (ISO 8601 format)

formatdate-time
worker_idstring
optional

Filter by worker ID (Admin only)

Returns
dataarray of object
optional
Hide ParametersShow Parameters
accountEmailstring
optional

Email of the account

contentstring
optional

Message content

date_sentstring
optional

When the message was sent

formatdate-time
date_updatedstring
optional

When the message was last updated

formatdate-time
error_codenumber
optional

Numeric error code if message failed

error_detailstring
optional

Detailed error information

error_messagestring
optional

Error message if message failed

error_reasonstring
optional

Error reason if message failed

from_numberstring
optional

Sender phone number

group_display_namestring
optional

Display name for group messages

group_idstring
optional

Group ID for group messages

is_outboundboolean
optional

Whether this is an outbound message

media_urlstring
optional

URL of attached media

message_handlestring
optional

Unique message identifier

message_typeenum
optional
"message" OR "group"
Hide ParametersShow Parameters
"message"
"group"
numberstring
optional

Primary phone number (to_number for outbound, from_number for inbound)

opted_outboolean
optional

Whether the recipient has opted out

participantsarray of string
optional

List of participants for group messages

planstring
optional

Account plan used for this message

send_styleenum
optional
"celebration" OR "shooting_star" OR "fireworks" OR 10 more

The iMessage expressive message style

Hide ParametersShow Parameters
"celebration"
"shooting_star"
"fireworks"
"lasers"
"love"
"confetti"
"balloons"
"spotlight"
"echo"
"invisible"
"gentle"
"loud"
"slam"
sendblue_numberstring
optional

Sendblue phone number used

serviceenum
optional
"iMessage" OR "SMS"
Hide ParametersShow Parameters
"iMessage"
"SMS"
statusenum
optional
"REGISTERED" OR "PENDING" OR "SENT" OR 7 more
Hide ParametersShow Parameters
"REGISTERED"
"PENDING"
"SENT"
"DELIVERED"
"RECEIVED"
"QUEUED"
"ERROR"
"DECLINED"
"ACCEPTED"
"SUCCESS"
to_numberstring
optional

Recipient phone number

was_downgradedboolean
optional

Whether the message was downgraded from iMessage to SMS

statusstring
optional
curl https://api.sendblue.co/api/v2/messages \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
200 Example
{
  "data": [
    {
      "accountEmail": "[email protected]",
      "content": "Hello, World!",
      "date_sent": "2024-01-01T12:00:00Z",
      "date_updated": "2024-01-01T12:00:01Z",
      "error_code": null,
      "error_detail": null,
      "error_message": null,
      "error_reason": null,
      "from_number": "+19998887777",
      "group_display_name": null,
      "group_id": null,
      "is_outbound": true,
      "media_url": null,
      "message_handle": "msg_abc123def456",
      "message_type": "message",
      "number": "+18887776666",
      "opted_out": false,
      "participants": [
        "string"
      ],
      "plan": "premium",
      "send_style": "celebration",
      "sendblue_number": "+19998887777",
      "service": "iMessage",
      "status": "SENT",
      "to_number": "+18887776666",
      "was_downgraded": false
    }
  ],
  "pagination": {
    "hasMore": true,
    "limit": 50,
    "offset": 0,
    "total": 1000
  },
  "status": "OK"
}