# Messages

## List

`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
```

### Parameters

- `account_email: Optional[str]`

  Filter by account email

- `created_at_gte: Optional[Union[str, datetime]]`

  Filter messages created after this date (ISO 8601 format)

- `created_at_lte: Optional[Union[str, datetime]]`

  Filter messages created before this date (ISO 8601 format)

- `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.

  - `"true"`

  - `"false"`

- `limit: Optional[int]`

  Maximum number of messages to return

- `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.

  - `"message"`

  - `"group"`

- `number: Optional[str]`

  Filter by any phone number (from or to)

- `offset: Optional[int]`

  Number of messages to skip

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

  Field to order messages by

  - `"createdAt"`

  - `"updatedAt"`

  - `"sentAt"`

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

  Sort order

  - `"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)

- `sent_at_lte: Optional[Union[str, datetime]]`

  Filter messages sent before this date (ISO 8601 format)

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

  Filter by service type

  - `"iMessage"`

  - `"SMS"`

  - `"RCS"`

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

  Filter by message status

  - `"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)

- `updated_at_lte: Optional[Union[str, datetime]]`

  Filter messages updated before this date (ISO 8601 format)

- `worker_id: Optional[str]`

  Filter by worker ID (Admin only)

### Returns

- `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

    - `date_updated: Optional[datetime]`

      When the message was last updated

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

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

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

      - `"iMessage"`

      - `"SMS"`

      - `"RCS"`

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

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

### Example

```python
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)
```

## Retrieve

`messages.retrieve(strmessage_id)  -> MessageRetrieveResponse`

**get** `/api/v2/messages/{message_id}`

Retrieve details of a specific message by its ID

### Parameters

- `message_id: str`

### Returns

- `class MessageRetrieveResponse: …`

  - `data: Optional[Data]`

    - `account_email: Optional[str]`

      Email of the account

    - `content: Optional[str]`

      Message content

    - `date_sent: Optional[datetime]`

      When the message was sent

    - `date_updated: Optional[datetime]`

      When the message was last updated

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

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

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

      - `"iMessage"`

      - `"SMS"`

      - `"RCS"`

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

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

  - `status: Optional[str]`

### Example

```python
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
)
message = client.messages.retrieve(
    "msg_abc123def456",
)
print(message.data)
```

## Send

`messages.send(MessageSendParams**kwargs)  -> MessageResponse`

**post** `/api/send-message`

Send an iMessage, SMS, or MMS to a single recipient

### Parameters

- `content: str`

  Message text content

- `from_number: str`

  **REQUIRED** - The phone number to send from. Must be one of your registered Sendblue phone numbers in E.164 format.
  Without this parameter, the message will fail to send.

- `number: str`

  Recipient phone number in E.164 format

- `media_url: Optional[str]`

  URL of media file to send (images, videos, etc.)

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

  The iMessage expressive message style

  - `"celebration"`

  - `"shooting_star"`

  - `"fireworks"`

  - `"lasers"`

  - `"love"`

  - `"confetti"`

  - `"balloons"`

  - `"spotlight"`

  - `"echo"`

  - `"invisible"`

  - `"gentle"`

  - `"loud"`

  - `"slam"`

- `status_callback: Optional[str]`

  Webhook URL for message status updates

### Returns

- `class MessageResponse: …`

  - `account_email: Optional[str]`

    Email of the account that sent the message

  - `content: Optional[str]`

    Message content

  - `date_created: Optional[datetime]`

    When the message was created

  - `date_updated: Optional[datetime]`

    When the message was last updated

  - `error_code: Optional[int]`

    Numeric error code if message failed

  - `error_message: Optional[str]`

    Error message if message failed

  - `from_number: Optional[str]`

    Sending phone number

  - `is_outbound: Optional[bool]`

    Whether this is an outbound message

  - `media_url: Optional[str]`

    URL of attached media

  - `message_handle: Optional[str]`

    Unique identifier for tracking the message

  - `number: Optional[str]`

    Recipient phone number

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

    The iMessage expressive message style

    - `"celebration"`

    - `"shooting_star"`

    - `"fireworks"`

    - `"lasers"`

    - `"love"`

    - `"confetti"`

    - `"balloons"`

    - `"spotlight"`

    - `"echo"`

    - `"invisible"`

    - `"gentle"`

    - `"loud"`

    - `"slam"`

  - `status: Optional[Literal["QUEUED", "SENT", "DELIVERED", "ERROR"]]`

    - `"QUEUED"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"ERROR"`

### Example

```python
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
)
message_response = client.messages.send(
    content="Hello, World!",
    from_number="+19998887777",
    number="+19998887777",
)
print(message_response.account_email)
```

## Get Status

`messages.get_status(MessageGetStatusParams**kwargs)  -> MessageResponse`

**get** `/api/status`

Retrieve the current status of a message using its message handle. Useful for resolving pending message statuses and avoiding duplicate messages.

### Parameters

- `handle: str`

  The message handle of the message you want to check status for

### Returns

- `class MessageResponse: …`

  - `account_email: Optional[str]`

    Email of the account that sent the message

  - `content: Optional[str]`

    Message content

  - `date_created: Optional[datetime]`

    When the message was created

  - `date_updated: Optional[datetime]`

    When the message was last updated

  - `error_code: Optional[int]`

    Numeric error code if message failed

  - `error_message: Optional[str]`

    Error message if message failed

  - `from_number: Optional[str]`

    Sending phone number

  - `is_outbound: Optional[bool]`

    Whether this is an outbound message

  - `media_url: Optional[str]`

    URL of attached media

  - `message_handle: Optional[str]`

    Unique identifier for tracking the message

  - `number: Optional[str]`

    Recipient phone number

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

    The iMessage expressive message style

    - `"celebration"`

    - `"shooting_star"`

    - `"fireworks"`

    - `"lasers"`

    - `"love"`

    - `"confetti"`

    - `"balloons"`

    - `"spotlight"`

    - `"echo"`

    - `"invisible"`

    - `"gentle"`

    - `"loud"`

    - `"slam"`

  - `status: Optional[Literal["QUEUED", "SENT", "DELIVERED", "ERROR"]]`

    - `"QUEUED"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"ERROR"`

### Example

```python
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
)
message_response = client.messages.get_status(
    handle="msg_abc123def456",
)
print(message_response.account_email)
```

## Domain Types

### Message Content

- `class MessageContent: …`

  - `account_email: Optional[str]`

    Email of the account

  - `content: Optional[str]`

    Message content

  - `date_created: Optional[datetime]`

    When the message was created

  - `date_sent: Optional[datetime]`

    When the message was sent

  - `date_updated: Optional[datetime]`

    When the message was last updated

  - `from_number: Optional[str]`

    Sender phone number

  - `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

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

    - `"celebration"`

    - `"shooting_star"`

    - `"fireworks"`

    - `"lasers"`

    - `"love"`

    - `"confetti"`

    - `"balloons"`

    - `"spotlight"`

    - `"echo"`

    - `"invisible"`

    - `"gentle"`

    - `"loud"`

    - `"slam"`

  - `status: Optional[Literal["QUEUED", "SENT", "DELIVERED", 2 more]]`

    - `"QUEUED"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"ERROR"`

    - `"RECEIVED"`

  - `to_number: Optional[str]`

    Recipient phone number

### Message Response

- `class MessageResponse: …`

  - `account_email: Optional[str]`

    Email of the account that sent the message

  - `content: Optional[str]`

    Message content

  - `date_created: Optional[datetime]`

    When the message was created

  - `date_updated: Optional[datetime]`

    When the message was last updated

  - `error_code: Optional[int]`

    Numeric error code if message failed

  - `error_message: Optional[str]`

    Error message if message failed

  - `from_number: Optional[str]`

    Sending phone number

  - `is_outbound: Optional[bool]`

    Whether this is an outbound message

  - `media_url: Optional[str]`

    URL of attached media

  - `message_handle: Optional[str]`

    Unique identifier for tracking the message

  - `number: Optional[str]`

    Recipient phone number

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

    The iMessage expressive message style

    - `"celebration"`

    - `"shooting_star"`

    - `"fireworks"`

    - `"lasers"`

    - `"love"`

    - `"confetti"`

    - `"balloons"`

    - `"spotlight"`

    - `"echo"`

    - `"invisible"`

    - `"gentle"`

    - `"loud"`

    - `"slam"`

  - `status: Optional[Literal["QUEUED", "SENT", "DELIVERED", "ERROR"]]`

    - `"QUEUED"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"ERROR"`