yes i used ai for the docs page because i didn't wanna make it myself
REST API for creating disposable inboxes and reading received mail.
This API lets you generate a disposable email address, then poll for messages
delivered to it. Addresses are created under a randomly chosen subdomain of one of
the domains listed above, e.g. ab@xy.example.com.
Wildcard subdomains are accepted for mail delivery, so any address at
*.<domain> will be routed correctly.
There is no authentication on these endpoints. Anyone with an EmailId
can read or delete that inbox, so treat inbox IDs as unlisted rather than secret.
| Name | Type | Required | Description |
|---|---|---|---|
| CustomId | string | No | Use a specific local-part / inbox ID instead of a random one. |
{ "Success": true, "Email": "ab3f9k@xy.example.com", "EmailId": "ab3f9k", "Domain": "example.com", "Subdomain": "xy", "CreatedAt": "2026-08-11T14:02:31.442Z" }
| Name | Type | Description |
|---|---|---|
| EmailId | string | The inbox ID returned by /api/email/create. |
{ "Success": true, "EmailId": "ab3f9k", "Count": 1, "Messages": [ { ...see below... } ] }
| Field | Type | Description |
|---|---|---|
| Id | string | Unique UUID for this message. |
| From | string | Sender address. |
| To | string | Recipient address. |
| Subject | string | Decoded subject line. |
| Body | string | Plain-text body, if present. |
| Html | string | HTML body, if present. |
| Timestamp | string | ISO 8601 receipt time. |
| Headers | object | Raw email headers as key/value pairs. |
404 if EmailId doesn't exist.| Name | Type | Description |
|---|---|---|
| EmailId | string | The inbox ID. |
| MessageIndex | integer | Zero-based index into that inbox's message list. |
{ "Success": true, "Message": { ...single message object... } }
404 if the inbox or index doesn't exist.{ "Success": true, "Message": "Email deleted" }
404 if EmailId doesn't exist.{ "Success": true, "Domains": ["example.com", ...] }
{ "Status": "ok", "Domains": [...], "ActiveEmails": 4, "TotalMessages": 11 }
Create an inbox, then poll it for new mail:
\# create an inbox curl -X POST https://tempmail.folkvalley.xyz/api/email/create \# poll for messages curl https://tempmail.folkvalley.xyz/api/email/ab3f9k/messages