---
title: "Sends a one-time code to an address for the calling email-less (`anonymous`) key. Nothing changes until the SAME key sends the code back to `POST /v1/keys/self/email/verify`; meanwhile `GET /v1/keys/self` shows the address as `pending_email`. Sending again (a corrected address, or a resend) replaces the pending address and voids the earlier code."
method: POST
path: "/v1/keys/self/email"
tags: ["self-serve"]
---

# Sends a one-time code to an address for the calling email-less (\`anonymous\`) key. Nothing changes until the SAME key sends the code back to \`POST /v1/keys/self/email/verify\`; meanwhile \`GET /v1/keys/self\` shows the address as \`pending_email\`. Sending again (a corrected address, or a resend) replaces the pending address and voids the earlier code.

`POST /v1/keys/self/email`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/v1/keys/self/email`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `api_key`

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.

## Request body

- AddEmailRequest: Body for `POST /v1/keys/self/email`.
  - `email` string, required: The address to add to the calling email-less key.

## Response `202`

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

- AddEmailResponse: Response for `POST /v1/keys/self/email`.
  - `expires_in_min` integer, required: Minutes the code stays valid.
  - `pending_email` string, required: The address the code was sent to, as it will be stored (lowercased).
  - `verify` string, required: What happens next.

## Other responses

- `400`: Invalid or disposable email, or a body with anything but `email`
- `401`: Missing, unknown, revoked or expired key
- `409`: The key already has an email (only email-less keys can add one)
- `422`: `email-undeliverable`: the mail provider refused this address, so no code was sent and nothing is pending; ask for the address again
- `429`: Per-key, per-IP or per-recipient daily limit, or the key's per-minute rate limit
- `503`: `mail-unavailable`: the code mail could not be handed to the mail provider, so no code exists; retry later

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)