POST/v1/keys/self/email

API key required, sent as Authorization: Bearer snk_… or ?api_key=snk_….

What it does

Quota-free like the rest of /v1/keys/self, and capped at identity::MAX_EMAIL_ADDS_PER_KEY_PER_DAY per key and identity::MAX_EMAIL_ADDS_PER_IP_PER_DAY per IP (an IPv6 /64 counts as one) per UTC day, and at the per-network plus per-address mail budget every signup already has. Unlike signup, a spent mail budget is a 429 here: no code is minted that was not mailed, so the budget also caps the codes anyone can guess at for one mailbox.

The answer is the same whether or not the address already has an account: a code is mailed either way, and only redeeming it (which takes the code from the mailbox) can tell.

Call it

bash

curl -fsS -X POST "https://api.mapmap.ai/v1/keys/self/email" \
  -H "Authorization: Bearer $MAPMAP_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Request body

application/json · AddEmailRequest

Field	Type	Required	Description
email	string	yes	The address to add to the calling email-less key.

Responses

202Code sent; send it back from the same key to POST /v1/keys/self/email/verify

Field	Type	Required	Description
expires_in_min	integer	yes	Minutes the code stays valid.
pending_email	string	yes	The address the code was sent to, as it will be stored (lowercased).
verify	string	yes	What happens next.

400Invalid or disposable email, or a body with anything but email

401Missing, unknown, revoked or expired key

409The key already has an email (only email-less keys can add one)

429Per-key, per-IP or per-recipient daily limit, or the key's per-minute rate limit

Error bodies follow the shared problem model documented on API conventions.

Also under self-serve

GET /v1/jobs GET /v1/jobs/{id}POST /v1/keys DELETE /v1/keys/self GET /v1/keys/self POST /v1/keys/self/email/verify POST /v1/keys/self/webhook-secret GET /v1/keys/verify POST /v1/keys/verify POST /v1/keys/verify/deny POST /v1/keys/verify/details GET /v1/usage POST /v1/x402/topup

Generated from https://api.mapmap.ai/openapi.json on 2026-10-02 · operationId add_email