> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bizzyco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Tools

> Access and manage messages, threads, and attachments

The Bizzy MCP server provides 7 tools for accessing and managing messages. These
tools allow you to retrieve messages, search content, manage message status, and
view conversation threads.

## getMessage

Get detailed information about a specific message by its ID, including all
message type-specific fields (email headers, SMS encoding, WhatsApp media,
etc.).

**Permission:** `messages:read`

**Parameters:**

| Name        | Type          | Required | Description                   |
| ----------- | ------------- | -------- | ----------------------------- |
| `messageId` | string (UUID) | Yes      | ID of the message to retrieve |

**Returns:** Message object with all type-specific fields.

***

## listMessages

List messages in the organization with optional filtering.

**Permission:** `messages:read`

**Parameters:**

| Name        | Type   | Required | Default | Description                                            |
| ----------- | ------ | -------- | ------- | ------------------------------------------------------ |
| `limit`     | number | No       | 10      | Maximum number of messages to return (1-100)           |
| `offset`    | number | No       | 0       | Offset for pagination                                  |
| `sortOrder` | string | No       | "desc"  | Sort order by creation date ("asc" or "desc")          |
| `direction` | string | No       | -       | Filter by message direction ("incoming" or "outgoing") |

**Returns:** Array of message objects.

***

## updateMessageStatus

Update the status of a message - mark as read/unread, archive/unarchive, or
snooze/unsnooze.

**Permission:** `messages:write`

**Parameters:**

| Name           | Type           | Required | Description                                               |
| -------------- | -------------- | -------- | --------------------------------------------------------- |
| `messageId`    | string (UUID)  | Yes      | ID of the message to update                               |
| `readAt`       | string \| null | No       | ISO datetime to mark as read, or `null` to mark as unread |
| `archivedAt`   | string \| null | No       | ISO datetime to archive, or `null` to unarchive           |
| `snoozedUntil` | string \| null | No       | ISO datetime to snooze until, or `null` to unsnooze       |

**Returns:** The updated message object.

<Note>
  This tool only allows updating status fields for security reasons. To modify
  message content, use the appropriate channel-specific tools.
</Note>

***

## getMessagesByContact

Get all messages sent to or received from a specific contact. Useful for viewing
the complete communication history with a contact.

**Permission:** `messages:read`

**Parameters:**

| Name        | Type          | Required | Default | Description                                                              |
| ----------- | ------------- | -------- | ------- | ------------------------------------------------------------------------ |
| `contactId` | string (UUID) | Yes      | -       | Contact ID to retrieve messages for                                      |
| `limit`     | number        | No       | 20      | Maximum number of messages to return (1-100)                             |
| `offset`    | number        | No       | 0       | Offset for pagination                                                    |
| `sortOrder` | string        | No       | "desc"  | Sort order by creation date ("asc" or "desc")                            |
| `direction` | string        | No       | -       | Filter by direction ("incoming" = from contact, "outgoing" = to contact) |

**Returns:** Array of message objects from/to the specified contact.

***

## getMessageThread

Get all messages that belong to the same conversation thread. Useful for viewing
the complete conversation history.

**Permission:** `messages:read`

**Parameters:**

| Name        | Type   | Required | Default | Description                                                                    |
| ----------- | ------ | -------- | ------- | ------------------------------------------------------------------------------ |
| `threadId`  | string | Yes      | -       | Thread ID to retrieve messages for                                             |
| `limit`     | number | No       | 50      | Maximum number of messages to return (1-100)                                   |
| `offset`    | number | No       | 0       | Offset for pagination                                                          |
| `sortOrder` | string | No       | "asc"   | Sort order ("asc" = oldest first for conversation flow, "desc" = newest first) |
| `direction` | string | No       | -       | Filter by message direction ("incoming" or "outgoing")                         |

**Returns:** Array of message objects in the thread.

***

## listMessageAttachments

List all file attachments associated with a specific message, including details
like filename, size, content type, and URL.

**Permission:** `messages:read`

**Parameters:**

| Name        | Type          | Required | Default | Description                                   |
| ----------- | ------------- | -------- | ------- | --------------------------------------------- |
| `messageId` | string (UUID) | Yes      | -       | ID of the message                             |
| `limit`     | number        | No       | 20      | Maximum number of attachments to return       |
| `offset`    | number        | No       | 0       | Offset for pagination                         |
| `sortOrder` | string        | No       | "asc"   | Sort order by creation date ("asc" or "desc") |

**Returns:** Array of attachment objects with metadata (filename, size, content
type, URL).

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Contact Tools" icon="address-book" href="/mcp-server/tools/contacts">
    Manage contacts and their data
  </Card>

  <Card title="Authentication" icon="key" href="/mcp-server/authentication">
    Learn how MCP clients authenticate to the server
  </Card>
</CardGroup>