Mail.tm API

https://docs.mail.tm/
Admin
Mail.tm API allows for the creation of temporary email accounts, automating email confirmation...
Tokens:7,348
Snippets:61
Trust Score:9.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Construct Email Address with Domain

Source: https://docs.mail.tm/api/domains

Example of how to construct a full email address by appending a retrieved domain to a username.

```string
"user@"+domains[0]['domain']

```

--------------------------------

### Get Token

Source: https://docs.mail.tm/

Obtains an authentication token for accessing protected resources, using account credentials.

```APIDOC
## POST /token

### Description
Generates an authentication token required for accessing protected API endpoints, such as fetching messages. Requires the email address and password of an existing account.

### Method
POST

### Endpoint
https://api.mail.tm/token

### Parameters
#### Request Body
- address (string) - Required - The email address of the account.
- password (string) - Required - The password for the account.

### Request Example
```json
{
  "address": "user@domain.com",
  "password": "secret"
}
```

### Response
#### Success Response (200)
- token (string) - The authentication token.

#### Response Example
```json
{
  "token": "YOUR_AUTH_TOKEN"
}
```
```

--------------------------------

### Get Available Domains

Source: https://docs.mail.tm/

Retrieves a list of available domains that can be used for creating temporary email accounts.

```APIDOC
## GET /domains

### Description
Fetches a list of available domains that can be used to create temporary email accounts.

### Method
GET

### Endpoint
https://api.mail.tm/domains

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- domains (array) - A list of available domain objects.
- id (string) - The domain ID.
- name (string) - The domain name.

#### Response Example
```json
{
  "id": "domain_id",
  "name": "domain.com"
}
```
```

--------------------------------

### Get All Messages

Source: https://docs.mail.tm/api/messages

Retrieves a paginated list of all messages for an account. Up to 30 messages are returned per page.

```json
{
  "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
      }
    ]
  }
}
```

--------------------------------

### Get Specific Message

Source: https://docs.mail.tm/api/messages

Retrieves a detailed Message resource by its ID. This includes more information than the list view but lacks the 'intro' field.

```json
{
  "@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"
}
```

--------------------------------

### Get All Messages

Source: https://docs.mail.tm/api/messages

Retrieves a paginated list of all messages for the account. Up to 30 messages are returned per page.

```APIDOC
## GET /messages

### Description
Get all messages for your account. Returns a paginated list.

### Method
GET

### Endpoint
/messages

### Parameters
#### Query Parameters
- **page** (int) - Optional - The collection page number

### Response
#### Success Response (200)
- **hydra:member** (array) - A list of message objects.
- **hydra:totalItems** (int) - The total number of messages available.
- **hydra:view** (object) - Pagination information.
- **hydra:search** (object) - Search template information.

### Response Example
```json
{
  "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
      }
    ]
  }
}
```
```

--------------------------------

### Get Message Source

Source: https://docs.mail.tm/api/messages

Retrieves the raw source data of a message. The 'data' field contains the source content, and 'downloadUrl' is also provided.

```json
{
  "@context": "string",
  "@id": "string",
  "@type": "string",
  "id": "string",
  "downloadUrl": "string",
  "data": "string"
}
```

--------------------------------

### Get Current Account

Source: https://docs.mail.tm/api/accounts

Retrieves the Account resource associated with the Bearer token provided in the request.

```APIDOC
## GET /me

### Description
Returns the Account resource that matches the Bearer token that sent the request.

### Method
GET

### Endpoint
/me

### Response
#### Success Response (200)
- **@context** (string)
- **@id** (string)
- **@type** (string)
- **id** (string)
- **address** (string)
- **quota** (integer)
- **used** (integer)
- **isDisabled** (boolean)
- **isDeleted** (boolean)
- **createdAt** (string)
- **updatedAt** (string)

### Response Example
```json
{
  "@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"
}
```
```

--------------------------------

### Get Message by ID

Source: https://docs.mail.tm/api/messages

