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

# List Agent Messages

> List sent and received agent email messages

## `GET /api/v1/agent/messages`

Returns saved agent email messages. Use this endpoint to retrieve the full conversation history for a creator email or Gmail thread before writing a customized reply.

## Query parameters

| Parameter                | Type    | Description                                                                                         |
| ------------------------ | ------- | --------------------------------------------------------------------------------------------------- |
| `projectId`              | string  | Filter to one agent project.                                                                        |
| `creatorEmail` / `email` | string  | Case-insensitive exact creator email match.                                                         |
| `creatorEmailContains`   | string  | Case-insensitive partial creator email match. Ignored when `creatorEmail` is present.               |
| `creatorId`              | string  | Filter by creator ID.                                                                               |
| `threadId`               | string  | Filter by Gmail thread ID.                                                                          |
| `gmailAccountId`         | string  | Filter by connected Gmail account ID.                                                               |
| `direction`              | string  | `all`, `outbound`, or `inbound`. Default: `all`. Use `outbound` to list messages sent by the agent. |
| `status`                 | string  | Filter by stored message status, such as `sent`, `received`, `replied`, or `failed`.                |
| `isFollowUp`             | boolean | Filter follow-up emails.                                                                            |
| `page`                   | integer | Page number. Default: `1`.                                                                          |
| `perPage`                | integer | Results per page. Default: `50`, maximum: `100`.                                                    |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.topyappers.com/api/v1/agent/messages?email=creator@example.com&direction=all" \
    -H "x-ty-api-key: $TY_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    email: 'creator@example.com',
    direction: 'all',
  });

  const res = await fetch(
    `https://api.topyappers.com/api/v1/agent/messages?${params.toString()}`,
    {
      headers: {
        'x-ty-api-key': process.env.TY_API_KEY,
      },
    },
  );

  const payload = await res.json();
  ```
</CodeGroup>

## Response fields

Each item in `response.data` includes:

| Field                                                                | Description                                                                                 |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `id`                                                                 | Message record ID.                                                                          |
| `project_id`, `conversation_id`                                      | Agent project and conversation IDs.                                                         |
| `gmail_account_id`, `sender_email`                                   | Connected Gmail account context.                                                            |
| `direction`                                                          | `outbound` for agent-sent messages, `inbound` for creator replies.                          |
| `creator_id`, `creator_name`, `creator_email`, `creator_platform`    | Creator context saved with the message.                                                     |
| `subject`, `body`, `body_preview`                                    | Plain-text message content. HTML is converted to readable text when no plain body is saved. |
| `status`                                                             | Stored message status.                                                                      |
| `sent_at`, `replied_at`, `failed_at`, `date_created`, `date_updated` | ISO timestamp fields.                                                                       |
| `thread_id`, `message_id`, `parent_message_id`                       | Gmail thread and message identifiers.                                                       |
| `is_follow_up`, `follow_up_number`                                   | Follow-up metadata.                                                                         |
| `metadata`                                                           | Extra transport or workflow metadata.                                                       |

## Example response

```json theme={null}
{
  "message": "OK",
  "response": {
    "data": [
      {
        "id": "662f0ab2c86c2af2a2b9f456",
        "project_id": "662f01a2c86c2af2a2b9f123",
        "sender_email": "partnerships@example.com",
        "direction": "outbound",
        "creator_id": "instagram_123",
        "creator_name": "Creator Name",
        "creator_email": "creator@example.com",
        "creator_platform": "instagram",
        "subject": "Partnership idea",
        "body_preview": "Loved your recent post about meal prep...",
        "status": "sent",
        "thread_id": "18f8d5c7a1b12345",
        "is_follow_up": false,
        "date_created": "2026-05-01T10:15:00"
      }
    ],
    "page": 1,
    "per_page": 50,
    "next_page": 0,
    "total_pages": 1,
    "total": 1
  }
}
```