API reference

REST over HTTPS with JSON bodies. Each operation below has its own page with its parameters, request and response examples, every error it can return, and a Try it panel. New to MailKey? Start with Getting started.

Base URL

This site documents staging:

https://api-staging.mkey.ai

Production is at https://api.mkey.ai, with its own business console and API keys. The OpenAPI 3.1 document is at /openapi.json, and the API serves the same document at /v1/openapi.json.

Authentication

Send a live API key from the business console on every request:Authorization: Bearer mk_live_.... Keys work only for a business in production. Every error uses one envelope, {"error": {"code", "message", "request_id"}}, and every response carries the same id in the X-Request-Id header.

Try it

On an operation page, Test Request opens a panel that sends the request from your browser to https://api-staging.mkey.ai. Enter your own API key under Authentication; this site has no key of its own and does not save yours. Calls are real: they count against your business's limits, and a claim saves a real grant.

Previews

Look a MailKey up and read the masked name and locality back to the person before you claim it.

Operation	Request
Look up a key	`POST /v1/previews`

Grants

Claim a preview with the person's consent, read their current name and address while the grant lasts, and release it or report returned mail.

Operation	Request
List grants	`GET /v1/grants`
Claim a preview	`POST /v1/grants`
Read current data	`GET /v1/grants/{id}`
Release a grant	`DELETE /v1/grants/{id}`
Report returned mail	`POST /v1/grants/{id}/returned-mail`

Keys

Turn what a caller said into the valid keys it could mean.

Operation	Request
Decode a transcript	`POST /v1/keys/decode`

Status

Your plan's limits and today's usage.

Operation	Request
Plan and usage	`GET /v1/status`

Voice agents

Tools for a voice agent taking a key over the phone: each answer carries a sentence to say, and previews are bound to the call. The same tools are served over MCP at mcp.mkey.ai/business.

Operation	Request
Check the key	`GET /v1/voice/business`
decode_key	`POST /v1/voice/decode`
preview_key	`POST /v1/voice/previews`
claim_key	`POST /v1/voice/grants`
get_grant	`GET /v1/voice/grants/{id}`

Webhooks

Operation	Request
List webhook endpoints	`GET /v1/webhook-endpoints`
Add a webhook endpoint	`POST /v1/webhook-endpoints`
Remove a webhook endpoint	`DELETE /v1/webhook-endpoints/{id}`
Send a test event	`POST /v1/webhook-endpoints/{id}/test`

Webhook events

The signed POSTs MailKey sends to your endpoints. None carries person data; read the grant for the current name and address.

Operation	Event
grant.approved	`grant.approved`
grant.denied	`grant.denied`
grant.revoked	`grant.revoked`
address.change_scheduled	`address.change_scheduled`
address.changed	`address.changed`
address.confirmed	`address.confirmed`
name.changed	`name.changed`