Getting started overview

Integrating with mail.tm's API allows developers to automate the creation of temporary email addresses and programmatically interact with their inboxes. This functionality is often used in testing environments, for bypassing email verification in automated scripts, or to enhance user privacy by providing disposable email options. The mail.tm platform offers a fully featured API and web access without cost.

The core workflow involves authenticating with the API to obtain a token, then using that token to create temporary domains or users, and finally fetching received emails. The API provides endpoints for managing domains, users (representing temporary email addresses), and messages within those user accounts. Documentation for the mail.tm API includes examples in multiple programming languages, such as PHP, JavaScript, and Python, in addition to cURL for direct HTTP requests.

This guide outlines the essential steps to get started with the mail.tm API, from account creation and token acquisition to making a first successful request. While the API is designed to be straightforward, developers should be aware of standard API practices, such as proper authentication and error handling, which are common across many web service integrations.

Create an account and get keys

mail.tm operates without traditional API keys. Instead, access to the API is managed through an authentication token system. To begin, you must register a user account directly through the mail.tm web interface or via the API. Once an account is created, you can generate an access token by sending a POST request to the /token endpoint with your username and password.

Account Creation via Web

  1. Navigate to the mail.tm homepage.
  2. Locate and select the option to create a new temporary email address. While this directly creates an email, it's often the quickest way to get a user identifier for API access later, or you can register an account explicitly if available through the web interface.

Account Creation via API (Recommended for Automation)

To create a user account programmatically, send a POST request to the /users endpoint. This method is generally preferred for automated setups, as it directly integrates account creation into your workflow. The request body should contain the desired address (username and domain) and a password for the new account.

curl -X POST "https://api.mail.tm/users" \
     -H "Content-Type: application/json" \
     -d '{
           "address": "your_username@your_domain.com",
           "password": "your_password"
         }'

Note that for the address field, you might need to first fetch available domains using the /domains endpoint to ensure you're using a valid and active domain.

Obtaining an API Token

After creating a user account (either via the web or API), you need to obtain an authentication token. This token is crucial for all subsequent authenticated API requests. Send a POST request to the /token endpoint with your account's address and password:

curl -X POST "https://api.mail.tm/token" \
     -H "Content-Type: application/json" \
     -d '{
           "address": "your_username@your_domain.com",
           "password": "your_password"
         }'

The response will include an X-AUTH-TOKEN which you will use in the Authorization header for all subsequent API calls in the format Bearer <token>. This token typically has an expiration, so your application should be prepared to refresh it as needed.

Your first request

Once you have an authentication token, you can make your first authenticated request to fetch messages for the newly created temporary email address. This demonstrates successful authentication and interaction with the API.

Step-by-step first request: Fetching Messages

  1. Obtain a Domain: First, identify an available domain. This step ensures you can create a valid email address. Call the /domains endpoint to list available domains.
  2. Create a User: Create a user account (temporary email address) using the /users endpoint, specifying one of the available domains.
  3. Get an Auth Token: Authenticate the newly created user and retrieve their authentication token from the /token endpoint.
  4. Fetch Messages: Use the obtained token to query the /messages endpoint, which will list any emails received by your temporary address. Initially, this list will likely be empty.

Here's a cURL example to fetch messages, assuming you have already created a user and obtained a token:

AUTH_TOKEN="YOUR_GENERATED_AUTH_TOKEN"

curl -X GET "https://api.mail.tm/messages" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $AUTH_TOKEN"

If successful, the API will return a JSON array of messages, which will be empty if no emails have been sent to the address yet. This confirms that your authentication and API calls are correctly configured. The mail.tm documentation provides further API reference details, including specific response structures and error codes.

Quick Reference: Getting Started Steps

Step What to Do Where
1. Get Domains List available temporary email domains. GET /domains
2. Create User Register a new temporary email address (user). POST /users
3. Get Token Authenticate user to obtain access token. POST /token
4. Fetch Messages Retrieve emails for the authenticated user. GET /messages

Common next steps

After successfully making your first request, several common next steps can enhance your integration with mail.tm:

  • Sending Test Emails: To verify your temporary inbox is working, send an email from an external client or another API to the temporary address you created. Then, re-fetch messages using the GET /messages endpoint to see the new email.
  • Polling for New Messages: For applications requiring real-time email reception, implement a polling mechanism to periodically check the GET /messages endpoint. Be mindful of rate limits to avoid being temporarily blocked. Consider exponential backoff strategies for polling, as recommended by Google Cloud's retry documentation.
  • Fetching Specific Message Content: Once you have a message ID from the GET /messages list, you can fetch the full content of a specific email using GET /messages/{id}. This endpoint provides the email body, headers, and attachments.
  • Deleting Messages and Users: Implement cleanup routines by deleting individual messages (DELETE /messages/{id}) or entire user accounts (DELETE /users/{id}), especially in testing environments to manage resources and maintain privacy.
  • Exploring SDKs: While mail.tm does not officially provide SDKs, community-contributed libraries for languages like Python or JavaScript might exist, which can simplify API interactions. Search for mail.tm on package managers like npm for JavaScript or PyPI for Python.
  • Error Handling: Implement robust error handling in your application to gracefully manage API responses indicating issues, such as invalid tokens, rate limits, or malformed requests. The API documentation specifies various HTTP status codes and error messages.

Troubleshooting the first call

Encountering issues during your initial API calls is common. Here are some troubleshooting tips for mail.tm:

  • Invalid Authentication Token: Ensure your Authorization: Bearer YOUR_TOKEN header is correctly formatted and that the token itself has not expired. Tokens are typically short-lived and may need to be refreshed periodically by re-calling the /token endpoint.
  • Incorrect Endpoint URL: Double-check that you are using the correct base URL (https://api.mail.tm) and the precise endpoint paths (e.g., /users, /token, /messages). Refer to the official mail.tm API documentation for exact paths.
  • Malformed Request Body: For POST requests (like creating a user or getting a token), ensure your JSON request body is valid and adheres to the expected schema (e.g., correct field names like address and password). Incorrect content types (e.g., not setting Content-Type: application/json) can also cause issues.
  • Rate Limiting: Extensive or rapid requests, especially during initial testing, can trigger rate limits. If you receive a 429 Too Many Requests status code, pause your requests and implement a retry mechanism with exponential backoff.
  • Domain Availability: When creating a user, ensure the domain you specify in the email address (e.g., example.com in [email protected]) is one of the active domains returned by the /domains endpoint. mail.tm frequently rotates its temporary domains.
  • Network Issues: Verify your application has internet connectivity and can reach the mail.tm API servers. Firewall settings or proxy configurations might interfere with outbound requests.
  • Check Server Status: Although mail.tm generally maintains high availability, temporary service disruptions can occur. Check the platform's status or community forums if issues persist and seem unrelated to your code.