YourMail

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!, {
  baseUrl: process.env.YOURMAIL_BASE_URL!,
});

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

Response fields

// 200 OK
{
  "id": "jn7abc123def456",
  "status": "delivered",
  "from": "hello@mail.acme.com",
  "to": ["alice@example.com"],
  "subject": "Welcome to Acme",
  "tags": [{ "name": "campaign", "value": "welcome" }],
  "sesMessageId": "0102018f1234abcd-...",
  "error": null,
  "createdAt": 1750000000000,
  "sentAt": 1750000001234,
  "openedAt": 1750000090000,
  "clickedAt": null,
  "events": [
    { "type": "send",      "occurredAt": 1750000001234, "meta": null },
    { "type": "delivered", "occurredAt": 1750000004567, "meta": null },
    { "type": "open",      "occurredAt": 1750000090000, "meta": null }
  ]
}
idstring
Unique email identifier.
statusstring
Current delivery status. See lifecycle below.
fromstring
Sender address as supplied in the send request.
tostring[]
Recipient addresses.
subjectstring
Email subject line.
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.
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. Null on events that carry none (delivery, opens, clicks).
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.

Status lifecycle

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

// Status lifecycle
//
//  queued ──(SES accept)──► sent ──(delivery event)──► delivered
//                                                  └──► bounced
//                                                  └──► complained
//         (SES reject or internal error)──► failed
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.

Errors

401authentication_error

API key missing, malformed, or not recognised

404not_found

No email with that ID exists in this account

Send batchNext: List emails