Sandboxes (Inboxes)

Manage test inboxes

Manage Sandboxes (Inboxes) for email testing. Capture and inspect emails without delivering them to real recipients. This is ideal for development, staging, and QA environments.

Get your Sandbox ID

To use the Sandbox API, you need a Sandbox (Inbox) ID. You can get it in one of the following ways.

Option 1: From the inbox URL

1. Open your Sandbox in Mailtrap.

2. Copy the ID from the inbox URL.

Example:

• URL: https://mailtrap.io/inboxes/2564102/messages

• Sandbox ID: 2564102

Option 2: Via the API

Use the Get a list of inboxes endpoint to retrieve all Sandboxes in your account.

Get a list of inboxes

get

Get a list of inboxes.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

Responses

200

Returns the list of inboxes in the account to which the API token has access.

• permissions returns the permissions of the token for the inbox.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

get

/api/accounts/{account_id}/inboxes

cURLNode.jsPHPPython.NETJava

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

[
  {
    "id": 3538,
    "name": "Admin Inbox",
    "username": "b3a87978452ae1",
    "password": "6be9fcfc613a7c",
    "max_size": 0,
    "status": "active",
    "email_username": "b7eae548c3-54c542",
    "email_username_enabled": false,
    "sent_messages_count": 52,
    "forwarded_messages_count": 0,
    "used": false,
    "forward_from_email_address": "[email protected]",
    "project_id": 2293,
    "domain": "localhost",
    "pop3_domain": "localhost",
    "email_domain": "localhost",
    "emails_count": 0,
    "emails_unread_count": 0,
    "last_message_sent_at": null,
    "smtp_ports": [
      25,
      465,
      587,
      2525
    ],
    "pop3_ports": [
      1100,
      9950
    ],
    "max_message_size": 5242880,
    "permissions": {
      "can_read": true,
      "can_update": true,
      "can_destroy": true,
      "can_leave": true
    }
  },
  {
    "id": 4089,
    "name": "Viewer Inbox",
    "username": "1d0aa0282f7712",
    "password": "5667a20f611ae7",
    "max_size": 0,
    "status": "active",
    "email_username": "f25402f8df-b77899",
    "email_username_enabled": false,
    "sent_messages_count": 527,
    "forwarded_messages_count": 0,
    "used": false,
    "forward_from_email_address": "[email protected]",
    "project_id": 2293,
    "domain": "localhost",
    "pop3_domain": "localhost",
    "email_domain": "localhost",
    "emails_count": 0,
    "emails_unread_count": 0,
    "last_message_sent_at": null,
    "smtp_ports": [
      25,
      465,
      587,
      2525
    ],
    "pop3_ports": [
      1100,
      9950
    ],
    "max_message_size": 5242880,
    "permissions": {
      "can_read": true,
      "can_update": false,
      "can_destroy": false,
      "can_leave": true
    }
  }
]

Create an inbox

post

Create an inbox in a project.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

project_idinteger · int64 · min: 1Required

Unique project ID

Example: 4032

Body

application/json

Responses

200

Returns attributes of the inbox.

• permissions returns the permissions of the token for the inbox.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Returns not found error message

application/json

post

/api/accounts/{account_id}/projects/{project_id}/inboxes

cURLNode.jsPHPPython.NETJava

curl -X POST https://mailtrap.io/api/accounts/{account_id}/projects/{project_id}/inboxes \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "inbox": {
      "name": "My Test Inbox"
    }
  }'

{
  "id": 3538,
  "name": "Admin Inbox",
  "username": "b3a87978452ae1",
  "password": "6be9fcfc613a7c",
  "max_size": 0,
  "status": "active",
  "email_username": "b7eae548c3-54c542",
  "email_username_enabled": false,
  "sent_messages_count": 52,
  "forwarded_messages_count": 0,
  "used": false,
  "forward_from_email_address": "[email protected]",
  "project_id": 2293,
  "domain": "localhost",
  "pop3_domain": "localhost",
  "email_domain": "localhost",
  "api_domain": "localhost",
  "emails_count": 0,
  "emails_unread_count": 0,
  "last_message_sent_at": null,
  "smtp_ports": [
    25,
    465,
    587,
    2525
  ],
  "pop3_ports": [
    1100,
    9950
  ],
  "max_message_size": 5242880,
  "permissions": {
    "can_read": true,
    "can_update": true,
    "can_destroy": true,
    "can_leave": true
  }
}

