Receiving Emails

In this article, you'll learn how to create an inbound inbox and start receiving emails.

You need account-level token to create an inbound inbox.

Step 1. Create a folder via the API

First, you need to create a folder for categorizing and storing your inboxes. To create a folder, use the following command:

curl -X POST https://mailtrap.io/api/inbound/folders \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Support" }'

Note: Make sure to replace YOUR_API_KEY with your actual Mailtrap API token.

The command should give you the following output: {"id":10,"name":"Support"}%

Step 2. Create an inbox via the API

Insert your folder ID, enter the desired inbox name, and create an inbox with the following command:

curl -X POST https://mailtrap.io/api/inbound/folders/{folder_id}/inboxes \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Support tickets" }'

The terminal should send you a following message: {"id":15,"name":"Support tickets","address":"[e-mail]"}%

Your inbound inbox in this case would be: [e-mail] and you could start sending emails to this address.

If you want your email address to be under your custom sending domain, please see this section.

Step 3. List messages from your inbound inbox

Mailtrap returns a fully parsed email object, including envelope fields (sender, recipients, subjects), metadata (Message-ID, references) and raw headers, all in a single JSON.

To list messages from your inbound inbox, use the following command:

curl -X GET 'https://mailtrap.io/api/inbound/inboxes/{inbox_id}/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Note: Make sure to replace {inbox_id} with your actual inbox ID (i.e., 15).

You should get the following output:

{"id":"1866872391602282496","inbox_id":15,"from":"Ivan Djuric [e-mail]","to":["[e-mail]"],"cc":[],"bcc":[],"reply_to":null,"subject":"Hello from the other side","message_id":"[e-mail]","in_reply_to":null,"references":[],"headers":{"mime-version":"1.0 (Mac OS X Mail 16.0 \(3864.600.51.1.1\))","return-path":"[e-mail]"},"size":3665,"html_size":null,"text_size":24,"received_at":"2026-06-02T08:17:31.878Z","attachments":[]}

You can use the message ID, the id field, to get a message:

curl -X GET https://mailtrap.io/api/inbound/inboxes/{inbox_id}/messages/{id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

Or, delete a message if you wish:

curl -X DELETE https://mailtrap.io/api/inbound/inboxes/{inbox_id}/messages/{id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

Creating a custom domain (catch-all) inbox

By default, Mailtrap-generated inboxes use an address under the @inbound-mailtrap.io domain. If you prefer to use your own sending domain for your inbox address, you can create a catch-all inbox under that domain.

1

First, configure your sending domain to receive inbound emails

1. Go to the Domains page and select the sending domain you want to use for your inbox.

2. Open the Domain Verification tab.

3. Under Add DNS records to your domain provider, enable Inbound domain receiving:

   
4. Add the provided MX record to your domain's DNS settings.

2

Next, create an inbox using your own domain

Once the MX record has been added, you will need the following:

1. Your domain ID (You can get this by using the List Domains API endpoint.)

2. Your folder ID (You can get this by using the List Folders API endpoint.)

3. Your API key

Once you have all of the above, you are now ready to create an inbox:

Insert your folder ID, enter the desired inbox name, and create an inbox with the following command:

curl -X POST https://mailtrap.io/api/inbound/folders/{folder_id}/inboxes \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Support tickets", "domain_id": domain_id }'

The terminal should send you something like this message: {"id": 2, "name": "Support tickets", "address": "*@your-domain.com", "domain_id": 894 }

In this case, your inbound inbox can use any username under @your-domain.com (example: [e-mail], [e-mail]), and you can start sending emails to that address.

Currently, custom domain inboxes catch all emails sent to any username under the custom domain. In the future, we plan to support custom rules and forwarding based on the username.