mail.tm Authentication: API Access & Security (2026)

Authentication overview

mail.tm, a service providing temporary email addresses, utilizes an authentication system to secure API access for developers. This system ensures that interactions with the mail.tm API, such as creating new temporary email addresses, fetching received emails, or deleting messages, are performed by authorized clients. The primary method for authentication involves obtaining and using an access token, which is a common practice in modern web APIs to manage session state and user identity without sending credentials with every request OAuth 2.0 Bearer Token usage.

The authentication flow typically involves an initial request to a login endpoint with user credentials (email and password). Upon successful verification, the API issues an access token. This token then needs to be included in the headers of subsequent requests to protected API endpoints. The token acts as proof of authentication, allowing the mail.tm API to verify the identity of the requesting application without requiring repeated submission of the user's secret credentials.

Supported authentication methods

mail.tm primarily supports one main authentication method for its API, which is token-based authentication. This method is widely adopted due to its balance of security and usability for API interactions.

Token-Based Authentication (JWT)

• Mechanism: After a successful login with a username (email) and password, the mail.tm API issues a JSON Web Token (JWT). This token is then sent in the Authorization header of subsequent API requests, typically as a Bearer token (e.g., Authorization: Bearer [your_token]).
• Benefits: JWTs are self-contained and digitally signed, allowing the API to verify their authenticity and integrity without needing to query a database for every request. This method enhances scalability and reduces server load JWT introduction.
• Lifecycle: Tokens have a limited lifespan. Developers must be prepared to refresh tokens or re-authenticate when a token expires. The mail.tm documentation provides specifics on token expiration and renewal processes mail.tm API documentation.

Getting your credentials

To access the mail.tm API, you need to first register an account on their platform. This registration process provides the necessary username (email address) and password that you will use to obtain an access token.

1. Account Registration: Navigate to the mail.tm website or use the API to create a new user account. This typically involves providing a unique email address and setting a strong password.
2. Login Endpoint: Once registered, you will use these credentials to make a request to the mail.tm login endpoint. The API documentation specifies the exact endpoint and the expected request body format, which usually involves sending the email and password in a JSON payload.
3. Token Retrieval: A successful login request will return a response containing your access token. This token is a string that you will need to store securely and include in the headers of all subsequent authenticated API calls.
4. Token Storage: For client-side applications or scripts, store the token in a secure, non-persistent manner, such as in memory. For server-side applications, secure storage mechanisms like environment variables or a secrets management service are recommended.

It is crucial to treat your email and password, as well as the resulting access token, as sensitive information to prevent unauthorized access to your temporary email accounts.

Authenticated request example

After successfully obtaining an access token, you can use it to make authenticated requests to the mail.tm API. The token should be included in the Authorization header of your HTTP requests, prefixed with Bearer.

Here's an example using cURL to log in and then fetch a list of messages for an authenticated user:

# Step 1: Login to get an access token
curl -X POST \
  https://api.mail.tm/token \
  -H 'Content-Type: application/json' \
  -d '{ "address": "[email protected]", "password": "your_secure_password" }'

# Expected response (example):
# {
#   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "id": "user_id"
# }

# Assume TOKEN is the token received from the login response
# Step 2: Use the token to fetch messages
curl -X GET \
  https://api.mail.tm/messages \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

In this example:

• The first curl command sends your credentials to the /token endpoint to obtain an access token.
• The second curl command then uses this YOUR_ACCESS_TOKEN in the Authorization: Bearer header to request messages from the /messages endpoint.

Replace [email protected] and your_secure_password with your actual mail.tm account credentials, and YOUR_ACCESS_TOKEN with the token received from the login response. For specific endpoint details and other API functionalities, refer to the official mail.tm API documentation.

Security best practices

Implementing strong security practices is essential when integrating with any API, especially one that handles email data. For mail.tm authentication, consider the following:

• Secure Credential Storage: Never hardcode API credentials (email, password, or access tokens) directly into your application's source code. Use environment variables, secure configuration files, or a dedicated secrets management service for server-side applications. For client-side applications, avoid persistent storage of tokens and consider short-lived tokens.
• HTTPS/TLS Usage: Always ensure all communication with the mail.tm API occurs over HTTPS (TLS). This encrypts data in transit, protecting credentials and tokens from eavesdropping and man-in-the-middle attacks. mail.tm's API inherently uses HTTPS, but it's important to verify your client enforces this.
• Token Expiration and Renewal: Be aware of the access token's expiration time. Implement logic to refresh tokens before they expire or gracefully handle token expiration by initiating a re-authentication flow. This minimizes the window of opportunity for an attacker to use a compromised token.
• Least Privilege Principle: If mail.tm were to introduce role-based access control (currently not explicitly detailed in its free API), ensure your applications only authenticate with credentials that have the minimum necessary permissions to perform their intended tasks.
• Input Validation and Sanitization: While primarily an application-level concern, ensure that any user-supplied data sent to the mail.tm API (e.g., when creating custom email addresses or interacting with messages) is properly validated and sanitized to prevent injection attacks.
• Error Handling: Implement robust error handling for authentication failures. Avoid providing overly descriptive error messages that could reveal sensitive information about your authentication mechanism. Generic messages like "Invalid credentials" are often preferred.
• Rate Limiting: Implement client-side rate limiting on your login attempts to prevent brute-force attacks against your mail.tm account.
• Regular Audits: Periodically review your authentication implementation and the security posture of your application. Stay informed about any security updates or recommendations from mail.tm.