# Table of Contents - [Authentication - Mail.tm](#authentication-mail-tm) - [Temp Mail API - Mail.tm](#temp-mail-api-mail-tm) - [Error Handling - Mail.tm](#error-handling-mail-tm) - [Domains - Mail.tm](#domains-mail-tm) - [Messages - Mail.tm](#messages-mail-tm) - [Accounts - Mail.tm](#accounts-mail-tm) - [Real-time Events - Mail.tm](#real-time-events-mail-tm) - [Integrations - Mail.tm](#integrations-mail-tm) - [About - Mail.tm](#about-mail-tm) --- # Authentication - Mail.tm Getting Started Authentication ============== Copy page Get a bearer token to authenticate with the Mail.tm API. No API key required. To make any request (except [account creation](https://docs.mail.tm/api/accounts#post-accounts) and [/domains](https://docs.mail.tm/api/domains) ) you need a bearer token. No API key is needed — just create an account and request a token. > _How to get it?_ You need to make a _**POST**_ request to the _**/token**_ path. [Request](https://docs.mail.tm/getting-started/authentication#request) ----------------------------------------------------------------------- **Body** | Name | Type | Description | | --- | --- | --- | | address | string | Account's address. Example: [user@example.com](mailto:user@example.com) | | password | string | Account's password. | **Params** _None_ [Response](https://docs.mail.tm/getting-started/authentication#response) ------------------------------------------------------------------------- `{ "id": "string", "token":"string" }` Use this token as `"Authorization":"Bearer TOKEN"` In every request! Remember: You should first create the account and then get the token!  [Error Handling\ \ HTTP status codes and error responses from the Mail.tm API.](https://docs.mail.tm/getting-started/error-handling) --- # Temp Mail API - Mail.tm Temp Mail API ============= Create temporary email accounts and receive emails via REST API. No API key required. [Getting Started](https://docs.mail.tm/getting-started/authentication) [OpenAPI Spec](https://api.mail.tm/) `# 1. Get available domains curl https://api.mail.tm/domains # 2. Create account curl -X POST https://api.mail.tm/accounts \ -H "Content-Type: application/json" \ -d '{"address":"user@domain.com","password":"secret"}' # 3. Get token curl -X POST https://api.mail.tm/token \ -H "Content-Type: application/json" \ -d '{"address":"user@domain.com","password":"secret"}' # 4. Fetch messages curl https://api.mail.tm/messages \ -H "Authorization: Bearer TOKEN"` Workflow How it works ------------ Fetch domains Get available domain names from the API. Create account Create a temporary email account with one request. Use the address Sign up on sites that require email confirmation. Message arrives We receive it and store it for you. Fetch messages Fetch messages via the API or listen in real-time with SSE. Step 0 of 5 Pricing Access to the API ----------------- Completely free. No API key, no signup, no paid tiers. * No API key required Just call the endpoints. No signup, no tokens to start. * 8 QPS rate limit The general quota limit is 8 queries per second (QPS) per IP address. Policy Terms of Use ------------ * No illegal activity Usage of our API for illegal activity is strictly prohibited. * No reselling Don't build a paid product that just wraps our API. * No proxy services Don't mirror or proxy our API under a different domain. * Attribution required If you use our API, link back to mail.tm somewhere visible. General Information ------------------- The API follows the OpenAPI v3 spec. Download it or explore interactively. [Download OpenAPI Spec](https://api.mail.tm/docs.jsonld) [Interactive API Docs](https://api.mail.tm/) --- # Error Handling - Mail.tm Getting Started Error Handling ============== Copy page HTTP status codes and error responses from the Mail.tm API. [Successful](https://docs.mail.tm/getting-started/error-handling#successful) ----------------------------------------------------------------------------- Generally, the request is successful when the response code is 200, 201 or 204 (You could also check if the code is between 200 and 204) [Unsuccessful](https://docs.mail.tm/getting-started/error-handling#unsuccessful) --------------------------------------------------------------------------------- Usually, when the request has an error the code is between 400 and 430. **Bad request 400:** Something in your payload is missing! Or, the payload isn't there at all. **Unauthorized 401:** Your token isn't correct (Or the headers hasn't a token at all!). Remember, every request (Except [POST /accounts](https://docs.mail.tm/api/accounts#post-accounts) and [POST /token](https://docs.mail.tm/getting-started/authentication) ) should be authenticated with a Bearer token! **Not found 404:** You're trying to access an account that doesn't exist? Or maybe reading a non-existing message? Go check that! **Method not allowed 405:** Maybe you're trying to _**GET**_ a _**/token**_ or _**POST**_ a _**/messages**_. Check the path you're trying to make a request to and check if the method is the correct one. **I'm a teapot 418:** Who knows? Maybe the server becomes a teapot! **Unprocessable entity 422:** Some went wrong on your payload. Like, the username of the address while creating the account isn't long enough, or, the account's domain isn't correct. Things like that. **Too many requests 429:** You exceeded the limit of 8 requests per second! Try delaying the request by one second! [Authentication\ \ Get a bearer token to authenticate with the Mail.tm API. No API key required.](https://docs.mail.tm/getting-started/authentication) [Domains\ \ List available email domains for creating temporary accounts.](https://docs.mail.tm/api/domains) --- # Domains - Mail.tm API Reference Domains ======= Copy page List available email domains for creating temporary accounts. [GET `/domains`](https://docs.mail.tm/api/domains#get-domains) --------------------------------------------------------------- Get the list of available domains. You need a domain before you can [create an account](https://docs.mail.tm/api/accounts#post-accounts) . Returns a paginated list of domains. **Body** _None_ **Params** | Name | Type | Description | | --- | --- | --- | | page | int | The collection page number | **Response** `{ "hydra:member": [ { "@id": "string", "@type": "string", "@context": "string", "id": "string", "domain": "string", "isActive": true, "isPrivate": true, "createdAt": "2022-04-01T00:00:00.000Z", "updatedAt": "2022-04-01T00:00:00.000Z" } ], "hydra:totalItems": 0, "hydra:view": { "@id": "string", "@type": "string", "hydra:first": "string", "hydra:last": "string", "hydra:previous": "string", "hydra:next": "string" }, "hydra:search": { "@type": "string", "hydra:template": "string", "hydra:variableRepresentation": "string", "hydra:mapping": [ { "@type": "string", "variable": "string", "property": "string", "required": true } ] } }` When you create an email, you have to know first which domain to use. You'll need to retrieve the domain, and then, do like so: `"user@"+domains[0]['domain']` There are up to 30 domains per page, to check the total number, retrieve it from `"hydra:totalItems"` [GET `/domains/{id}`](https://docs.mail.tm/api/domains#get-domainsid) ---------------------------------------------------------------------- Retrieve a domain by its id (Useful for deleted/private domains) **Body** _None_ **Params** | Name | Type | Description | | --- | --- | --- | | id | string | The domain you want to get with id | **Response** `{ "@id": "string", "@type": "string", "@context": "string", "id": "string", "domain": "string", "isActive": true, "isPrivate": true, "createdAt": "2022-04-01T00:00:00.000Z", "updatedAt": "2022-04-01T00:00:00.000Z" }` [Error Handling\ \ HTTP status codes and error responses from the Mail.tm API.](https://docs.mail.tm/getting-started/error-handling) [Accounts\ \ Create and manage temporary email accounts.](https://docs.mail.tm/api/accounts) --- # Messages - Mail.tm API Reference Messages ======== Copy page Fetch, read, and manage emails received by your temporary account. [GET `/messages`](https://docs.mail.tm/api/messages#get-messages) ------------------------------------------------------------------ Get all messages for your account. Returns a paginated list. **Body** _None_ **Params** | Name | Type | Description | | --- | --- | --- | | page | int | The collection page number | **Response** `{ "hydra:member": [ { "@id": "string", "@type": "string", "@context": "string", "id": "string", "accountId": "string", "msgid": "string", "from": { "name": "string", "address": "string" }, "to": [ { "name": "string", "address": "string" } ], "subject": "string", "intro": "string", "seen": true, "isDeleted": true, "hasAttachments": true, "size": 0, "downloadUrl": "string", "createdAt": "2022-04-01T00:00:00.000Z", "updatedAt": "2022-04-01T00:00:00.000Z" } ], "hydra:totalItems": 0, "hydra:view": { "@id": "string", "@type": "string", "hydra:first": "string", "hydra:last": "string", "hydra:previous": "string", "hydra:next": "string" }, "hydra:search": { "@type": "string", "hydra:template": "string", "hydra:variableRepresentation": "string", "hydra:mapping": [ { "@type": "string", "variable": "string", "property": "string", "required": true } ] } }` There are up to 30 messages per page, to check the total number, retrieve it from `"hydra:totalItems"` [GET `/messages/{id}`](https://docs.mail.tm/api/messages#get-messagesid) ------------------------------------------------------------------------- Retrieves a Message resource with a specific id (It has way more information than a message retrieved with [GET /messages](https://docs.mail.tm/api/messages#get-messages) but it hasn't the "intro" member) **Body** _None_ **Params** | Name | Type | Description | | --- | --- | --- | | id | string | The message you want to get by id | **Response** `{ "@context": "string", "@id": "string", "@type": "string", "id": "string", "accountId": "string", "msgid": "string", "from": { "name": "string", "address": "string" }, "to": [ { "name": "string", "address": "string" } ], "cc": [ "string" ], "bcc": [ "string" ], "subject": "string", "seen": true, "flagged": true, "isDeleted": true, "verifications": [ "string" ], "retention": true, "retentionDate": "2022-04-01T00:00:00.000Z", "text": "string", "html": [ "string" ], "hasAttachments": true, "attachments": [ { "id": "string", "filename": "string", "contentType": "string", "disposition": "string", "transferEncoding": "string", "related": true, "size": 0, "downloadUrl": "string" } ], "size": 0, "downloadUrl": "string", "createdAt": "2022-04-01T00:00:00.000Z", "updatedAt": "2022-04-01T00:00:00.000Z" }` [DELETE `/messages/{id}`](https://docs.mail.tm/api/messages#delete-messagesid) ------------------------------------------------------------------------------- Deletes the `Message` resource. **Body** _None_ **Params** | Name | Type | Description | | --- | --- | --- | | id | string | The message you want to delete's id | **Response** _None_ _**(Returns status code 204 if successful.)**_ [PATCH `/messages/{id}`](https://docs.mail.tm/api/messages#patch-messagesid) ----------------------------------------------------------------------------- Marks a Message resource as read! **Body** _None_ **Params** | Name | Type | Description | | --- | --- | --- | | id | string | The message you want to read's id | **Response** `{ "seen": true }` To check if the message has been read, you could also check if the status code is 200! [GET `/sources/{id}`](https://docs.mail.tm/api/messages#get-sourcesid) ----------------------------------------------------------------------- Gets a Message's Source resource (If you don't know what this is, you either don't really want to use it or you should read [this](https://en.wikipedia.org/wiki/Email#Plain_text_and_HTML) !) **Body** _None_ **Params** | Name | Type | Description | | --- | --- | --- | | id | string | The source you want to get by id | **Response** `{ "@context": "string", "@id": "string", "@type": "string", "id": "string", "downloadUrl": "string", "data": "string" }` You don't really need the `downloadUrl` if you already have the "data" String. It will simply download that data. [Attachments](https://docs.mail.tm/api/messages#attachments) ------------------------------------------------------------- Message's attachments need to be handled in a certain way. When you download them, be sure to download them in the right encoding (For example, a .exe file will need to be downloaded as an array of integers, but a json will need to be downloaded as String! Also, remember: APIs are your friends. contentType member can help you know how to decode the file) [Accounts\ \ Create and manage temporary email accounts.](https://docs.mail.tm/api/accounts) [Real-time Events\ \ Listen for new emails in real-time using SSE (Server-Sent Events) via Mercure.](https://docs.mail.tm/api/webhooks) --- # Accounts - Mail.tm API Reference Accounts ======== Copy page Create and manage temporary email accounts. [POST `/accounts`](https://docs.mail.tm/api/accounts#post-accounts) -------------------------------------------------------------------- Create a new temporary email account. **Body** | Name | Type | Description | | --- | --- | --- | | address | string | Account's address. Example: [user@example.com](mailto:user@example.com) | | password | string | Account's password. | **Params** _None_ **Response** `{ "@context": "string", "@id": "string", "@type": "string", "id": "string", "address": "user@example.com", "quota": 0, "used": 0, "isDisabled": true, "isDeleted": true, "createdAt": "2022-04-01T00:00:00.000Z", "updatedAt": "2022-04-01T00:00:00.000Z" }` At this point, you could now [get the token](https://docs.mail.tm/getting-started/authentication) and do all the cool stuff you want to do. [GET `/accounts/{id}`](https://docs.mail.tm/api/accounts#get-accountsid) ------------------------------------------------------------------------- Get an Account resource by its id (Obviously, the Bearer token needs to be the one of the account you are trying to retrieve) **Body** _None_ **Params** | Name | Type | Description | | --- | --- | --- | | id | string | The message you want to gets id | **Response** `{ "@context": "string", "@id": "string", "@type": "string", "id": "string", "address": "user@example.com", "quota": 0, "used": 0, "isDisabled": true, "isDeleted": true, "createdAt": "2022-04-01T00:00:00.000Z", "updatedAt": "2022-04-01T00:00:00.000Z" }` [DELETE `/accounts/{id}`](https://docs.mail.tm/api/accounts#delete-accountsid) ------------------------------------------------------------------------------- Deletes the Account resource. Be careful! We can't restore your account, if you use this method, bye bye dear account **Body** _None_ **Params** | Name | Type | Description | | --- | --- | --- | | id | string | The account you want to delete by id | **Response** _None_ _**(Returns status code 204 if successful.)**_ [GET `/me`](https://docs.mail.tm/api/accounts#get-me) ------------------------------------------------------ Returns the Account resource that matches the Bearer token that sent the request. **Body** _None_ **Params** _None_ **Response** `{ "@context": "string", "@id": "string", "@type": "string", "id": "string", "address": "user@example.com", "quota": 0, "used": 0, "isDisabled": true, "isDeleted": true, "createdAt": "2022-04-01T00:00:00.000Z", "updatedAt": "2022-04-01T00:00:00.000Z" }` [Domains\ \ List available email domains for creating temporary accounts.](https://docs.mail.tm/api/domains) [Messages\ \ Fetch, read, and manage emails received by your temporary account.](https://docs.mail.tm/api/messages) --- # Real-time Events - Mail.tm API Reference Real-time Events ================ Copy page Listen for new emails in real-time using SSE (Server-Sent Events) via Mercure. Instead of webhooks, we use [Mercure](https://mercure.rocks/) to push real-time SSE events. This lets you receive emails instantly without polling. [Listen to messages](https://docs.mail.tm/api/webhooks#listen-to-messages) --------------------------------------------------------------------------- To listen for incoming emails, connect to the Mercure hub. **Base url:** `https://mercure.mail.tm/.well-known/mercure` **Topic:** `/accounts/{id}` Remember! You must use the `Bearer TOKEN` authorization in the headers! For each listened message, there will be an `Account` event. That Account is the Account resource that received the message, with updated `"used"` property. [Messages\ \ Fetch, read, and manage emails received by your temporary account.](https://docs.mail.tm/api/messages) [Integrations\ \ Community-built libraries and SDKs for Python, JavaScript, Go, Rust, PHP, Java, Swift, Dart, and .NET.](https://docs.mail.tm/integrations) --- # Integrations - Mail.tm Integrations ============ Copy page Community-built libraries and SDKs for Python, JavaScript, Go, Rust, PHP, Java, Swift, Dart, and .NET. | Language | Link | | --- | --- | | .NET | [SmorcIRL/mail.tm](https://github.com/SmorcIRL/mail.tm) | | Dart | [mailtm\_client](https://pub.dev/packages/mailtm_client) | | Golang | [felixstrobel/mailtm](https://github.com/felixstrobel/mailtm)
, [msuny-c/mailtm](https://github.com/msuny-c/mailtm) | | Java | [shivam1608/JMailTM](https://github.com/shivam1608/JMailTM) | | JavaScript | [cemalgnlts/Mailjs](https://github.com/cemalgnlts/Mailjs) | | PHP | [heithemmoumni/mail.tm](https://github.com/heithemmoumni/mail.tm) | | Python | [CarloDePieri/pymailtm](https://github.com/CarloDePieri/pymailtm)
, [prtolem/MailTM](https://github.com/prtolem/MailTM)
, [RPwnage/MailTMClient](https://github.com/RPwnage/MailTMClient) | | Rust | [AwesomeIbex/mail-tm-rs](https://github.com/AwesomeIbex/mail-tm-rs) | | Swift | [devwaseem/MailTMSwift](https://github.com/devwaseem/MailTMSwift) | Built something? Let us know and we'll add it here. [Real-time Events\ \ Listen for new emails in real-time using SSE (Server-Sent Events) via Mercure.](https://docs.mail.tm/api/webhooks) [About\ \ Questions, suggestions, and tech stack behind Mail.tm.](https://docs.mail.tm/about) --- # About - Mail.tm About ===== Copy page Questions, suggestions, and tech stack behind Mail.tm. [Questions and suggestions](https://docs.mail.tm/about#questions-and-suggestions) ---------------------------------------------------------------------------------- Got questions or ideas? Email us at [support@mail.tm](mailto:support@mail.tm) . [Tech stack](https://docs.mail.tm/about#tech-stack) ---------------------------------------------------- Our stack includes [API-Platform](https://api-platform.com/) , [Mercure](https://mercure.rocks/) , [Nuxt.js](https://nuxtjs.org/) , [Haraka](https://haraka.github.io/) , [Caddy](https://caddyserver.com/) , [MongoDB](https://www.mongodb.com/) , [Node.js](https://nodejs.org/) , [CentOS](https://centos.org/) [Integrations\ \ Community-built libraries and SDKs for Python, JavaScript, Go, Rust, PHP, Java, Swift, Dart, and .NET.](https://docs.mail.tm/integrations) ---