# Messages

## List

`client.messages.list(MessageListParamsquery?, RequestOptionsoptions?): 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

- `query: MessageListParams`

  - `account_email?: string`

    Filter by account email

  - `created_at_gte?: string`

    Filter messages created after this date (ISO 8601 format)

  - `created_at_lte?: string`

    Filter messages created before this date (ISO 8601 format)

  - `from_number?: string`

    Filter by sender phone number

  - `group_id?: string`

    Filter by group ID

  - `is_outbound?: "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?: number`

    Maximum number of messages to return

  - `message_type?: "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?: string`

    Filter by any phone number (from or to)

  - `offset?: number`

    Number of messages to skip

  - `order_by?: "createdAt" | "updatedAt" | "sentAt"`

    Field to order messages by

    - `"createdAt"`

    - `"updatedAt"`

    - `"sentAt"`

  - `order_direction?: "asc" | "desc"`

    Sort order

    - `"asc"`

    - `"desc"`

  - `sendblue_number?: string`

    Filter by Sendblue phone number

  - `sent_at_gte?: string`

    Filter messages sent after this date (ISO 8601 format)

  - `sent_at_lte?: string`

    Filter messages sent before this date (ISO 8601 format)

  - `service?: "iMessage" | "SMS" | "RCS"`

    Filter by service type

    - `"iMessage"`

    - `"SMS"`

    - `"RCS"`

  - `status?: "REGISTERED" | "PENDING" | "SENT" | 7 more`

    Filter by message status

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

  - `updated_at_lte?: string`

    Filter messages updated before this date (ISO 8601 format)

  - `worker_id?: string`

    Filter by worker ID (Admin only)

### Returns

- `MessageListResponse`

  - `data?: Array<Data>`

    - `accountEmail?: string`

      Email of the account

    - `content?: string`

      Message content

    - `date_sent?: string`

      When the message was sent

    - `date_updated?: string`

      When the message was last updated

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

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

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

      The messaging service used

      - `"iMessage"`

      - `"SMS"`

      - `"RCS"`

    - `status?: "REGISTERED" | "PENDING" | "SENT" | 7 more`

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

  - `pagination?: Pagination`

    - `hasMore?: boolean`

      Whether there are more messages available

    - `limit?: number`

      Number of messages returned in this request

    - `offset?: number`

      Number of messages skipped

    - `total?: number`

      Total number of messages matching the filters

  - `status?: string`

### Example

```typescript
import SendblueAPI from 'sendblue';

const client = new SendblueAPI({
  apiKey: process.env['SENDBLUE_API_API_KEY'], // This is the default and can be omitted
  apiSecret: process.env['SENDBLUE_API_API_SECRET'], // This is the default and can be omitted
});

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

console.log(messages.data);
```

## Retrieve

`client.messages.retrieve(stringmessageID, RequestOptionsoptions?): MessageRetrieveResponse`

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

Retrieve details of a specific message by its ID

### Parameters

- `messageID: string`

### Returns

- `MessageRetrieveResponse`

  - `data?: Data`

    - `accountEmail?: string`

      Email of the account

    - `content?: string`

      Message content

    - `date_sent?: string`

      When the message was sent

    - `date_updated?: string`

      When the message was last updated

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

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

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

      The messaging service used

      - `"iMessage"`

      - `"SMS"`

      - `"RCS"`

    - `status?: "REGISTERED" | "PENDING" | "SENT" | 7 more`

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

  - `status?: string`

### Example

```typescript
import SendblueAPI from 'sendblue';

const client = new SendblueAPI({
  apiKey: process.env['SENDBLUE_API_API_KEY'], // This is the default and can be omitted
  apiSecret: process.env['SENDBLUE_API_API_SECRET'], // This is the default and can be omitted
});

const message = await client.messages.retrieve('msg_abc123def456');

console.log(message.data);
```

## Send

`client.messages.send(MessageSendParamsbody, RequestOptionsoptions?): MessageResponse`

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

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

### Parameters

- `body: MessageSendParams`

  - `content: string`

    Message text content

  - `from_number: string`

    **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: string`

    Recipient phone number in E.164 format

  - `media_url?: string`

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

  - `send_style?: "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?: string`

    Webhook URL for message status updates

### Returns

