Jo Mail API for developers

Create temporary inboxes and read incoming messages from your own code, for example to test sign-up flows.

Authentication

Create a key in your dashboard and send it with each request in one of these headers.

X-Api-Key: jm_xxxxxxxxxxxxxxxx
# or
Authorization: Bearer jm_xxxxxxxxxxxxxxxx

Endpoints

POST   /api/inbox                         create an inbox   {"guest":true,"name":"optional","domain":"jo-mail.org","ttl_minutes":60}
                                          -> {"inbox":{"id":1,"address":"...","expires_at":...},"key":"1.abcdef..."}
GET    /api/inbox                         list messages     (header X-Inbox: <key>)
GET    /api/inbox/wait?after=<lastId>     long-poll: returns {"changed":true} as soon as a new message arrives
GET    /api/inbox/messages/{id}           read one message  (subject, from, text, html, attachments)
GET    /api/inbox/attachments/{id}        download an attachment
DELETE /api/inbox/messages/{id}           delete a message
POST   /api/inbox/renew                   extend the lifetime
DELETE /api/inbox                         delete the inbox

Examples

# 1) create an inbox
curl -s -X POST https://jo-mail.org/api/inbox \
  -H "X-Api-Key: $JM_KEY" -H "Content-Type: application/json" \
  -d '{"guest":true}'

# 2) wait for mail, then read it
curl -s "https://jo-mail.org/api/inbox/wait?after=0" -H "X-Inbox: $INBOX_KEY"
curl -s https://jo-mail.org/api/inbox -H "X-Inbox: $INBOX_KEY"

// JavaScript
const r = await fetch('https://jo-mail.org/api/inbox', {
  method: 'POST',
  headers: { 'X-Api-Key': KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ guest: true }),
});
const { inbox, key } = await r.json();
console.log(inbox.address);   // use it to sign up, then poll /api/inbox/wait

Limit: 600 inboxes per hour per key. Inbox keys are secret: whoever has the key can read that inbox.