List

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.

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

Accepts 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

Accepts one of the following:

"message"

"group"

offset: Optional[int]

Number of messages to skip

minimum0

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

Field to order messages by

Accepts one of the following:

"createdAt"

"updatedAt"

"sentAt"

order_direction: Optional[Literal["asc", "desc"]]

Sort order

Accepts one of the following:

"asc"

"desc"

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"]]

Filter by service type

Accepts one of the following:

"iMessage"

"SMS"

status: Optional[Literal["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: 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"]]

Accepts 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

Accepts 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"]]

Accepts one of the following:

"iMessage"

"SMS"

status: Optional[Literal["REGISTERED", "PENDING", "SENT", 7 more]]

Accepts 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

pagination: Optional[Pagination]

has_more: Optional[bool]

Whether there are more messages available

limit: Optional[int]

Number of messages returned in this request

offset: Optional[int]

Number of messages skipped

total: Optional[int]

Total number of messages matching the filters

status: Optional[str]

Get messages

python

• http
• typescript
• python

from sendblue_api import SendblueAPI

client = SendblueAPI(
    api_key="My API Key",
    api_secret="My API Secret",
)
messages = client.messages.list()
print(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"
}

Returns Examples

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"
}