Skip to Content
EmailList Emails

List Emails

GET /v1/emails

Lists your emails, newest first. Filter by tag, status or batch, and page through the results with a cursor. Each row is a summary; call Get Email for the full event history.

Query parameters

ParameterTypeDescription
tagstringOnly emails carrying this tag, as name:value. Repeat the parameter to require several tags at once, up to 10.
statusstringOne of the email statuses.
batch_idstringOnly emails from this batch.
limitintegerPage size, 1 to 100. Defaults to 50.
cursorstringThe next_cursor from the previous page.

Example

const { data, error } = await retransmit.emails.list({
  tags: [{ name: "campaign", value: "spring-2026" }],
  status: "bounced",
  limit: 100,
});
 
if (data?.has_more) {
  const next = await retransmit.emails.list({
    tags: [{ name: "campaign", value: "spring-2026" }],
    status: "bounced",
    limit: 100,
    cursor: data.next_cursor!,
  });
}

Response

200 OK

{
  "emails": [
    {
      "id": "em_xxxxxxxxxxxx",
      "batch_id": null,
      "from": "Acme <hello@yourdomain.com>",
      "to": ["user@example.com"],
      "subject": "Your receipt",
      "marketing": false,
      "tags": [{ "name": "campaign", "value": "spring-2026" }],
      "status": "bounced",
      "error": "The recipient's mailbox does not exist. (smtp; 550 5.1.1 User unknown)",
      "bounce_reason": "mailbox_not_found",
      "created_at": "2026-09-01T12:00:00.000Z",
      "scheduled_at": null,
      "last_event_at": "2026-09-01T12:00:03.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "2026-09-01T12:00:00.000Z"
}

Pass next_cursor back as cursor, with the same filters, to fetch the next page. It is null on the last page.

Filter on status=bounced and group the results by bounce_reason to see whether your bounces are dead addresses or your sending being refused. The reasons are listed in Get Email. Filter on status=scheduled for sends that have not gone out yet.

List tags

GET /v1/emails/tags

Every distinct tag on your account with how many emails carry it. This is the same list the dashboard filter offers.

const { data } = await retransmit.emails.tags();
{
  "tags": [
    { "name": "campaign", "value": "spring-2026", "count": 1240 },
    { "name": "category", "value": "receipt", "count": 388 }
  ]
}

Errors

StatusCodeCause
422validation_errorA query parameter is malformed, for example a tag without name:value or a limit above 100.
401unauthorizedMissing, malformed, or revoked API key.
Last updated on
Get EmailGet Batch