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

List

API Reference
Messages
Get messages
client.messages.list(MessageListParams { account_email, created_at_gte, created_at_lte, 16 more } query?, RequestOptionsoptions?): MessageListResponse { data, pagination, status }
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.

ParametersExpand Collapse
query: MessageListParams { account_email, created_at_gte, created_at_lte, 16 more }
account_email?: string

Filter by account email

created_at_gte?: string

Filter messages created after this date (ISO 8601 format)

formatdate-time
created_at_lte?: string

Filter messages created before this date (ISO 8601 format)

formatdate-time
from_number?: string

Filter by sender phone number

group_id?: string

Filter by group ID

is_outbound?: "true" | "false"

Filter by message direction

Accepts one of the following:
"true"
"false"
limit?: number

Maximum number of messages to return

minimum1
maximum1000
message_type?: "message" | "group"

Filter by message type

Accepts one of the following:
"message"
"group"
offset?: number

Number of messages to skip

minimum0
order_by?: "createdAt" | "updatedAt" | "sentAt"

Field to order messages by

Accepts one of the following:
"createdAt"
"updatedAt"
"sentAt"
order_direction?: "asc" | "desc"

Sort order

Accepts one of the following:
"asc"
"desc"
sent_at_gte?: string

Filter messages sent after this date (ISO 8601 format)

formatdate-time
sent_at_lte?: string

Filter messages sent before this date (ISO 8601 format)

formatdate-time
service?: "iMessage" | "SMS"

Filter by service type

Accepts one of the following:
"iMessage"
"SMS"
status?: "REGISTERED" | "PENDING" | "SENT" | 7 more

Filter by message status

Accepts one of the following:
"REGISTERED"
"PENDING"
"SENT"
"DELIVERED"
"RECEIVED"
"QUEUED"
"ERROR"
"DECLINED"
"ACCEPTED"
"SUCCESS"
to_number?: string

Filter by recipient phone number

updated_at_gte?: string

Filter messages updated after this date (ISO 8601 format)

formatdate-time
updated_at_lte?: string

Filter messages updated before this date (ISO 8601 format)

formatdate-time
worker_id?: string

Filter by worker ID (Admin only)

ReturnsExpand Collapse
MessageListResponse { data, pagination, status }
data?: Array<Data>
accountEmail?: string

Email of the account

content?: string

Message content

date_sent?: string

When the message was sent

formatdate-time
date_updated?: string

When the message was last updated

formatdate-time
error_code?: number | null

Numeric error code if message failed

error_detail?: string | null

Detailed error information

error_message?: string | null

Error message if message failed

error_reason?: string | null

Error reason if message failed

from_number?: string

Sender phone number

group_display_name?: string | null

Display name for group messages

group_id?: string | null

Group ID for group messages

is_outbound?: boolean

Whether this is an outbound message

media_url?: string | null

URL of attached media

message_handle?: string

Unique message identifier

message_type?: "message" | "group"
Accepts one of the following:
"message"
"group"
number?: string

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

opted_out?: boolean

Whether the recipient has opted out

participants?: Array<string>

List of participants for group messages

plan?: string

Account plan used for this message

send_style?: "celebration" | "shooting_star" | "fireworks" | 10 more

The iMessage expressive message style

Accepts one of the following:
"celebration"
"shooting_star"
"fireworks"
"lasers"
"love"
"confetti"
"balloons"
"spotlight"
"echo"
"invisible"
"gentle"
"loud"
"slam"
sendblue_number?: string | null

Sendblue phone number used

service?: "iMessage" | "SMS"
Accepts one of the following:
"iMessage"
"SMS"
status?: "REGISTERED" | "PENDING" | "SENT" | 7 more
Accepts one of the following:
"REGISTERED"
"PENDING"
"SENT"
"DELIVERED"
"RECEIVED"
"QUEUED"
"ERROR"
"DECLINED"
"ACCEPTED"
"SUCCESS"
to_number?: string

Recipient phone number

was_downgraded?: boolean

Whether the message was downgraded from iMessage to SMS

Whether there are more messages available

Number of messages returned in this request

Number of messages skipped

Total number of messages matching the filters

status?: string
Get messages
  • http
  • typescript
  • python
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);
{
  "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"
}
Returns Examples
{
  "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"
}