YourMail

API reference

List emails

GET/v1/emails

Page through every email you've sent, newest first, optionally filtered by status.

Why use this

Retrieve answers “what happened to this email?”. List answers “what happened to all of them?” — it's how you reconcile sending against your own records, build internal reporting, or sweep up failures in a scheduled job.

For example

Every morning you pull yesterday's bounced emails and flag those users' addresses in your own database, so your support team knows who never got their receipt.

Example

import { YourMail } from "yourmail";

const yourmail = new YourMail(process.env.YOURMAIL_API_KEY!, {
  baseUrl: process.env.YOURMAIL_BASE_URL!,
});

const page = await yourmail.list({ limit: 50 });

for (const email of page.data) {
  console.log(email.id, email.status, email.subject);
}

Query parameters

All parameters are optional.

limitnumber
Page size, 1–100. Defaults to 50. Values outside the range are clamped rather than rejected.
cursorstring
Opaque cursor taken from a previous response's nextCursor. Omit it to start from the newest email.
statusstring
Optional filter. One of queued, sent, delivered, bounced, complained, failed. Any other value is a 400.

Response

// 200 OK
{
  "data": [
    {
      "id": "jn7abc123def456",
      "to": ["alice@example.com"],
      "from": "hello@mail.acme.com",
      "subject": "Welcome to Acme",
      "status": "delivered",
      "tags": [{ "name": "campaign", "value": "welcome" }],
      "createdAt": 1750000000000,
      "sentAt": 1750000001234,
      "openedAt": 1750000090000,
      "clickedAt": null
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJpZCI6..."
}
dataobject[]
The page of emails, newest first.
data[].idstring
Unique email identifier — pass it to the retrieve endpoint for the full record.
data[].tostring[]
Recipient addresses.
data[].fromstring
Sender address as supplied in the send request.
data[].subjectstring
Email subject line.
data[].statusstring
Current delivery status.
data[].tags{name,value}[]
Tags attached at send time.
data[].createdAtnumber
Unix millisecond timestamp when the email was created.
data[].sentAtnumber | null
Unix ms when the message was accepted for delivery. Null until the status reaches sent.
data[].openedAtnumber | null
Unix ms of the first recorded open. Null if never opened.
data[].clickedAtnumber | null
Unix ms of the first recorded click. Null if no link was clicked.
hasMoreboolean
True when another page is available.
nextCursorstring | null
Pass as cursor to fetch the next page. Null on the last page.

Pagination

Results are cursor-paginated. Read nextCursor from a response and pass it back as cursor to get the following page; when it comes back null, you've reached the end. Cursors are opaque — don't construct or modify them.

// Walk every page. `nextCursor` is null on the last one.
let cursor: string | undefined;

do {
  const page = await yourmail.list({ limit: 100, cursor });
  for (const email of page.data) {
    // ...
  }
  cursor = page.nextCursor ?? undefined;
} while (cursor);

Errors

400validation_error

The status filter isn't a recognised status

401authentication_error

API key missing, malformed, or not recognised

403authentication_error

The key is send-only; listing requires a full-access key

Retrieve emailNext: Suppressions