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

List

API Reference
Messages
Get messages
client.messages.list(MessageListParamsquery?, RequestOptionsoptions?): dataarraypaginationPaginationstatusstringMessageListResponse
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.

Parameters
queryaccount_emailstringcreated_at_gtestringcreated_at_ltestringfrom_numberstringgroup_idstringis_outboundunionlimitnumbermessage_typeunionnumberstringoffsetnumberorder_byunionorder_directionunionsendblue_numberstringsent_at_gtestringsent_at_ltestringserviceunionstatusunionto_numberstringupdated_at_gtestringupdated_at_ltestringworker_idstringMessageListParams
Hide ParametersShow 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_outboundunion
optional
"true" | "false"

Filter by message direction

Hide ParametersShow Parameters
"true"
"false"
limitnumber
optional

Maximum number of messages to return

minimum1
maximum1000
message_typeunion
optional
"message" | "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_byunion
optional
"createdAt" | "updatedAt" | "sentAt"

Field to order messages by

Hide ParametersShow Parameters
"createdAt"
"updatedAt"
"sentAt"
order_directionunion
optional
"asc" | "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
serviceunion
optional
"iMessage" | "SMS"

Filter by service type

Hide ParametersShow Parameters
"iMessage"
"SMS"
statusunion
optional
"REGISTERED" | "PENDING" | "SENT" | 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
MessageListResponse
Hide ParametersShow Parameters
dataarray
optional
Array<Data>
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_codeunion
optional
number | null

Numeric error code if message failed

error_detailunion
optional
string | null

Detailed error information

error_messageunion
optional
string | null

Error message if message failed

error_reasonunion
optional
string | null

Error reason if message failed

from_numberstring
optional

Sender phone number

group_display_nameunion
optional
string | null

Display name for group messages

group_idunion
optional
string | null

Group ID for group messages

is_outboundboolean
optional

Whether this is an outbound message

media_urlunion
optional
string | null

URL of attached media

message_handlestring
optional

Unique message identifier

message_typeunion
optional
"message" | "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
optional
Array<string>

List of participants for group messages

planstring
optional

Account plan used for this message

send_styleunion
optional
"celebration" | "shooting_star" | "fireworks" | 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_numberunion
optional
string | null

Sendblue phone number used

serviceunion
optional
"iMessage" | "SMS"
Hide ParametersShow Parameters
"iMessage"
"SMS"
statusunion
optional
"REGISTERED" | "PENDING" | "SENT" | 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
import SendblueAPI from 'sendblue';

const client = new SendblueAPI({
  apiKey: 'My API Key',
  apiSecret: 'My API Secret',
});

const messages = await client.messages.list();

console.log(messages.data);
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"
}