Retrieves a specific Message resource by its ID. This provides more detailed information than the list view, but excludes the 'intro' field.

```APIDOC
## GET /messages/{id}

### Description
Retrieves a Message resource with a specific id (It has way more information than a message retrieved with GET /messages but it hasn't the "intro" member)

### Method
GET

### Endpoint
/messages/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The message you want to get by id

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the message.
- **accountId** (string) - The ID of the account the message belongs to.
- **msgid** (string) - The unique message ID.
- **from** (object) - Sender's information (name and address).
- **to** (array) - Recipients of the message.
- **cc** (array) - CC recipients of the message.
- **bcc** (array) - BCC recipients of the message.
- **subject** (string) - The subject line of the email.
- **seen** (boolean) - Indicates if the message has been seen.
- **flagged** (boolean) - Indicates if the message is flagged.
- **isDeleted** (boolean) - Indicates if the message is marked as deleted.
- **verifications** (array) - Verification details for the message.
- **retention** (boolean) - Indicates if retention policies apply.
- **retentionDate** (string) - The date when retention policies expire.
- **text** (string) - The plain text content of the message.
- **html** (array) - An array of strings representing the HTML content of the message.
- **hasAttachments** (boolean) - Indicates if the message has attachments.
- **attachments** (array) - Details of the message attachments.
- **size** (integer) - The size of the message in bytes.
- **downloadUrl** (string) - A URL to download the message.
- **createdAt** (string) - The timestamp when the message was created.
- **updatedAt** (string) - The timestamp when the message was last updated.

### Response Example
```json
{
  "@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"
}
```
```

--------------------------------

### Get Account by ID

Source: https://docs.mail.tm/api/accounts

Retrieves a specific Account resource using its unique ID. Requires the Bearer token of the account to be retrieved.

```APIDOC
## GET /accounts/{id}

### Description
Get an Account resource by its id. The Bearer token must belong to the account being retrieved.

### Method
GET

### Endpoint
/accounts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the account to retrieve.

### Response
#### Success Response (200)
- **@context** (string)
- **@id** (string)
- **@type** (string)
- **id** (string)
- **address** (string)
- **quota** (integer)
- **used** (integer)
- **isDisabled** (boolean)
- **isDeleted** (boolean)
- **createdAt** (string)
- **updatedAt** (string)

### Response Example
```json
{
  "@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"
}
```
```

--------------------------------

### Get Message Source

Source: https://docs.mail.tm/api/messages

Retrieves the raw source of a Message resource by its ID. This includes the 'data' field which contains the source content.

```APIDOC
## GET /sources/{id}

### Description
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!)

### Method
GET

### Endpoint
/sources/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The source you want to get by id

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the source.
- **downloadUrl** (string) - A URL to download the source content.
- **data** (string) - The raw source content of the message.

### Response Example
```json
{
  "@context": "string",
  "@id": "string",
  "@type": "string",
  "id": "string",
  "downloadUrl": "string",
  "data": "string"
}
```
```

--------------------------------

### Get Bearer Token

Source: https://docs.mail.tm/getting-started/authentication

To authenticate with the Mail.tm API, you need to obtain a bearer token. This is done by sending a POST request to the /token endpoint with your account credentials in the request body.

```APIDOC
## POST /token

### Description
Obtain a bearer token for API authentication.

### Method
POST

### Endpoint
/token

### Request Body
- **address** (string) - Required - Account's address. Example: user@example.com
- **password** (string) - Required - Account's password.

### Response
#### Success Response (200)
- **id** (string) - The ID of the token.
- **token** (string) - The bearer token.

### Request Example
```json
{
  "address": "user@example.com",
  "password": "your_password"
}
```

### Response Example
```json
{
  "id": "some_id",
  "token": "your_bearer_token"
}
```

### Usage
Use the obtained token in the Authorization header as 'Bearer TOKEN'.
```

--------------------------------

### Fetch Available Domains

Source: https://docs.mail.tm/

Use this command to retrieve a list of available domain names for creating email accounts.