Get inbox attributes

get

Get inbox attributes by inbox id. See the list of attributes in the example

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

inbox_idinteger · int64 · min: 1Required

Unique inbox ID

Example: 4015

Responses

200

Returns attributes of the inbox.

• permissions returns the permissions of the token for the inbox.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Returns not found error message

application/json

get

/api/accounts/{account_id}/inboxes/{inbox_id}

cURLNode.jsPHPPython.NETJava

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

{
  "id": 3538,
  "name": "Admin Inbox",
  "username": "b3a87978452ae1",
  "password": "6be9fcfc613a7c",
  "max_size": 0,
  "status": "active",
  "email_username": "b7eae548c3-54c542",
  "email_username_enabled": false,
  "sent_messages_count": 52,
  "forwarded_messages_count": 0,
  "used": false,
  "forward_from_email_address": "[email protected]",
  "project_id": 2293,
  "domain": "localhost",
  "pop3_domain": "localhost",
  "email_domain": "localhost",
  "api_domain": "localhost",
  "emails_count": 0,
  "emails_unread_count": 0,
  "last_message_sent_at": null,
  "smtp_ports": [
    25,
    465,
    587,
    2525
  ],
  "pop3_ports": [
    1100,
    9950
  ],
  "max_message_size": 5242880,
  "permissions": {
    "can_read": true,
    "can_update": true,
    "can_destroy": true,
    "can_leave": true
  }
}

Delete an inbox

delete

Delete an inbox with all its emails.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

inbox_idinteger · int64 · min: 1Required

Unique inbox ID

Example: 4015

Responses

200

Returns attributes of the inbox.

• permissions returns the permissions of the token for the inbox.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Returns not found error message

application/json

delete

/api/accounts/{account_id}/inboxes/{inbox_id}

cURLNode.jsPHPPython.NETJava

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

{
  "id": 3538,
  "name": "Admin Inbox",
  "username": "b3a87978452ae1",
  "password": "6be9fcfc613a7c",
  "max_size": 0,
  "status": "active",
  "email_username": "b7eae548c3-54c542",
  "email_username_enabled": false,
  "sent_messages_count": 52,
  "forwarded_messages_count": 0,
  "used": false,
  "forward_from_email_address": "[email protected]",
  "project_id": 2293,
  "domain": "localhost",
  "pop3_domain": "localhost",
  "email_domain": "localhost",
  "api_domain": "localhost",
  "emails_count": 0,
  "emails_unread_count": 0,
  "last_message_sent_at": null,
  "smtp_ports": [
    25,
    465,
    587,
    2525
  ],
  "pop3_ports": [
    1100,
    9950
  ],
  "max_message_size": 5242880,
  "permissions": {
    "can_read": true,
    "can_update": true,
    "can_destroy": true,
    "can_leave": true
  }
}

Update an inbox

patch

Update inbox name, inbox email username.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

inbox_idinteger · int64 · min: 1Required

Unique inbox ID

Example: 4015

Body

application/json

Responses

200

Returns attributes of the inbox.

• permissions returns the permissions of the token for the inbox.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Returns not found error message

application/json

patch

/api/accounts/{account_id}/inboxes/{inbox_id}

cURLNode.jsPHPPython.NETJava

curl -X PATCH https://mailtrap.io/api/accounts/{account_id}/inboxes/{inbox_id} \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "inbox": {
      "name": "Updated Inbox Name",
      "email_username": "new-username"
    }
  }'

