# MailReveal: email activity for people and agents

Base URL: https://mailreveal.com
OpenAPI: https://mailreveal.com/api/openapi.json
MCP Streamable HTTP (POST): https://mailreveal.com/mcp

## Get a key
1. POST https://mailreveal.com/api/v1/agent-requests with JSON {"name":"My assistant","purpose":"Prepare trackers and report recent activity"}.
2. Keep claim_token private. Show approval_url and code to the workspace owner. Registration does not grant access.
3. POST claim_url with JSON {"claim_token":"<private token>"} no more often than every 5 seconds. Pending and denied requests have no key.
4. After owner approval, the first successful claim returns key.token and key.scopes. Store the token securely. It cannot be retrieved again. Requests expire after 30 minutes.
5. Use Authorization: Bearer <key.token> for API and MCP. Discover scopes via GET /api/v1/capabilities.

## Track an individual email
POST /api/v1/messages with recipient, subject, body and an Idempotency-Key header. The returned signatureHtml and pixelUrl are unique to this email. Insert before sending in an HTML-capable email client. Preparation does not send email.

## Reusable signature across clients
POST /api/v1/signatures with {"label":"Work signature","name":"Alex Morgan","title":"Customer success","email":"alex@example.com"}.
Requires signatures:write. Response includes html and pixelUrl. Paste the rendered HTML into the email client's signature editor. Use a public HTTPS deployment for recipient loads. Plain-text signatures and image-blocking clients do not support this tracker. A reused tracker reports aggregate signature activity; it cannot identify which email or recipient loaded the image. Previews, proxies, privacy services and automated fetches can produce events.
GET /api/v1/signatures and /api/v1/signatures/:id require signatures:read. PATCH /api/v1/signatures/:id with {"paused":true} stops recording future activity, and requires signatures:write.

## Events and webhooks
GET /api/v1/events requires events:read. Events include email.image_loaded or signature.image_loaded, confidence and source; never treat them as confirmed reads.
POST /api/v1/webhooks with {"url":"https://your-approved-host.example/events"} requires webhooks:write or owner credentials. The operator must allow the exact host in WEBHOOK_ALLOWED_HOSTS. The signing secret is returned only at creation.
Verify X-Readout-Signature = sha256=HMAC-SHA256(secret, X-Readout-Timestamp + "." + raw_body). Enforce a timestamp window, deduplicate X-Readout-Event-Id, and return 2xx after durable acceptance. Retries use the same event ID and may redeliver. GET /api/v1/deliveries requires webhooks:read.

## Send only with human authorization
Preparing or inserting a tracker never sends mail. send_email via MCP requires confirmed:true and email:send. This boolean is a client assertion, not a human approval service. Obtain the user's authorization for recipient and content before calling it. Gmail must be connected or SMTP configured. A Google connection alone cannot inject images into arbitrary emails sent in native Gmail.

## Workspace model
This deployment is a single owner-controlled workspace, not a public multi-tenant service. Owners connect Gmail in the app and approve agents with limited scopes. Never share the workspace admin token with agents.