temp mail API Documentation
Integrate our temporary email generator directly into your applications. The API is free to use and provides access to our premium domains.
Base URL: https://api.temp-mail.agency/api
POST /client/create
Initialize a client session. You must call this endpoint first to obtain a unique UUID to use in all subsequent requests.
Parameters (x-www-form-urlencoded):
app_uuid(string) - Set to"a5x-cj6a-ka1q".
Response Example:
{
"client": {
"uuid": "417da78c-e6bd-498f-8eae-da59b6ccd3e5",
"ref_id": "6074671-7605",
"type": 0
},
"email": {
"id": 10879733,
"alias": "rijofos",
"domain_name": "koletter.com",
"address": "rijofos@koletter.com"
}
}
POST /domains
Retrieve a list of all currently active premium domains that can be used to generate custom emails.
Parameters (x-www-form-urlencoded):
uuid(string) - The UUID obtained from /client/create.
Response Example:
{
"domains": [
{
"id": 3,
"name": "mailfrs.com",
"tld": "com",
"type": 0
},
{
"id": 4,
"name": "koletter.com",
"tld": "com",
"type": 0
}
]
}
POST /email/custom
Generate a new temporary email address with a custom username on a specific domain.
Parameters (x-www-form-urlencoded):
uuid(string) - The UUID obtained from /client/create.alias(string) - The requested username prefix.domain_id(integer) - The ID of the domain fetched from /domains.
Response Example:
{
"email": {
"id": 10879745,
"alias": "jareme",
"domain_name": "mailfrs.com",
"address": "jareme@mailfrs.com",
"type": 0,
"created_at": "2026-06-17T15:00:00.000000Z"
}
}
POST /messages
Fetch the inbox contents for a specific email address.
Parameters (x-www-form-urlencoded):
uuid(string) - The UUID obtained from /client/create.selected_email_id(integer) - The email ID returned from /email/custom or /client/create.
Response Example:
{
"messages": [
{
"id": 12,
"from": "GitHub ",
"subject": "Verify your temporary email address",
"body": "Please click the link below...",
"created_at": "2026-06-17T15:05:00.000000Z"
}
]
}