- `MessageResponse`

  - `account_email?: string`

    Email of the account that sent the message

  - `content?: string`

    Message content

  - `date_created?: string`

    When the message was created

  - `date_updated?: string`

    When the message was last updated

  - `error_code?: number`

    Numeric error code if message failed

  - `error_message?: string`

    Error message if message failed

  - `from_number?: string`

    Sending phone number

  - `is_outbound?: boolean`

    Whether this is an outbound message

  - `media_url?: string`

    URL of attached media

  - `message_handle?: string`

    Unique identifier for tracking the message

  - `number?: string`

    Recipient phone number

  - `send_style?: "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?: "QUEUED" | "SENT" | "DELIVERED" | "ERROR"`

    - `"QUEUED"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"ERROR"`

### Example

```typescript
import SendblueAPI from 'sendblue';

const client = new SendblueAPI({
  apiKey: process.env['SENDBLUE_API_API_KEY'], // This is the default and can be omitted
  apiSecret: process.env['SENDBLUE_API_API_SECRET'], // This is the default and can be omitted
});

const messageResponse = await client.messages.send({
  content: 'Hello, World!',
  from_number: '+19998887777',
  number: '+19998887777',
});

console.log(messageResponse.account_email);
```

## Get Status

`client.messages.getStatus(MessageGetStatusParamsquery, RequestOptionsoptions?): 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

- `query: MessageGetStatusParams`

  - `handle: string`

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

### Returns

- `MessageResponse`

  - `account_email?: string`

    Email of the account that sent the message

  - `content?: string`

    Message content

  - `date_created?: string`

    When the message was created

  - `date_updated?: string`

    When the message was last updated

  - `error_code?: number`

    Numeric error code if message failed

  - `error_message?: string`

    Error message if message failed

  - `from_number?: string`

    Sending phone number

  - `is_outbound?: boolean`

    Whether this is an outbound message

  - `media_url?: string`

    URL of attached media

  - `message_handle?: string`

    Unique identifier for tracking the message

  - `number?: string`

    Recipient phone number

  - `send_style?: "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?: "QUEUED" | "SENT" | "DELIVERED" | "ERROR"`

    - `"QUEUED"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"ERROR"`

### Example

```typescript
import SendblueAPI from 'sendblue';

const client = new SendblueAPI({
  apiKey: process.env['SENDBLUE_API_API_KEY'], // This is the default and can be omitted
  apiSecret: process.env['SENDBLUE_API_API_SECRET'], // This is the default and can be omitted
});

const messageResponse = await client.messages.getStatus({ handle: 'msg_abc123def456' });

console.log(messageResponse.account_email);
```

## Domain Types

### Message Content

- `MessageContent`

  - `account_email?: string`

    Email of the account

  - `content?: string`

    Message content

  - `date_created?: string`

    When the message was created

  - `date_sent?: string`

    When the message was sent

  - `date_updated?: string`

    When the message was last updated

  - `from_number?: string`

    Sender phone number

  - `is_outbound?: boolean`

    Whether this is an outbound message

  - `media_url?: string`

    URL of attached media

  - `message_handle?: string`

    Unique message identifier

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

    - `"celebration"`

    - `"shooting_star"`

    - `"fireworks"`

    - `"lasers"`

    - `"love"`

    - `"confetti"`

    - `"balloons"`

    - `"spotlight"`

    - `"echo"`

    - `"invisible"`

    - `"gentle"`

    - `"loud"`

    - `"slam"`

  - `status?: "QUEUED" | "SENT" | "DELIVERED" | 2 more`

    - `"QUEUED"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"ERROR"`

    - `"RECEIVED"`

  - `to_number?: string`

    Recipient phone number

### Message Response

- `MessageResponse`

  - `account_email?: string`

    Email of the account that sent the message

  - `content?: string`

    Message content

  - `date_created?: string`

    When the message was created

  - `date_updated?: string`

    When the message was last updated

  - `error_code?: number`

    Numeric error code if message failed

  - `error_message?: string`

    Error message if message failed

  - `from_number?: string`

    Sending phone number

  - `is_outbound?: boolean`

    Whether this is an outbound message

  - `media_url?: string`

    URL of attached media

  - `message_handle?: string`

    Unique identifier for tracking the message

  - `number?: string`

    Recipient phone number

  - `send_style?: "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?: "QUEUED" | "SENT" | "DELIVERED" | "ERROR"`

    - `"QUEUED"`

    - `"SENT"`

    - `"DELIVERED"`

    - `"ERROR"`