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/contacted-creators

Returns creators who have received at least one non-failed outbound email from your agent. This is the fastest way to map an inbox email address back to the creator, projects, threads, and reply status.

​
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.
pageintegerPage number. Default: 1.
perPageintegerResults per page. Default: 50, maximum: 100.
curl -X GET "https://api.topyappers.com/api/v1/agent/contacted-creators?email=creator@example.com" \
  -H "x-ty-api-key: $TY_API_KEY"

​
Response fields

Each item in response.data includes:
FieldDescription
creator_emailEmail address contacted by the agent.
creator_id, creator_name, creator_platformCreator context captured when outreach was sent.
project_idsAgent project IDs that contacted this creator.
thread_idsGmail thread IDs associated with the creator.
sent_messages_countNumber of non-failed outbound messages sent.
reply_messages_countNumber of inbound replies saved for the matching thread or email.
has_repliestrue when at least one inbound reply exists.
first_contacted_at, last_contacted_at, last_reply_atISO timestamp fields.
last_subject, last_status, last_body_previewPreview of the latest outbound message.

​
Example response

{
  "message": "OK",
  "response": {
    "data": [
      {
        "creator_email": "creator@example.com",
        "creator_id": "instagram_123",
        "creator_name": "Creator Name",
        "creator_platform": "instagram",
        "project_ids": ["662f01a2c86c2af2a2b9f123"],
        "thread_ids": ["18f8d5c7a1b12345"],
        "sent_messages_count": 2,
        "reply_messages_count": 1,
        "has_replies": true,
        "first_contacted_at": "2026-05-01T10:15:00",
        "last_contacted_at": "2026-05-04T10:15:00",
        "last_reply_at": "2026-05-05T14:20:00",
        "last_subject": "Partnership idea",
        "last_status": "replied",
        "last_body_preview": "Loved your recent post about meal prep..."
      }
    ],
    "page": 1,
    "per_page": 50,
    "next_page": 0,
    "total_pages": 1,
    "total": 1
  }
}