API Tokens

In this article

• Mailtrap Email Testing
• Where to find tokens?
• Mailtrap Email Sending
• Auto-created token per domain 
• API Integration
• SMTP Integration
• Reset token
• Edit permissions
• Delete token

APIv2 tokens work with Mailtrap Email Testing, and Mailtrap Email Sending. 

The important thing is that you set up and use both products with the same token management system. 

Read more information about tokens with APIv2 in relation to both Mailtrap products below. 

Mailtrap Email Testing

The guidelines assume that you’ve set up Mailtrap Email Testing and use the corresponding APIv2. 

Where to find tokens?

Select Settings in the menu on the left, then API Tokens. You’ll see all active tokens, their creator, and access level. 

Click three vertical dots (More menu) to the far right of the specific user token and select Edit permissions. 

The following menu reveals what permissions and access levels that token has. Make sure it has admin access to specific Sandbox Projects or Inboxes by clicking on the corresponding boxes. 

Important Notes:

• You can also give Account Amin access to the token and get access to all Projects, Inboxes, and domains on that account. 

If you want to test how it works, you need to get authenticated using your API token. Mailtrap uses Bearer Authentication, so you need to pass the token under the Authorization header of your email. 

Mailtrap Email Sending

Add and manage tokens manually

Navigate to > Settings in the menu on the left and select API Tokens. 

To add a new token, click the “Add Token” button in the upper right corner. 

Type the token name into the designated field. It’s perfectly fine to have a custom name for the API token as it’s only for your reference, regardless of the use case.  

Then, assign permissions by checking the boxes in the corresponding access level columns. Note that if you want to send emails with this token, you must have admin permissions on a particular domain. 

Click the Save button and preview the new token under API Tokens main menu. 

Auto-created token per domain

When you create a domain, a token is automatically created and named based on the following formula: [domain name] + [token] + [token ID]. 

For example, if you create the www.example.com domain, the token for that domain will be named: example.com token 1234. By default, the automatically-generated token gets a Domain Admin access to Email API for the given domain. 

Note: 

You’ll need to Edit permissions for the automatically-generated token to allow for authorization on other domains under Email API, and the same goes for accessing Sandbox API. 

API Integration

Where to find tokens?

The automatically assigned token per domain is under API and SMTP Integration in Step 3 of the domain setup process. More precisely, it’s under the ‘Authorization: bearer….’ header. And alternatively, you can also find them in the API tokens page. 

SMTP Integration

The token per domain is under Password. 

Note: By design, in case of SMTP integration, the SMTP password is the same as the API token for the domain. 

SMTP or API, you can easily reset the token by clicking the “Reset credentials” function of the API and SMTP Integration section. 

Then, confirm your choice with the “Yes, Reset” button.

Important Notes:

• After clicking the “Reset credentials” function, the existing token per domain becomes invalid after 12 hours. So, you have a 12-hour window to update all apps that use the old API token. Afterward, the old token expires and some parts of your application will not work properly if their token hasn’t been updated. And all expired tokens get deleted from your account within 24 hours after expiration. 
• When you reset a token, the old one gets expired and a new one gets created. And the token ID is added to the token name the same way it’s done for automatically generated tokens eg. > mailtrap.example token 4231

Reset token

Aside from what’s mentioned above, you can also reset a token from the API Tokens menu. Click three vertical dots (More menu) at the far right of an active token. 

Click Reset API Token and confirm your choice by clicking on the corresponding button. 

Tip: Token More menu also allows you to copy a token to your clipboard. 

To remind you, after you reset the token you have a 12-hour window to update all apps that use the old token. Then, the token becomes invalid and your apps won’t work properly if the API token hasn’t been updated. Within 24 hours, the token gets deleted from the system. 

Edit permissions

As mentioned earlier, click the More menu at the far right of a token and select Edit permissions. 

Add or remove token permissions by clicking on the corresponding boxes. Then, confirm your selection with the Save button. 

Delete token

Again, you click the More menu and choose the Delete token option. 

Important Note: Keep in mind that a token gets deleted immediately. And you can’t delete the last token per domain.