List Contacted Creators - TopYappers API

`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

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.
`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/contacted-creators?email=creator@example.com" \
  -H "x-ty-api-key: $TY_API_KEY"

const params = new URLSearchParams({
  email: 'creator@example.com',
  perPage: '25',
});

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

const payload = await res.json();

Response fields

Each item in response.data includes:

Field	Description
`creator_email`	Email address contacted by the agent.
`creator_id`, `creator_name`, `creator_platform`	Creator context captured when outreach was sent.
`project_ids`	Agent project IDs that contacted this creator.
`thread_ids`	Gmail thread IDs associated with the creator.
`sent_messages_count`	Number of non-failed outbound messages sent.
`reply_messages_count`	Number of inbound replies saved for the matching thread or email.
`has_replies`	`true` when at least one inbound reply exists.
`first_contacted_at`, `last_contacted_at`, `last_reply_at`	ISO timestamp fields.
`last_subject`, `last_status`, `last_body_preview`	Preview 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
  }
}