Skip to main content

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.

​
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

ParameterTypeDescription
projectIdstringFilter to one agent project.
creatorEmail / emailstringCase-insensitive exact creator email match.
creatorEmailContainsstringCase-insensitive partial creator email match. Ignored when creatorEmail is present.
creatorIdstringFilter by creator ID.
threadIdstringFilter by Gmail thread ID.
gmailAccountIdstringFilter by connected Gmail account ID.
directionstringall, outbound, or inbound. Default: all. Use outbound to list messages sent by the agent.
statusstringFilter by stored message status, such as sent, received, replied, or failed.
isFollowUpbooleanFilter follow-up emails.
pageintegerPage number. Default: 1.
perPageintegerResults 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"

​
Response fields

Each item in response.data includes:
FieldDescription
idMessage record ID.
project_id, conversation_idAgent project and conversation IDs.
gmail_account_id, sender_emailConnected Gmail account context.
directionoutbound for agent-sent messages, inbound for creator replies.
creator_id, creator_name, creator_email, creator_platformCreator context saved with the message.
subject, body, body_previewPlain-text message content. HTML is converted to readable text when no plain body is saved.
statusStored message status.
sent_at, replied_at, failed_at, date_created, date_updatedISO timestamp fields.
thread_id, message_id, parent_message_idGmail thread and message identifiers.
is_follow_up, follow_up_numberFollow-up metadata.
metadataExtra 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
  }
}