Quickstart

Create an API key

Open the API Keys page and create a key — you will only see the secret once, so save it somewhere safe.

Send your first email

Your API base URL https://api.yourmail.dev is already filled in below. Just replace YOUR_KEY with the key you just created and run it. The snippet below sends from the shared test-mode address, which delivers only to your signup email or an @simulator.amazonses.com address — any other recipient is rewritten to your signup inbox.

Using the SDK? Install it first — the fetch and cURL tabs need no dependencies.

npm install yourmail

import { YourMail } from "yourmail";

const yourmail = new YourMail("yourmail_YOUR_KEY");

await yourmail.send({
  from: "no-reply@yourmail.dev",       // test-mode sender — no verified domain needed
  to:   "you@example.com",            // rewritten to your signup email
  subject: "Hello from YourMail",
  html: "<p>It works. Ship it.</p>",
});

const res = await fetch(
  "https://api.yourmail.dev/v1/emails",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer yourmail_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      from:    "no-reply@yourmail.dev",
      to:      "you@example.com",
      subject: "Hello from YourMail",
      html:    "<p>It works. Ship it.</p>",
    }),
  }
);

const { id } = await res.json();
console.log("Email queued:", id);

curl -X POST https://api.yourmail.dev/v1/emails \
  -H "Authorization: Bearer yourmail_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from":    "no-reply@yourmail.dev",
    "to":      "you@example.com",
    "subject": "Hello from YourMail",
    "html":    "<p>It works. Ship it.</p>"
  }'

A successful request returns { id }. The email transitions from queued to sent to delivered (or bounced / failed) as SES confirms delivery. If the email doesn't appear in your inbox, check your spam folder — test emails from the shared sender often land there until you're sending from your own verified domain.

Verify your domain

To send from your own address you need a verified domain. Go to Domains and add your sending domain. YourMail will provide three DKIM CNAME records (optionally plus a recommended DMARC TXT). Add them to your DNS provider — most domains verify within a few minutes. See Domains & DNS for full instructions and troubleshooting.

Go live

Once your domain is verified, swap the test-mode sender for an address on your verified domain — set the from field to it. The key stays the same — there is no separate live key to switch to, and the API signature is identical. See Send email for the full request schema, optional headers, and batch sending.

Sending to real users has one more gate. Until your account is approved, a live send can only reach an address at a domain you have verified, your signup email, or an AWS SES simulator address — anything else returns 403 account_pending_review. Approval usually takes a few hours, and you can build and test the whole integration against your own domain while you wait; your plan's daily limits and the first-week ramp still apply. See Limits & review.

Check delivery

Retrieve an email at any point to check its current status. The full lifecycle is: queued → sent → delivered (or bounced / complained / failed).

This one needs a full-access key. A send-only key can reach only the two send endpoints, and gets a 403 here — check the Logs tab instead.

const email = await yourmail.get(id);
console.log(email.status);
// queued → sent → delivered
//               ↳ bounced | complained | failed

You can also watch the full send history and live status for every email in the Dashboard.