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. |
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"
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();
Response fields
Each item inresponse.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
{
"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
}
}