{
  "id": 3538,
  "name": "Admin Inbox",
  "username": "b3a87978452ae1",
  "password": "6be9fcfc613a7c",
  "max_size": 0,
  "status": "active",
  "email_username": "b7eae548c3-54c542",
  "email_username_enabled": false,
  "sent_messages_count": 52,
  "forwarded_messages_count": 0,
  "used": false,
  "forward_from_email_address": "[email protected]",
  "project_id": 2293,
  "domain": "localhost",
  "pop3_domain": "localhost",
  "email_domain": "localhost",
  "api_domain": "localhost",
  "emails_count": 0,
  "emails_unread_count": 0,
  "last_message_sent_at": null,
  "smtp_ports": [
    25,
    465,
    587,
    2525
  ],
  "pop3_ports": [
    1100,
    9950
  ],
  "max_message_size": 5242880,
  "permissions": {
    "can_read": true,
    "can_update": true,
    "can_destroy": true,
    "can_leave": true
  }
}

Clean inbox

patch

Delete all messages (emails) from inbox.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

inbox_idinteger · int64 · min: 1Required

Unique inbox ID

Example: 4015

Responses

200

Returns attributes of the inbox.

• permissions returns the permissions of the token for the inbox.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Returns not found error message

application/json

patch

/api/accounts/{account_id}/inboxes/{inbox_id}/clean

cURLNode.jsPHPPython.NETJava

curl -X PATCH https://mailtrap.io/api/accounts/{account_id}/inboxes/{inbox_id}/clean \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 3538,
  "name": "Admin Inbox",
  "username": "b3a87978452ae1",
  "password": "6be9fcfc613a7c",
  "max_size": 0,
  "status": "active",
  "email_username": "b7eae548c3-54c542",
  "email_username_enabled": false,
  "sent_messages_count": 52,
  "forwarded_messages_count": 0,
  "used": false,
  "forward_from_email_address": "[email protected]",
  "project_id": 2293,
  "domain": "localhost",
  "pop3_domain": "localhost",
  "email_domain": "localhost",
  "api_domain": "localhost",
  "emails_count": 0,
  "emails_unread_count": 0,
  "last_message_sent_at": null,
  "smtp_ports": [
    25,
    465,
    587,
    2525
  ],
  "pop3_ports": [
    1100,
    9950
  ],
  "max_message_size": 5242880,
  "permissions": {
    "can_read": true,
    "can_update": true,
    "can_destroy": true,
    "can_leave": true
  }
}

Mark as read

patch

Mark all messages in the inbox as read.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

inbox_idinteger · int64 · min: 1Required

Unique inbox ID

Example: 4015

Responses

200

Returns attributes of the inbox.

• permissions returns the permissions of the token for the inbox.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Returns not found error message

application/json

patch

/api/accounts/{account_id}/inboxes/{inbox_id}/all_read

cURLNode.jsPHPPython.NETJava

curl -X PATCH https://mailtrap.io/api/accounts/{account_id}/inboxes/{inbox_id}/all_read \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 3538,
  "name": "Admin Inbox",
  "username": "b3a87978452ae1",
  "password": "6be9fcfc613a7c",
  "max_size": 0,
  "status": "active",
  "email_username": "b7eae548c3-54c542",
  "email_username_enabled": false,
  "sent_messages_count": 52,
  "forwarded_messages_count": 0,
  "used": false,
  "forward_from_email_address": "[email protected]",
  "project_id": 2293,
  "domain": "localhost",
  "pop3_domain": "localhost",
  "email_domain": "localhost",
  "api_domain": "localhost",
  "emails_count": 0,
  "emails_unread_count": 0,
  "last_message_sent_at": null,
  "smtp_ports": [
    25,
    465,
    587,
    2525
  ],
  "pop3_ports": [
    1100,
    9950
  ],
  "max_message_size": 5242880,
  "permissions": {
    "can_read": true,
    "can_update": true,
    "can_destroy": true,
    "can_leave": true
  }
}

Reset credentials

patch

Reset SMTP credentials of the inbox.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

inbox_idinteger · int64 · min: 1Required

Unique inbox ID

Example: 4015

Responses

200

Returns attributes of the inbox.

• permissions returns the permissions of the token for the inbox.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Returns not found error message

application/json

patch

/api/accounts/{account_id}/inboxes/{inbox_id}/reset_credentials

cURLNode.jsPHPPython.NETJava

