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" } ] }

Why Use Our Disposable Email Service?

temp-mail.agency provides the best free temp mail, temp email, and disposable email services online. Whether you need a fake email generator to avoid spam, a temporary email for signing up to online platforms, or a throwaway email for free trials, our email generator has you covered. Get your secure tempmail instantly with no registration required.