Skip to content
YourMail

API reference

API keys

GET/v1/api-keys
POST/v1/api-keys
DELETE/v1/api-keys/:id

Mint, list and revoke keys. Each key carries a scope, and the scope is the whole reason to hold more than one.

Why use this

A key that sends is a key you paste into things: a deploy, a serverless function, an AI coding agent. A key that can also mint other keys, repoint a webhook and delete the domain it sends from is a different kind of secret. scope: "send" is the one to hand out; keep a full key for whatever manages the account.

For example

Your CI pipeline mints a send-only key per environment at deploy time and revokes the previous one, so a leaked staging key can send test mail and nothing else.

Example

import { YourMail } from "yourmail";

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

// A send-only key to hand to a deploy, or to an AI coding agent.
const { key } = await yourmail.apiKeys.create({ name: "production", scope: "send" });
// `key` is returned exactly once. Store it now — it cannot be read back.

const keys = await yourmail.apiKeys.list();
await yourmail.apiKeys.revoke(keys[0].id);

Response

// 201 Created — the only time the plaintext is returned
{ "key": "yourmail_..." }

// 200 OK — GET /v1/api-keys (live keys only)
{
  "data": [
    {
      "id": "k1...",
      "name": "production",
      "last4": "9f3a",
      "scope": "send",
      "createdAt": 1756800000000,
      "lastUsedAt": 1756803600000
    }
  ]
}

The plaintext comes back once, on create, and is not stored — there is no endpoint that returns it again. DELETE revokes immediately with no grace window, so the next request carrying that key is a 401. Revoking is idempotent — a second DELETE on the same id also returns 200. The list shows live keys only, and only live keys count toward the 50-key limit.

scope"full" | "send"
full reaches every endpoint. send may call only POST /v1/emails and POST /v1/emails/batch, and gets a 403 everywhere else. Defaults to full when omitted.
last4string
The last four characters, to tell keys apart in a list. Never the hash, and never the plaintext.
lastUsedAtnumber | null
Unix ms of the most recent authenticated request on this key, or null if it has never been used. A key idle for weeks is one worth revoking.

Errors

Every endpoint on this page needs a full-access key. A send-only key is issued so it can be handed to something that only sends — if it could also manage the account, the scope would be decorative. See Errors for the full error shape.

400validation_error

name is missing, scope is not full or send, or you already hold the maximum of 50 active keys — revoke one to free a slot

401authentication_error

The API key is missing, malformed or revoked

403authentication_error

The key is send-only; minting or revoking keys requires a full-access key

404not_found

No key with that id on this account