curl -X PATCH https://mailtrap.io/api/accounts/{account_id}/inboxes/{inbox_id}/reset_credentials \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 3538,
  "name": "Admin Inbox",
  "username": "b3a87978452ae1",
  "password": "6be9fcfc613a7c",
  "max_size": 0,
  "status": "active",
  "email_username": "b7eae548c3-54c542",
  "email_username_enabled": false,
  "sent_messages_count": 52,
  "forwarded_messages_count": 0,
  "used": false,
  "forward_from_email_address": "[email protected]",
  "project_id": 2293,
  "domain": "localhost",
  "pop3_domain": "localhost",
  "email_domain": "localhost",
  "api_domain": "localhost",
  "emails_count": 0,
  "emails_unread_count": 0,
  "last_message_sent_at": null,
  "smtp_ports": [
    25,
    465,
    587,
    2525
  ],
  "pop3_ports": [
    1100,
    9950
  ],
  "max_message_size": 5242880,
  "permissions": {
    "can_read": true,
    "can_update": true,
    "can_destroy": true,
    "can_leave": true
  }
}

Enable email address

patch

Turn the email address of the inbox on/off.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

inbox_idinteger · int64 · min: 1Required

Unique inbox ID

Example: 4015

Responses

200

Returns attributes of the inbox.

• permissions returns the permissions of the token for the inbox.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Returns not found error message

application/json

patch

/api/accounts/{account_id}/inboxes/{inbox_id}/toggle_email_username

cURLNode.jsPHPPython.NETJava

curl -X PATCH https://mailtrap.io/api/accounts/{account_id}/inboxes/{inbox_id}/toggle_email_username \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 3538,
  "name": "Admin Inbox",
  "username": "b3a87978452ae1",
  "password": "6be9fcfc613a7c",
  "max_size": 0,
  "status": "active",
  "email_username": "b7eae548c3-54c542",
  "email_username_enabled": false,
  "sent_messages_count": 52,
  "forwarded_messages_count": 0,
  "used": false,
  "forward_from_email_address": "[email protected]",
  "project_id": 2293,
  "domain": "localhost",
  "pop3_domain": "localhost",
  "email_domain": "localhost",
  "api_domain": "localhost",
  "emails_count": 0,
  "emails_unread_count": 0,
  "last_message_sent_at": null,
  "smtp_ports": [
    25,
    465,
    587,
    2525
  ],
  "pop3_ports": [
    1100,
    9950
  ],
  "max_message_size": 5242880,
  "permissions": {
    "can_read": true,
    "can_update": true,
    "can_destroy": true,
    "can_leave": true
  }
}

Reset email address

patch

Reset username of email address per inbox.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

inbox_idinteger · int64 · min: 1Required

Unique inbox ID

Example: 4015

Responses

200

Returns attributes of the inbox.

• permissions returns the permissions of the token for the inbox.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Returns not found error message

application/json

patch

/api/accounts/{account_id}/inboxes/{inbox_id}/reset_email_username

cURLNode.jsPHPPython.NETJava

curl -X PATCH https://mailtrap.io/api/accounts/{account_id}/inboxes/{inbox_id}/reset_email_username \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 3538,
  "name": "Admin Inbox",
  "username": "b3a87978452ae1",
  "password": "6be9fcfc613a7c",
  "max_size": 0,
  "status": "active",
  "email_username": "b7eae548c3-54c542",
  "email_username_enabled": false,
  "sent_messages_count": 52,
  "forwarded_messages_count": 0,
  "used": false,
  "forward_from_email_address": "[email protected]",
  "project_id": 2293,
  "domain": "localhost",
  "pop3_domain": "localhost",
  "email_domain": "localhost",
  "api_domain": "localhost",
  "emails_count": 0,
  "emails_unread_count": 0,
  "last_message_sent_at": null,
  "smtp_ports": [
    25,
    465,
    587,
    2525
  ],
  "pop3_ports": [
    1100,
    9950
  ],
  "max_message_size": 5242880,
  "permissions": {
    "can_read": true,
    "can_update": true,
    "can_destroy": true,
    "can_leave": true
  }
}