Getting started

Quickstart

POST/v1/emails

YourMail is a transactional email API for UK senders — send receipts, password resets, and welcome messages from your own domain, with full delivery tracking. Sending runs through London (eu-west-2).

Set up with AI

Prefer to let your own coding agent do it? Copy the prompt below, or point any agent at /llms.txt.

Paste this into your AI coding agent — it audits your app, proposes where email should live, then wires it end-to-end.

Loading your setup…

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.

from: no-reply@yourmail.devTest mode— sending from the shared sandbox address works on any key and needs no verified domain. The server doesn't touch from — sending from it is what selects test mode in the first place — but it does rewrite the recipients: any address outside your signup email or an AWS SES simulator address is dropped, and cc/bcc are cleared. If nothing valid is left, the mail goes to your signup address — so it lands in your inbox, not the one you typed. (The one case that does fail is an account with no verified email on file, which returns a sandbox_recipient error.) Test mode is capped at 20 sends per day; past that you get a 429 whose retryAfter points at the next UTC midnight. Send from an address on a verified sending domain instead to go live and lift the cap.

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 sandbox 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",       // sandbox 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 sandbox 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. That is all — the API signature is identical. See Send email for the full request schema, optional headers, and batch sending.

Check delivery

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

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.

Introduction Next: Domains & DNS