Developer REST API Documentation

Creates a new disposable inbox for your account. No request body needed.

curl -X POST "https://api.zephbox.com/api/developers/aliases/" \
  -H "X-API-Key: YOUR_API_KEY"
        

const res = await fetch('https://api.zephbox.com/api/developers/aliases/', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const alias = await res.json();
console.log('Address:', alias.email);
        

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
res = requests.post('https://api.zephbox.com/api/developers/aliases/', headers=headers)
print(res.json()['email'])
        

{
  "id": 4821,
  "alias": "x7k2p9",
  "email": "[email protected]",
  "is_expired": false,
  "time_remaining": 86400,
  "message_count": 0
}
        

403 if your account doesn't have an active Full Access plan; 400 if the pool has no capacity right now (rare, retry shortly).

Lists every message received by an inbox, most recent first — use this when you need more than just the latest OTP, e.g. to render a full inbox view or audit everything an alias received.

curl -X GET "https://api.zephbox.com/api/developers/aliases/x7k2p9/messages/" \
  -H "X-API-Key: YOUR_API_KEY"
        

const res = await fetch('https://api.zephbox.com/api/developers/aliases/x7k2p9/messages/', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const messages = await res.json();
        

res = requests.get('https://api.zephbox.com/api/developers/aliases/x7k2p9/messages/', headers=headers)
messages = res.json()
        

[
  {
    "message_id": 91823,
    "subject": "Your verification code",
    "sender": "[email protected]",
    "received_at": "2026-08-29T10:15:00Z"
  }
]
        

Deactivates an inbox immediately instead of waiting for its natural expiry — useful for cleaning up test aliases at the end of a CI run rather than letting the pool fill up with dead addresses.

curl -X DELETE "https://api.zephbox.com/api/developers/aliases/x7k2p9/" \
  -H "X-API-Key: YOUR_API_KEY"
      

Returns 204 No Content on success. This deletes the alias and its messages the same way natural expiry does — it's not recoverable.

Extracts a verification code or magic link from the alias's most recent message. Returns the latest message with code/link set to null if nothing matched — never a bare 404 once mail has arrived.

curl -X GET "https://api.zephbox.com/api/developers/aliases/x7k2p9/otp/" \
  -H "X-API-Key: YOUR_API_KEY"
        

const res = await fetch('https://api.zephbox.com/api/developers/aliases/x7k2p9/otp/', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const { code, link } = await res.json();
console.log('Code:', code);
        

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
res = requests.get('https://api.zephbox.com/api/developers/aliases/x7k2p9/otp/', headers=headers)
print(res.json()['code'])
        

{
  "message_id": 91823,
  "subject": "Your verification code",
  "sender": "[email protected]",
  "received_at": "2026-08-29T10:15:00Z",
  "code": "482913",
  "link": null
}
        

Long-polls: blocks server-side (bounded, up to 20 seconds, default 15) until a new message arrives on this alias — one that arrives after the call starts, not one already sitting in the inbox — then returns its extracted code/link. Times out with 408 if nothing arrives in time. This is what you want for "trigger a signup, then wait for the OTP" rather than polling /otp/ in a loop.

curl -X GET "https://api.zephbox.com/api/developers/aliases/x7k2p9/wait-for-otp/?timeout=20" \
  -H "X-API-Key: YOUR_API_KEY"
      

Query param timeout (seconds, max 20) is optional. See our webhooks vs. polling guide for when to reach for this versus a webhook.

These management endpoints authenticate with your regular account login (JWT/session from the dashboard), not an API key — an API key can't be used to manage other API keys. GET lists your keys (hashes never shown, only the prefix). POST creates one; the raw key appears exactly once in that response.

curl -X POST "https://api.zephbox.com/api/developers/api-keys/" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI runner"}'
      

Revokes (doesn't delete the record of) a key — it stops authenticating immediately and can't be un-revoked.

Register up to 5 endpoints per account (also authenticated via your regular login, not an API key). Once registered, every new message to any of your aliases triggers a POST to your URL with an X-Kmail-Signature header — an HMAC-SHA256 hex digest of the raw request body, signed with the endpoint's own secret, so you can verify the delivery genuinely came from zephbox before trusting it. Delivery auto-retries on failure and auto-disables an endpoint that keeps failing, so a dead URL doesn't silently eat your webhook budget forever.

curl -X POST "https://api.zephbox.com/api/developers/webhooks/" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourapp.example.com/webhooks/zephbox"}'
      

Removes a registered endpoint. zephbox refuses to register a webhook URL pointing at a private/internal address (SSRF protection) — use a real, publicly reachable endpoint.