Skip to content
Documentation menu
docs / api / post-v1-keys-self-email
Keys and account

POST/v1/keys/self/email

Access and price

AuthAn API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Not metered: it draws no quota and no credit. Needs a full key; a browser (maps) key is refused.
PriceNot metered: no quota, no credit.

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 '{"email":"string"}'

Request body

application/json · AddEmailRequest

FieldTypeRequiredDescription
emailstringyesThe address to add to the calling email-less key.

Example: A request assembled from this schema's own field examples, enums, defaults and types; not a recorded call

json
{
  "email": "string"
}

Responses

202Code sent; send it back from the same key to POST /v1/keys/self/email/verify
FieldTypeRequiredDescription
expires_in_minintegeryesMinutes the code stays valid.
pending_emailstringyesThe address the code was sent to, as it will be stored (lowercased).
verifystringyesWhat happens next.

Example: A response assembled from this schema's own field examples, enums, defaults and types; not a recorded call

json
{
  "expires_in_min": 0,
  "pending_email": "string",
  "verify": "string"
}
400Invalid or disposable email, or a body with anything but email

application/problem+json · Problem

401Missing, unknown, revoked or expired key. Also: No key, or a missing, malformed, unknown, revoked or expired one (unauthorized)

application/problem+json · Problem

403A browser (maps-scoped) key on a route that needs a full-scope key (scope-insufficient)

application/problem+json · Problem

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

application/problem+json · Problem

413The request declares a body larger than 1048576 bytes (plain text, not problem+json)

text/plain

422email-undeliverable: the mail provider refused this address, so no code was sent and nothing is pending; ask for the address again

application/problem+json · Problem

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

application/problem+json · Problem

503mail-unavailable: the code mail could not be handed to the mail provider, so no code exists; retry later

application/problem+json · Problem

504The request did not finish within the gateway's request deadline (request-timeout)

application/problem+json · Problem

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

Also under Keys and account

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