```bash
curl https://api.mail.tm/domains
```

--------------------------------

### Create Email Account

Source: https://docs.mail.tm/

Create a new temporary email account by providing a desired address and password in JSON format.

```bash
curl -X POST https://api.mail.tm/accounts \
-H "Content-Type: application/json" \
-d '{"address":"user@domain.com","password":"secret"}'
```

--------------------------------

### Obtain Authentication Token

Source: https://docs.mail.tm/

Obtain an authentication token after creating an account by sending your address and password.

```bash
curl -X POST https://api.mail.tm/token \
-H "Content-Type: application/json" \
-d '{"address":"user@domain.com","password":"secret"}'
```

--------------------------------

### Create Account

Source: https://docs.mail.tm/

Creates a new temporary email account with a specified address and password.

```APIDOC
## POST /accounts

### Description
Creates a new temporary email account. You need to provide the desired email address and a password.

### Method
POST

### Endpoint
https://api.mail.tm/accounts

### Parameters
#### Request Body
- address (string) - Required - The desired email address (e.g., "user@domain.com").
- password (string) - Required - The password for the account.

### Request Example
```json
{
  "address": "user@domain.com",
  "password": "secret"
}
```

### Response
#### Success Response (201)
- id (string) - The unique identifier for the created account.
- address (string) - The email address of the created account.

#### Response Example
```json
{
  "id": "account_id",
  "address": "user@domain.com"
}
```
```

--------------------------------

### Account Response Structure

Source: https://docs.mail.tm/api/accounts

This is the standard JSON structure returned when creating or retrieving an account.

```json
{
  "@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"
}
```

--------------------------------

### Fetch Messages

Source: https://docs.mail.tm/

Retrieve messages from your temporary email account using the obtained authentication token in the Authorization header.

```bash
curl https://api.mail.tm/messages \
-H "Authorization: Bearer TOKEN"
```

--------------------------------

### List Available Email Domains

Source: https://docs.mail.tm/api/domains

Retrieve a paginated list of available email domains. This is necessary before creating a new temporary email account.

```json
{
  "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
      }
    ]
  }
}

```

--------------------------------

### List Available Domains

Source: https://docs.mail.tm/api/domains

Retrieves a paginated list of available email domains. You need a domain before you can create an account. There are up to 30 domains per page.

```APIDOC
## GET /domains

### Description
Get the list of available domains. You need a domain before you can create an account. Returns a paginated list of domains.

### Method
GET

### Endpoint
/domains

### Parameters
#### Query Parameters
- **page** (int) - Optional - The collection page number

### Response
#### Success Response (200)
- **hydra:member** (array) - A list of domain objects.
- **hydra:totalItems** (int) - The total number of available domains.

### Response Example
```json
{
  "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
      }
    ]
  }
}
```
```

--------------------------------

### Fetch Messages

Source: https://docs.mail.tm/

Retrieves a list of messages for the authenticated account.

```APIDOC
## GET /messages

### Description
Fetches a list of emails received by the authenticated account. Requires an Authorization header with a valid token.

### Method
GET

### Endpoint
https://api.mail.tm/messages

### Parameters
#### Header Parameters
- Authorization (string) - Required - Bearer token for authentication (e.g., "Bearer TOKEN").

### Request Example
None (uses headers)

### Response
#### Success Response (200)
- messages (array) - A list of message objects.
- id (string) - The message ID.
- from (object) - Information about the sender.
  - address (string) - Sender's email address.
  - name (string) - Sender's name.
- subject (string) - The subject of the email.
- receivedId (string) - The internal ID for the received message.
- at (integer) - Timestamp when the message was received.

#### Response Example
```json
{
  "messages": [
    {
      "id": "message_id",
      "from": {
        "address": "sender@example.com",
        "name": "Sender Name"
      },
      "subject": "Test Email",
      "receivedId": "received_id",
      "at": 1678886400
    }
  ]
}
```
```

--------------------------------

### Listen to Messages

Source: https://docs.mail.tm/api/webhooks

