REST API v1

API reference

Receive-only disposable inboxes on temp.mailsbyte.me. Create a box, poll for mail, copy OTPs. Users cannot send from these addresses.

Bearer mb_live_… JSON Receive only

Base URL

https://mailsbyte.me/api/v1

Authentication

Sign in at /login, open Profile → Developer, and create a secret key. The full value is shown once. Send it on every /api/v1 call:

Header

Authorization: Bearer mb_live_YOUR_KEY

Session cookies are for the website. Scripts should use the key, not a browser cookie.

Credits & limits

Charge create, never poll. Reads, lists, deletes, and WebSockets cost 0. Monthly Premium credits reset on the 1st UTC. Earned and purchased credits never expire.

Call	Credits
List or read a message	`0`
Create mailbox	`1`
First +30 minute extend	`0`
Extra +30 minute extend	`1`
+24 hour extend	`5`
Delete mailbox	`0`
VirusTotal scan	`1`

Plan	Monthly credits	Keys	API inboxes	Req / min	Req / day
Free	0 + earned (max 20)	2	2	30	1,000
Premium ($2.99/mo)	100	8	10	120	10,000

Earn 5 on signup, 10 on email/Google verify, 5 on first key. Builder pack is $15 / 2,000 credits (listed, checkout not live). Website New button does not spend credits. GET /api/v1/me returns your remaining credits and recent ledger. Every response includes X-Credits-Remaining, X-Quota-Cost, and X-RateLimit-Remaining.

Errors

Status	Meaning
`401`	Missing or invalid API key
`402`	Not enough credits for this call
`403`	Mailbox not owned by this key, or inbox cap
`404`	Mailbox or message gone (expired)
`429`	Per-minute limit — wait and retry

POST /mailboxes/create 1 credit

Create a mailbox

Mints an address on mailsbyte.online or temp.mailsbyte.me. Lifetime is 30 minutes (Premium can set 10 minutes–1 hour and a custom local-part). Also accepted at POST /api/v1/mailboxes.

Body	Notes
`domain`	Optional. Use `temp.mailsbyte.me`.
`local`	Optional alias. Premium only.
`ttl_seconds`	Default 1800. Capped at 3600.
`mode`	`random` (default) or `alias`.

curl -X POST https://mailsbyte.me/api/v1/mailboxes/create \
  -H "Authorization: Bearer mb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds":1800}'

POST body

{
  "domain": "temp.mailsbyte.me",
  "ttl_seconds": 1800,
  "mode": "random"
}

201 response

{
  "ok": true,
  "address": "kd32t56egi@temp.mailsbyte.me",
  "session_token": "sess_…",
  "created_at": 1786382412,
  "expires_at": 1786384212,
  "ttl_seconds": 1800,
  "pool": "temp",
  "mode": "random"
}

GET /mailboxes/:address/messages free

List messages

Returns the inbox for a box this key owns. OTP codes are extracted when present. Polling is free inside the per-minute and per-day request caps.

Query	Notes
`q`	Optional filter on from / subject / snippet.

curl https://mailsbyte.me/api/v1/mailboxes/demo@temp.mailsbyte.me/messages \
  -H "Authorization: Bearer mb_live_YOUR_KEY"

200 response

{
  "ok": true,
  "address": "demo@temp.mailsbyte.me",
  "total_count": 1,
  "expires_at": 1786384212,
  "messages": [
    {
      "id": "msg_984102",
      "from": "no-reply@service.com",
      "subject": "Your code: 884920",
      "snippet": "Your verification code is 884920.",
      "otp_code": "884920",
      "received_at": 1786382415,
      "has_html": true
    }
  ]
}

GET /mailboxes/:address/messages/:id free

Read a message

Full text, HTML, attachments metadata, and OTP if one was found.

curl https://mailsbyte.me/api/v1/mailboxes/demo@temp.mailsbyte.me/messages/msg_123 \
  -H "Authorization: Bearer mb_live_YOUR_KEY"

200 response

{
  "ok": true,
  "id": "msg_984102",
  "to": "demo@temp.mailsbyte.me",
  "from": "no-reply@service.com",
  "subject": "Your code: 884920",
  "received_at": 1786382415,
  "otp_code": "884920",
  "body_text": "Your verification code is 884920.",
  "body_html": "<p>Your verification code is <b>884920</b></p>",
  "attachments": []
}

POST /mailboxes/:address/extend 0 / 1 / 5

Extend TTL

First +30m is free. Extra +30m costs 1 credit. Pass seconds: 86400 for +24h (5 credits, 7-day lifetime cap). Website New / Extend does not spend credits.

curl -X POST https://mailsbyte.me/api/v1/mailboxes/demo@temp.mailsbyte.me/extend \
  -H "Authorization: Bearer mb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seconds":1800}'

POST body

{
  "seconds": 1800
}

200 response

{
  "ok": true,
  "address": "demo@temp.mailsbyte.me",
  "expires_at": 1786386012,
  "ttl_seconds": 3600,
  "extended_by_seconds": 1800
}

DELETE /mailboxes/:address free

Delete a mailbox

Removes the box and its mail immediately. This cannot be undone unless you stored a Premium restore key.

curl -X DELETE https://mailsbyte.me/api/v1/mailboxes/demo@temp.mailsbyte.me \
  -H "Authorization: Bearer mb_live_YOUR_KEY"

200 response

{
  "ok": true,
  "message": "Mailbox demo@temp.mailsbyte.me and associated messages purged."
}

POST /security/scan-url 1 credit

Scan a URL

Sends a link to VirusTotal (or the demo scanner if no platform key is set). Use this before opening a suspicious href from mail.

curl -X POST https://mailsbyte.me/api/v1/security/scan-url \
  -H "Authorization: Bearer mb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/login"}'

POST body

{
  "url": "https://example.com/login"
}

200 response

{
  "ok": true,
  "url": "https://example.com/login",
  "defanged_url": "hXXps://example[.]com/login",
  "threat_rating": "0/92",
  "status": "CLEAN"
}

Keys live under your profile. Inbox UI is at /inbox.