temp mail API Documentation

Developers: get your free API key

The REST API v1 and the MCP server for AI agents share one free key — 100 emails/day. Sign in with Google, no card, no forms.

Integrate our temporary email generator directly into your applications. The generator draws on two public, receive-only providers: Temp Mail (the endpoints below) and Edu Mail (documented at the end of this page). All domains returned by both providers appear in the generator's domain selector.

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

Edu Mail API

Edu Mail inboxes are provided by EduMails. The API is public and keyless, returns JSON, and is receive-only. The temp-mail.agency generator requests the .edu.pl domain category and merges those addresses with the Temp Mail domains above.

Base URL: https://api.edu-mails.com/api

GET /domains?tld=.edu.pl

List Edu Mail domains. The optional tld filter defaults to .edu.pl. Each entry includes an id, name and tld.

Response Example:

{
  "status": "success",
  "data": {
    "domains": [
      { "id": 1, "name": "cambrigeuni.edu.pl", "tld": ".edu.pl" }
    ]
  }
}
              

POST /emails/generate

Generate an Edu Mail address. Send a JSON body with action set to "custom" (with alias and domain_id) or "random". The response returns the inbox UUID and address; keep the UUID to read the inbox.

Request Example:

{
  "action": "custom",
  "alias": "demoqa2026",
  "domain_id": 1
}
              

Response Example:

{
  "status": "success",
  "data": {
    "email": {
      "uuid": "YOUR_INBOX_UUID",
      "address": "demoqa2026@cambrigeuni.edu.pl",
      "has_password": false
    },
    "reused": false
  }
}
              

GET /emails/{uuid}

Read the inbox for a UUID returned by /emails/generate. Messages are newest first and include from, subject, body and created_at. Password-protected inboxes require the X-Inbox-Password header.

The temp-mail.agency inbox polls this endpoint every five seconds while an Edu Mail address is open. There is no public endpoint for sending, deleting an inbox or deleting a message.