Connect to the Mercure hub to listen for incoming emails. This endpoint pushes 'Account' events for each received message, including updates to the account's 'used' property.

```APIDOC
## GET /.well-known/mercure

### Description
Listen for incoming emails in real-time via Server-Sent Events (SSE).

### Method
GET

### Endpoint
https://mercure.mail.tm/.well-known/mercure

### Parameters
#### Query Parameters
- **topic** (string) - Required - The topic to subscribe to, formatted as `/accounts/{id}` where `{id}` is the account ID.

#### Headers
- **Authorization** (string) - Required - Bearer TOKEN

### Response
#### Success Response (200)
- **event** (string) - The type of event, e.g., 'Account'.
- **data** (object) - The payload of the event, containing the updated Account resource with a 'used' property.
```

--------------------------------

### Mark Message as Read

Source: https://docs.mail.tm/api/messages

Marks a specific Message resource as read. A status code of 200 indicates success.

```json
{
  "seen": true
}
```

--------------------------------

### Mark Message as Read

Source: https://docs.mail.tm/api/messages

Marks a specific Message resource as read.

```APIDOC
## PATCH /messages/{id}

### Description
Marks a Message resource as read!

### Method
PATCH

### Endpoint
/messages/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The message you want to read's id

### Response
#### Success Response (200)
- **seen** (boolean) - Indicates if the message has been marked as read.

### Response Example
```json
{
  "seen": true
}
```
```

--------------------------------

### Retrieve Domain by ID

Source: https://docs.mail.tm/api/domains

Retrieves a specific domain by its unique identifier. This is useful for accessing details of deleted or private domains.

```APIDOC
## GET /domains/{id}

### Description
Retrieve a domain by its id (Useful for deleted/private domains)

### Method
GET

### Endpoint
/domains/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The domain you want to get with id

### Response
#### Success Response (200)
- **@id** (string) - The @id of the domain.
- **@type** (string) - The @type of the domain.
- **@context** (string) - The @context of the domain.
- **id** (string) - The unique identifier of the domain.
- **domain** (string) - The domain name.
- **isActive** (boolean) - Indicates if the domain is active.
- **isPrivate** (boolean) - Indicates if the domain is private.
- **createdAt** (string) - The date and time the domain was created.
- **updatedAt** (string) - The date and time the domain was last updated.

### Response Example
```json
{
  "@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"
}
```
```

--------------------------------

### Retrieve a Specific Domain by ID

Source: https://docs.mail.tm/api/domains

Fetch details for a specific email domain using its unique ID. This is useful for checking the status of deleted or private domains.

```json
{
  "@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"
}

```

--------------------------------

### Delete Account

Source: https://docs.mail.tm/api/accounts

Deletes the specified Account resource. This action is irreversible.

```APIDOC
## DELETE /accounts/{id}

### Description
Deletes the Account resource. This action is irreversible.

### Method
DELETE

### Endpoint
/accounts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the account to delete.

### Response
#### Success Response (204)
No content is returned upon successful deletion.
```

--------------------------------

### Include Bearer Token in Authorization Header

Source: https://docs.mail.tm/getting-started/authentication

This is the format for including your obtained bearer token in the Authorization header for API requests. Replace 'TOKEN' with your actual token.

```http
"Authorization":"Bearer TOKEN"
```

--------------------------------

### Mail.tm API Token Response Structure

Source: https://docs.mail.tm/getting-started/authentication

This JSON structure represents the successful response when requesting an authentication token from the Mail.tm API. It contains the user's ID and the generated bearer token.

```json
{
  "id": "string",
  "token":"string"
}
```

--------------------------------

### Delete Message

Source: https://docs.mail.tm/api/messages

Deletes a specific Message resource by its ID.

```APIDOC
## DELETE /messages/{id}

### Description
Deletes the `Message` resource.

### Method
DELETE

### Endpoint
/messages/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The message you want to delete's id

### Response
#### Success Response (204)
_No content. Returns status code 204 if successful._
```
Tokens:
Raw