API Documentation
Premium feature — use your API key to integrate Ephemask into your workflow.
Authentication
All requests require your API key as a Bearer token:
Authorization: Bearer YOUR_API_KEY Get your API key from the Account page.
Base URL
https://api.ephemask.com Rate Limits
Endpoints
/inbox Create a new random inbox. Optionally pass TTL (premium only).
Request body (optional, premium):
{
"ttl_minutes": 30
} Response:
{
"address": "x7k2m9p4@ephemask.com",
"expires_at": 1776000000,
"token": "inbox_token_here",
"no_ads": false
} Use the token for all subsequent inbox operations.
/inbox/vanity PREMIUM Create an inbox with a custom address.
Request body:
{
"local_part": "john",
"domain": "ephemask.com",
"ttl_minutes": 60
} Response: same as POST /inbox
/inbox/{address} Get inbox details and message list. Requires inbox token.
Response:
{
"address": "x7k2m9p4@ephemask.com",
"expires_at": 1776000000,
"messages": [
{
"message_id": "abc123",
"from": "sender@example.com",
"subject": "Hello",
"received_at": 1775999000,
"preview": "Message preview..."
}
],
"no_ads": false
} /inbox/{address}/messages/{messageId} Get full message content. Requires inbox token.
Response:
{
"message_id": "abc123",
"from": "sender@example.com",
"subject": "Hello",
"received_at": 1775999000,
"preview": "...",
"body_text": "Plain text body",
"body_html": "<p>HTML body</p>"
} /inbox/{address} Delete an inbox and all its messages immediately. Requires inbox token.
/user/me Get your account info. Requires API key.
{
"user_id": "u_abc123",
"tier": "premium",
"no_ads": true,
"inbox_count": 3,
"created_at": 1775900000
} /user/inboxes List all active inboxes. Requires API key.
/health Check API status. No authentication required.
{"status": "ok"} Quick Example
# Create inbox curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \ https://api.ephemask.com/inbox # Check messages (use inbox token from response) curl -H "Authorization: Bearer INBOX_TOKEN" \ https://api.ephemask.com/inbox/x7k2m9p4@ephemask.com # Read a message curl -H "Authorization: Bearer INBOX_TOKEN" \ https://api.ephemask.com/inbox/x7k2m9p4@ephemask.com/messages/abc123 # Download an attachment curl -H "Authorization: Bearer INBOX_TOKEN" \ https://api.ephemask.com/inbox/x7k2m9p4@ephemask.com/messages/abc123/attachments/0 \ -o file.pdf
Webhooks
Configure a webhook URL on your account page and receive a POST request for every email that lands in any of your inboxes.
Headers sent with each delivery:
Content-Type: application/json X-Ephemask-Event: email.received X-Ephemask-Signature: sha256=<hex_hmac_of_body> User-Agent: Ephemask-Webhook/1.0
Payload:
{
"event": "email.received",
"inbox_address": "x7k2m9p4@ephemask.com",
"message_id": "abc123",
"from": "sender@example.com",
"subject": "Hello",
"received_at": 1714003200,
"attachment_count": 1
}
Compute HMAC-SHA256(body, your_secret) and compare to X-Ephemask-Signature to verify the request came from Ephemask. The body itself never includes the email content — fetch the message via the API using the message_id.
Quick verify with bash + openssl:
# Use printf '%s' (not echo -n) so no CR/LF is appended on Windows shells printf '%s' '<raw_body_bytes>' | openssl dgst -sha256 -hmac '<your_secret>'
Delivery is best-effort with a 5s timeout and no retry. Your inbox always has the message regardless of delivery success.