API Documentation

Quick start

This API is free, requires no authentication, and supports CORS. All responses are JSON. Perfect for sign-up automation, OTP detection, and email verification links.

Base URL

https://cloud-mail-magic-g9il8.sevalla.app/api/public/v1

🔑 Authentication (Admin API)

Some endpoints (e.g. share) require an API key. Create one in the admin panel under Settings → API Keys.

1. Go to the app → Settings → API Keys → fill in a label → click Create
2. Copy the key immediately — it is only shown once
3. Pass the key in the Authorization header:

Authorization: Bearer cm_abc123def456...

Example

# Share an inbox (requires API key)
curl -X POST https://cloud-mail-magic-g9il8.sevalla.app/api/db/inboxes/INBOX_ID/share \
  -H "Authorization: Bearer cm_abc123def456..."

# Response
{ "token": "share-token-here" }

💡 API keys start with cm_ and never expire until revoked. Keep them secret.

Endpoints

GET/domains

List active domains available for creating inboxes.

Example

curl https://cloud-mail-magic-g9il8.sevalla.app/api/public/v1/domains

Response

{
  "domains": ["example.com", "mail.dev"]
}

POST/inboxes

Create a new inbox. Body is optional. Username & domain are picked at random if omitted.

Body (optional)

{
  "username": "john.doe",   // optional, will be sanitized
  "domain": "example.com"   // optional, must be from /domains
}

Example

curl -X POST https://cloud-mail-magic-g9il8.sevalla.app/api/public/v1/inboxes \
  -H "Content-Type: application/json" \
  -d '{"username":"john.doe"}'

Response (201)

{
  "id": "uuid",
  "address": "[email protected]",
  "expires_at": "2025-01-02T00:00:00Z",
  "created_at": "2025-01-01T00:00:00Z"
}

GET/inboxes/{address}

Fetch messages for an inbox. Each message automatically includes otp & verification_link when detected.

Query

limit — number of messages (1–100, default 20)
body — set to false to omit the full body

Example

curl "https://cloud-mail-magic-g9il8.sevalla.app/api/public/v1/inboxes/[email protected]?limit=10"

Response

{
  "inbox": { "id": "...", "address": "...", "expires_at": "...", "created_at": "..." },
  "count": 1,
  "messages": [
    {
      "id": "uuid",
      "from": { "address": "[email protected]", "name": "Service" },
      "to": "[email protected]",
      "subject": "Your code is 123456",
      "received_at": "2025-01-01T00:00:00Z",
      "preview": "Your verification code...",
      "otp": "123456",
      "verification_link": "https://svc.com/verify?token=abc",
      "links": ["https://svc.com/verify?token=abc", "https://svc.com/reset?t=xyz"],
      "text": "...",
      "html": "...",
      "attachments": []
    }
  ]
}

GET/inboxes/{address}/latest

Fetch the most recent message. Use this to poll until an OTP or verification link arrives.

Query

require=otp — return the first message containing an OTP
require=link — return the first message containing a verification link

Poll example for OTP

# wait for OTP (404 = not yet)
curl "https://cloud-mail-magic-g9il8.sevalla.app/api/public/v1/inboxes/[email protected]/latest?require=otp"

Response

{
  "message": {
    "otp": "123456",
    "verification_link": "https://...",
    "subject": "...",
    "from": { "address": "...", "name": "..." },
    "received_at": "..."
  }
}

GET/share/{token}

Get the email address and all messages of a shared inbox. No authentication required. Auto-refreshes on the web UI every 15 seconds.

Base: /api/public

Example

curl "https://cloud-mail-magic-g9il8.sevalla.app/api/public/share/TOKEN"

Response

{
  "address": "[email protected]",
  "messages": [
    {
      "id": "uuid",
      "from_address": "[email protected]",
      "from_name": "Service",
      "subject": "Welcome!",
      "text_body": "...",
      "html_body": "...",
      "attachments": [],
      "received_at": "2025-01-01T00:00:00Z"
    }
  ]
}

💡 The token is obtained by clicking the Share button in the web app, or via the admin API: POST /api/db/inboxes/{id}/share (requires Authorization: Bearer <jwt-or-api-key>).

JavaScript example

// Create an inbox then poll until the OTP arrives
const base = "https://cloud-mail-magic-g9il8.sevalla.app/api/public/v1";
const r = await fetch(base + "/inboxes", { method: "POST" });
const { address } = await r.json();

let otp = null;
for (let i = 0; i < 30 && !otp; i++) {
  await new Promise(r => setTimeout(r, 2000));
  const res = await fetch(`${base}/inboxes/${address}/latest?require=otp`);
  if (res.ok) otp = (await res.json()).message?.otp;
}
console.log("address:", address, "otp:", otp);

Notes

Inboxes stay active for 24 hours, then expire automatically (HTTP 410).
Shared inboxes never expire — they remain active until the admin removes them.
Addresses are case-insensitive.
Be reasonable — avoid polling faster than once per second.
Status codes: 400 bad input, 404 not found, 409 address conflict, 410 expired.