API reference

Retrieve email

GET/v1/emails/:id

Fetch the current status and metadata for any email by its ID.

Why use this

After you send an email, retrieve lets you check exactly what happened to it — was it delivered, did it bounce, or did the recipient mark it as spam? It's how you answer support questions and confirm important messages actually arrived, without leaving your own app.

For example

A user says they never got their password-reset link. You look the email up by its ID and see it bounced — so you know to ask them to check the address.

Example

import { YourMail } from "yourmail";

const yourmail = new YourMail(process.env.YOURMAIL_API_KEY!);

const email = await yourmail.get("jn7abc123def456");
console.log(email.status);   // "delivered"
console.log(email.sentAt);   // Unix ms timestamp

const res = await fetch(
  "https://api.yourmail.dev/v1/emails/jn7abc123def456",
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  }
);

const email = await res.json();

curl https://api.yourmail.dev/v1/emails/jn7abc123def456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response fields

// 200 OK
{
  "id": "jn7abc123def456",
  "status": "delivered",
  "from": "hello@mail.acme.com",
  "to": ["alice@example.com"],
  "cc": [],
  "bcc": [],
  "replyTo": null,
  "subject": "Welcome to Acme",
  "html": "<p>Welcome to Acme</p>",
  "text": "Welcome to Acme",
  "tags": [{ "name": "campaign", "value": "welcome" }],
  "sesMessageId": "0102018f1234abcd-...",
  "error": null,
  "createdAt": 1750000000000,
  "scheduledAt": null,
  "sentAt": 1750000001234,
  "openedAt": 1750000090000,
  "clickedAt": null,
  "events": [
    { "type": "send",      "occurredAt": 1750000001234, "meta": null },
    { "type": "delivered", "occurredAt": 1750000004567, "meta": null },
    { "type": "open",      "occurredAt": 1750000090000,
      "meta": { "userAgent": "Mozilla/5.0 ..." } }
  ]
}

idstring: Unique email identifier.
statusstring: Current delivery status. See lifecycle below.
fromstring: Sender address as supplied in the send request.
tostring[]: Recipient addresses.
ccstring[]: Carbon-copy recipients. Empty array when none were set.
bccstring[]: Blind carbon-copy recipients. Empty array when none were set.
replyTostring | null: Reply-To address as supplied on the send request. Null when none was set.
subjectstring: Email subject line.
htmlstring | null: The HTML body as sent. Null once your account's retention window has stripped the body — the message and its metadata remain, only the content is gone.
textstring | null: The plain-text body as sent. Null when none was supplied, or once retention has stripped it.
tags{name, value}[]: Tags supplied on the send request. Empty array when none were set.
sesMessageIdstring | null: AWS SES message ID. Set once SES accepts the message (status sent or later). Null until then.
errorstring | null: Human-readable error description. Set when status is failed. Null otherwise.
createdAtnumber: Unix millisecond timestamp when the email was created.
scheduledAtnumber | null: Unix millisecond timestamp the send is booked for. Null on an ordinary immediate send. Cancellable until it dispatches — see /docs/api/cancel.
sentAtnumber | null: Unix millisecond timestamp when SES accepted the message. Null until status reaches sent.
openedAtnumber | null: Unix millisecond timestamp of the first open. Null if never opened.
clickedAtnumber | null: Unix millisecond timestamp of the first click. Null if never clicked.
eventsobject[]: The delivery timeline, oldest first, capped at the 100 most recent events. See below.

Delivery timeline

Every status change and engagement signal the provider reported for the message, oldest first. This is where a failure explains itself: a bounce carries the type, sub-type, and the raw SMTP response from the receiving server.

// A bounced message carries the reason on its timeline
{
  "id": "jn7abc123def456",
  "status": "bounced",
  "error": "Bounced",
  "events": [
    { "type": "send", "occurredAt": 1750000001234, "meta": null },
    {
      "type": "bounce",
      "occurredAt": 1750000003000,
      "meta": {
        "bounceType": "Permanent",
        "bounceSubType": "General",
        "diagnosticCode": "smtp; 550 5.1.1 user unknown"
      }
    }
  ]
}

typestring: send, delivered, bounce, complaint, open, click, or a future provider event.
occurredAtnumber: Unix millisecond timestamp at which the provider recorded the event.
metaobject | null: Diagnostic detail on a bounce or complaint, engagement detail on an open or click. Null on events that carry none, such as send and delivered.
meta.bounceTypestring?: Permanent, Transient, or Undetermined. Branch on this to decide whether a retry is worth attempting.
meta.bounceSubTypestring?: e.g. General, NoEmail, MailboxFull, MessageTooLarge, ContentRejected.
meta.diagnosticCodestring?: The raw SMTP response from the receiving server.
meta.complaintFeedbackTypestring?: e.g. abuse, fraud, not-spam. Present on complaint events.
meta.linkstring?: The URL that was clicked. Present on click events.
meta.userAgentstring?: The recipient's user-agent. Present on open and click events.

Status lifecycle

Statuses transition in one direction. Delivery events (bounces, complaints, confirmations) arrive asynchronously from AWS SES after the initial send.

// Status lifecycle
//
//  scheduled ──(booked time)──► queued
//      └──(DELETE before it goes)──► canceled
//
//  queued ──(SES accept)──► sent ──(delivery event)──► delivered
//                                                  └──► bounced
//                                                  └──► complained
//         (SES reject or internal error)──► failed

scheduled

Booked for a future time via scheduledAt. Nothing is charged or sent yet, and it can still be cancelled.

queued

Pending dispatch to SES.

sent

Accepted by AWS SES. sesMessageId is set. Waiting for delivery event.

delivered

SES confirmed successful delivery to the recipient's mail server.

bounced

SES reported a permanent or temporary delivery failure.

spam

Recipient marked the email as spam via their mail client.

failed

SES rejected the send or an internal error occurred. See the error field.

cancelled

A scheduled send cancelled before it dispatched. A deliberate outcome, not a failure — which is why it is not folded into failed.

Errors

401authentication_error

API key missing, malformed, or not recognised

404not_found

No email with that ID exists in this account

Send batch Next: List emails