API docs · MailIcloud TempMail

Quick start

The common case: create an address, wait for the verification mail, read the code. Exactly two requests.

1

Ask for an address

Leave user empty and the system generates 10 random characters; leave domain empty too to pick a random open domain.
```
curl "https://mailicloud.store/api/address?domain=mailicloud.store"
```
```
{"address":"k3n8fq2wla@mailicloud.store"}
```

2

Read the inbox with content included

Use that address wherever you need to sign up, then run this. html=0 drops the HTML part — looking for an OTP only needs bodyText.

curl "https://mailicloud.store/api/inbox?address=k3n8fq2wla@mailicloud.store&html=0"

{
  "address": "k3n8fq2wla@mailicloud.store",
  "count": 1,
  "messages": [
    {
      "key": "6a81aaf2e7d7885b3d1af630ef18b047f2a6b38f4496672b2322eb5422c9df25",
      "messageId": "<abc123@shop.com>",
      "to": "k3n8fq2wla@mailicloud.store",
      "from": "no-reply@shop.com",
      "fromName": "Shop",
      "subject": "Your verification code",
      "bodyText": "Your code is 483920",
      "receivedAt": "2026-07-31T10:08:42Z"
    }
  ]
}

Authentication and limits

The API works without a key. A key only lifts the two limits below.

Without a key

120 requests per minute per IP
Only mail from the last 15 minutes

With a key

No request limit
Mail past its visibility window is readable too

Send the key either way, whichever suits you:

curl "https://mailicloud.store/api/inbox?address=abc@mailicloud.store&key=KEY_CUA_BAN"

curl -H "Authorization: Bearer KEY_CUA_BAN" \
     "https://mailicloud.store/api/inbox?address=abc@mailicloud.store"

Keys are created by the administrator in Settings. There is no self-service sign-up for keys.

Every endpoint

GET/api/address

Create an address. Nothing is stored — the address only really exists once the first mail arrives.

Parameter	Required	Description
`domain`	no	Empty picks a random open domain (each call may return a different domain)
`user`	no	The part before `@`. Empty generates 10 `[a-z0-9]` characters

curl "https://mailicloud.store/api/address?domain=mailicloud.store&user=dat-ten-rieng"

{"address":"dat-ten-rieng@mailicloud.store"}

GET/api/inboxrecommended

The whole inbox with content in a single call. This is the endpoint for tools fetching an OTP — no follow-up call per mail.

Parameter	Required	Description
`address`	yes	Full address, domain included
`limit`	no	How many mails to return. Default 20, capped at 100
`html`	no	Set to `0` to drop `bodyHtml` — usually 80–90% of the payload
`since`	no	Unix timestamp (seconds); only return mail received at or after it. For polling new mail without client-side filtering
`from`	no	Filter by sender — case-insensitive substring, matches both address and display name (e.g. `huawei`, `facebook`)

curl "https://mailicloud.store/api/inbox?address=abc@mailicloud.store&from=huawei&since=1754899200&html=0"

Each mail includes otp = the verification code extracted automatically (empty if none). No need to parse it yourself.

{
  "address": "abc@mailicloud.store",
  "count": 1,
  "messages": [
    {
      "key": "6a81aaf2e7d7885b3d1af630ef18b047f2a6b38f4496672b2322eb5422c9df25",
      "from": "no-reply@facebookmail.com",
      "fromName": "Facebook",
      "subject": "Your verification code",
      "otp": "483920",
      "bodyText": "Your code is 483920",
      "receivedAt": "2026-07-31T10:08:42Z"
    }
  ]
}

GET/api/messages

Summaries only, no content. Much lighter, so it suits repeated polling for new mail; to read a body, follow up with /api/message/{key}.

Parameter	Required	Description
`address`	yes	Returns up to the 100 newest mails

curl "https://mailicloud.store/api/messages?address=abc@mailicloud.store"

{
  "address": "abc@mailicloud.store",
  "count": 1,
  "messages": [
    {
      "key": "6a81aaf2e7d7885b3d1af630ef18b047f2a6b38f4496672b2322eb5422c9df25",
      "from": "no-reply@shop.com",
      "fromName": "Shop",
      "subject": "Your verification code",
      "snippet": "Your code is 483920",
      "hasHtml": true,
      "receivedAt": "2026-07-31T10:08:42Z"
    }
  ]
}

GET/api/message/{key}

One full mail, fetched by the key you got from /api/messages.

curl "https://mailicloud.store/api/message/6a81aaf2e7d7885b3d1af630ef18b047f2a6b38f4496672b2322eb5422c9df25"

GET/api/stream

Server-Sent Events. New mail is pushed immediately, no polling needed. Each mail event carries exactly one element shaped like those in /api/messages.

curl -N "https://mailicloud.store/api/stream?address=abc@mailicloud.store"

: connected

event: mail
data: {"key":"6a81aaf2…","from":"no-reply@shop.com","subject":"Your verification code",…}

: heartbeat

Error codes

Code	Means
`400`	Malformed address, a domain that is not open, or `limit` outside 1–100
`404`	No mail with that `key` — or it is past its visibility window and you sent no key
`429`	Over 120 requests/minute. Wait for the next minute or use an API key
`503`	No receiving domain has been opened yet

Error bodies are always {"error":"..."}.

What to know before relying on this

Inboxes are public

There is no password per inbox. Anyone who knows the address reads the mail in it. Do not use it for accounts that matter or for sensitive data.

Mail hides itself after 15 minutes

Past that window mail disappears from the public API. It stays readable with an API key.

Deleted for good after 72 hours

Past that point mail is removed from the database and cannot be recovered, not even with a key.

No attachments

Attachments are dropped on arrival. The API returns only the text and HTML of the body.