Free Temp Mail API Documentation

GET /domains

Return public domains matching a TLD filter. The optional tld query parameter defaults to .edu.pl; this endpoint does not automatically return every domain category. A filter with no matches returns an empty domain list.

This read-only example lists domain metadata without creating an inbox:

curl --get 'https://api.edu-mails.com/api/domains' \
  --data-urlencode 'tld=.edu.pl' \
  --header 'Accept: application/json'

A successful response has status: "success" and an array at data.domains. Each entry includes an id, name and tld. Use a current returned domain ID for custom generation; availability can change. Domain spelling or suffix does not establish university affiliation.

POST /emails/generate

Generate an address using a JSON body. This request creates server data, except when a custom address already exists and is reused.

• action: use "random" (the default) or "custom".
• alias: username for custom mode. It is trimmed, lowercased, stripped to letters a–z and digits 0–9, and truncated to 30 characters. If fewer than 5 characters remain, a random alias is generated.
• domain_id: in custom mode, select an available public domain returned by /domains.
• tld: in custom mode, the fallback filter if no usable domain_id is supplied; defaults to .edu.pl. If the chosen ID is unavailable, another public domain in the fallback category may be selected.

Random mode chooses across all public domains. It does not restrict its choice to the supplied TLD or domain ID. Always read the final data.email.address from the response.

Random request body

{
  "action": "random"
}

Custom request body

The ID below is illustrative. Replace it with a current domain ID from the listing before making a request.

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

Illustrative response

Examples use the reserved domain example.com and a placeholder identifier; they do not describe a live inbox. Actual objects can contain additional fields.

{
  "status": "success",
  "data": {
    "email": {
      "uuid": "YOUR_INBOX_UUID",
      "address": "demoqa2026@example.com",
      "has_password": false
    },
    "reused": false
  }
}

Store the returned UUID to read this inbox. The custom response includes data.reused: true means the same address already existed and its existing UUID was returned. The random response does not include this flag. Generation does not return a password or grant access to password-protected messages.

GET /emails/{uuid}

Read an authorized inbox by replacing {uuid} with its returned UUID. A successful response includes data.email and data.messages, ordered newest first. An empty inbox returns an empty messages array. This route has no documented pagination parameters.

For a protected inbox, send X-Inbox-Password: YOUR_INBOX_PASSWORD as a header. Omit it for an unprotected inbox. Do not place the password in a query string.

{
  "status": "success",
  "data": {
    "email": {
      "uuid": "YOUR_INBOX_UUID",
      "address": "demoqa2026@example.com",
      "has_password": true
    },
    "messages": []
  }
}

Message records use fields including uuid, from, recipient, subject, body and created_at. Handle empty or missing content. Treat email content as untrusted; do not insert message HTML into your application without appropriate sanitization or isolation.

A missing or incorrect password produces HTTP 401 with data.password_required: true. An unknown UUID produces HTTP 404.

PUT /emails/{uuid}/password

Set or change the password on an inbox you are authorized to manage. Send a required password string of 6–72 characters in the JSON body. The new password is stored as a hash and is not returned by the API.

{
  "password": "YOUR_NEW_UNIQUE_PASSWORD"
}

If the inbox already has a password, also provide current_password in the body or the current password in X-Inbox-Password. A supplied current_password takes precedence over the header. The current-password body field accepts at most 72 characters.

{
  "password": "YOUR_NEW_UNIQUE_PASSWORD",
  "current_password": "YOUR_CURRENT_PASSWORD"
}

Success returns HTTP 200, message: "Inbox password saved." and the updated object at data.email. A wrong current password returns 401, an unknown inbox returns 404, and an invalid body returns 422 when JSON is requested. There is no public password removal or recovery endpoint.