Skip to content
Sendblue Docs
Get Started
API Reference
Messages

Get messages

messages.list(MessageListParams**kwargs) -> MessageListResponse
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.

Common Use Cases

Polling for inbound messages (no webhooks):

GET /api/v2/messages?is_outbound=false&sendblue_number=+16292925296&order_by=createdAt&order_direction=desc&limit=50

Track processed message IDs to avoid duplicates.

Get conversation with a specific contact:

GET /api/v2/messages?number=+15551234567&order_by=createdAt&order_direction=desc
ParametersExpand Collapse
account_email: Optional[str]

Filter by account email

created_at_gte: Optional[Union[str, datetime]]

Filter messages created after this date (ISO 8601 format)

formatdate-time
created_at_lte: Optional[Union[str, datetime]]

Filter messages created before this date (ISO 8601 format)

formatdate-time
from_number: Optional[str]

Filter by sender phone number

group_id: Optional[str]

Filter by group ID

is_outbound: Optional[Literal["true", "false"]]

Filter by message direction. Use false to get inbound messages (messages sent TO your Sendblue number).

To get inbound messages for polling: Use is_outbound=false combined with sendblue_number or to_number set to your Sendblue phone number.

Note: Do NOT use message_type=inbound - that parameter only accepts message or group values.

One of the following:
"true"
"false"
limit: Optional[int]

Maximum number of messages to return

minimum1
maximum1000
message_type: Optional[Literal["message", "group"]]

Filter by message type (1:1 vs group chat). Only accepts message or group.

Common mistake: This is NOT for filtering inbound vs outbound messages. Use is_outbound parameter instead.

One of the following:
"message"
"group"
number: Optional[str]

Filter by any phone number (from or to)

offset: Optional[int]

Number of messages to skip

minimum0
order_by: Optional[Literal["createdAt", "updatedAt", "sentAt"]]

Field to order messages by

One of the following:
"createdAt"
"updatedAt"
"sentAt"
order_direction: Optional[Literal["asc", "desc"]]

Sort order

One of the following:
"asc"
"desc"
sendblue_number: Optional[str]

Filter by Sendblue phone number

sent_at_gte: Optional[Union[str, datetime]]

Filter messages sent after this date (ISO 8601 format)

formatdate-time
sent_at_lte: Optional[Union[str, datetime]]

Filter messages sent before this date (ISO 8601 format)

formatdate-time
service: Optional[Literal["iMessage", "SMS", "RCS"]]

Filter by service type

One of the following:
"iMessage"
"SMS"
"RCS"
status: Optional[Literal["REGISTERED", "PENDING", "SENT", 7 more]]

Filter by message status

One of the following:
"REGISTERED"
"PENDING"
"SENT"
"DELIVERED"
"RECEIVED"
"QUEUED"
"ERROR"
"DECLINED"
"ACCEPTED"
"SUCCESS"
to_number: Optional[str]

Filter by recipient phone number

updated_at_gte: Optional[Union[str, datetime]]

Filter messages updated after this date (ISO 8601 format)

formatdate-time
updated_at_lte: Optional[Union[str, datetime]]

Filter messages updated before this date (ISO 8601 format)

formatdate-time
worker_id: Optional[str]

Filter by worker ID (Admin only)

ReturnsExpand Collapse
class MessageListResponse: …
data: Optional[List[Data]]
account_email: Optional[str]

Email of the account

content: Optional[str]

Message content

date_sent: Optional[datetime]

When the message was sent

formatdate-time
date_updated: Optional[datetime]

When the message was last updated

formatdate-time
error_code: Optional[int]

Numeric error code if message failed

error_detail: Optional[str]

Detailed error information

error_message: Optional[str]

Error message if message failed

error_reason: Optional[str]

Error reason if message failed

from_number: Optional[str]

Sender phone number

group_display_name: Optional[str]

Display name for group messages

group_id: Optional[str]

Group ID for group messages

is_outbound: Optional[bool]

Whether this is an outbound message

media_url: Optional[str]

URL of attached media

message_handle: Optional[str]

Unique message identifier

message_type: Optional[Literal["message", "group"]]
One of the following:
"message"
"group"
number: Optional[str]

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

opted_out: Optional[bool]

Whether the recipient has opted out

participants: Optional[List[str]]

List of participants for group messages

plan: Optional[str]

Account plan used for this message

send_style: Optional[Literal["celebration", "shooting_star", "fireworks", 10 more]]

The iMessage expressive message style

One of the following:
"celebration"
"shooting_star"
"fireworks"
"lasers"
"love"
"confetti"
"balloons"
"spotlight"
"echo"
"invisible"
"gentle"
"loud"
"slam"
sendblue_number: Optional[str]

Sendblue phone number used

service: Optional[Literal["iMessage", "SMS", "RCS"]]

The messaging service used

One of the following:
"iMessage"
"SMS"
"RCS"
status: Optional[Literal["REGISTERED", "PENDING", "SENT", 7 more]]
One of the following:
"REGISTERED"
"PENDING"
"SENT"
"DELIVERED"
"RECEIVED"
"QUEUED"
"ERROR"
"DECLINED"
"ACCEPTED"
"SUCCESS"
to_number: Optional[str]

Recipient phone number

was_downgraded: Optional[bool]

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: Optional[str]

Get messages

import os
from sendblue_api import SendblueAPI

client = SendblueAPI(
    api_key=os.environ.get("SENDBLUE_API_API_KEY"),  # This is the default and can be omitted
    api_secret=os.environ.get("SENDBLUE_API_API_SECRET"),  # This is the default and can be omitted
)
messages = client.messages.list()
print(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"
}