For the complete documentation index, see llms.txt. This page is also available as Markdown.

Sandboxes

Manage test sandboxes

Manage Sandboxes 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 ID. You can get it in one of the following ways.

Option 1: From the sandbox URL

  1. Open your Sandbox in Mailtrap.

  2. Copy the ID from the sandbox URL.

Example:

  • URL: https://mailtrap.io/sandboxes/2564102/settings

  • Sandbox ID: 2564102

Option 2: Via the API

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

Get a list of sandboxes

get

Get a list of sandboxes.

Authorizations
Api-TokenstringRequired

Pass the API token in the Api-Token

Responses
200

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

  • permissions returns the permissions of the token for the sandbox.
application/json
idintegerOptional
namestringOptional
usernamestringOptional
passwordstring · nullableOptional

Password is only available if you have admin permissions for the sandbox.

max_sizeintegerOptional
statusstring · enumOptionalPossible values:
email_usernamestringOptional
email_username_enabledbooleanOptional
sent_messages_countintegerOptional
forwarded_messages_countintegerOptional
usedbooleanOptional
forward_from_email_addressstringOptional
project_idintegerOptional
domainstringOptional
pop3_domainstringOptional
email_domainstringOptional
api_domainstringOptional
emails_countintegerOptional
emails_unread_countintegerOptional
last_message_sent_atstring · nullableOptional
smtp_portsinteger[]Optional
pop3_portsinteger[]Optional
max_message_sizeintegerOptional
get/api/sandboxes

Create a sandbox

post

Create a sandbox in a project.

Authorizations
Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters
project_idinteger · int64 · min: 1Required

Unique project ID

Example: 4032
Body
Responses
200

Returns attributes of the sandbox.

  • permissions returns the permissions of the token for the sandbox.
application/json
idintegerOptional
namestringOptional
usernamestringOptional
passwordstring · nullableOptional

Password is only available if you have admin permissions for the sandbox.

max_sizeintegerOptional
statusstring · enumOptionalPossible values:
email_usernamestringOptional
email_username_enabledbooleanOptional
sent_messages_countintegerOptional
forwarded_messages_countintegerOptional
usedbooleanOptional
forward_from_email_addressstringOptional
project_idintegerOptional
domainstringOptional
pop3_domainstringOptional
email_domainstringOptional
api_domainstringOptional
emails_countintegerOptional
emails_unread_countintegerOptional
last_message_sent_atstring · nullableOptional
smtp_portsinteger[]Optional
pop3_portsinteger[]Optional
max_message_sizeintegerOptional
post/api/projects/{project_id}/sandboxes

Get sandbox attributes

get

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

Authorizations
Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters
sandbox_idinteger · int64 · min: 1Required

Unique sandbox ID

Example: 4015
Responses
200

Returns attributes of the sandbox.

  • permissions returns the permissions of the token for the sandbox.
application/json
idintegerOptional
namestringOptional
usernamestringOptional
passwordstring · nullableOptional

Password is only available if you have admin permissions for the sandbox.

max_sizeintegerOptional
statusstring · enumOptionalPossible values:
email_usernamestringOptional
email_username_enabledbooleanOptional
sent_messages_countintegerOptional
forwarded_messages_countintegerOptional
usedbooleanOptional
forward_from_email_addressstringOptional
project_idintegerOptional
domainstringOptional
pop3_domainstringOptional
email_domainstringOptional
api_domainstringOptional
emails_countintegerOptional
emails_unread_countintegerOptional
last_message_sent_atstring · nullableOptional
smtp_portsinteger[]Optional
pop3_portsinteger[]Optional
max_message_sizeintegerOptional
get/api/sandboxes/{sandbox_id}

Delete a sandbox

delete

Delete a sandbox with all its emails.

Authorizations
Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters
sandbox_idinteger · int64 · min: 1Required

Unique sandbox ID

Example: 4015
Responses
200

Returns attributes of the sandbox.

  • permissions returns the permissions of the token for the sandbox.
application/json
idintegerOptional
namestringOptional
usernamestringOptional
passwordstring · nullableOptional

Password is only available if you have admin permissions for the sandbox.

max_sizeintegerOptional
statusstring · enumOptionalPossible values:
email_usernamestringOptional
email_username_enabledbooleanOptional
sent_messages_countintegerOptional
forwarded_messages_countintegerOptional
usedbooleanOptional
forward_from_email_addressstringOptional
project_idintegerOptional
domainstringOptional
pop3_domainstringOptional
email_domainstringOptional
api_domainstringOptional
emails_countintegerOptional
emails_unread_countintegerOptional
last_message_sent_atstring · nullableOptional
smtp_portsinteger[]Optional
pop3_portsinteger[]Optional
max_message_sizeintegerOptional
delete/api/sandboxes/{sandbox_id}

Update a sandbox

patch

Update sandbox name, sandbox email username.

Authorizations
Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters
sandbox_idinteger · int64 · min: 1Required

Unique sandbox ID

Example: 4015
Body
Responses
200

Returns attributes of the sandbox.

  • permissions returns the permissions of the token for the sandbox.
application/json
idintegerOptional
namestringOptional
usernamestringOptional
passwordstring · nullableOptional

Password is only available if you have admin permissions for the sandbox.

max_sizeintegerOptional
statusstring · enumOptionalPossible values:
email_usernamestringOptional
email_username_enabledbooleanOptional
sent_messages_countintegerOptional
forwarded_messages_countintegerOptional
usedbooleanOptional
forward_from_email_addressstringOptional
project_idintegerOptional
domainstringOptional
pop3_domainstringOptional
email_domainstringOptional
api_domainstringOptional
emails_countintegerOptional
emails_unread_countintegerOptional
last_message_sent_atstring · nullableOptional
smtp_portsinteger[]Optional
pop3_portsinteger[]Optional
max_message_sizeintegerOptional
patch/api/sandboxes/{sandbox_id}

Clean sandbox

patch

Delete all messages (emails) from sandbox.

Authorizations
Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters
sandbox_idinteger · int64 · min: 1Required

Unique sandbox ID

Example: 4015
Responses
200

Returns attributes of the sandbox.

  • permissions returns the permissions of the token for the sandbox.
application/json
idintegerOptional
namestringOptional
usernamestringOptional
passwordstring · nullableOptional

Password is only available if you have admin permissions for the sandbox.

max_sizeintegerOptional
statusstring · enumOptionalPossible values:
email_usernamestringOptional
email_username_enabledbooleanOptional
sent_messages_countintegerOptional
forwarded_messages_countintegerOptional
usedbooleanOptional
forward_from_email_addressstringOptional
project_idintegerOptional
domainstringOptional
pop3_domainstringOptional
email_domainstringOptional
api_domainstringOptional
emails_countintegerOptional
emails_unread_countintegerOptional
last_message_sent_atstring · nullableOptional
smtp_portsinteger[]Optional
pop3_portsinteger[]Optional
max_message_sizeintegerOptional
patch/api/sandboxes/{sandbox_id}/clean

Mark as read

patch

Mark all messages in the sandbox as read.

Authorizations
Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters
sandbox_idinteger · int64 · min: 1Required

Unique sandbox ID

Example: 4015
Responses
200

Returns attributes of the sandbox.

  • permissions returns the permissions of the token for the sandbox.
application/json
idintegerOptional
namestringOptional
usernamestringOptional
passwordstring · nullableOptional

Password is only available if you have admin permissions for the sandbox.

max_sizeintegerOptional
statusstring · enumOptionalPossible values:
email_usernamestringOptional
email_username_enabledbooleanOptional
sent_messages_countintegerOptional
forwarded_messages_countintegerOptional
usedbooleanOptional
forward_from_email_addressstringOptional
project_idintegerOptional
domainstringOptional
pop3_domainstringOptional
email_domainstringOptional
api_domainstringOptional
emails_countintegerOptional
emails_unread_countintegerOptional
last_message_sent_atstring · nullableOptional
smtp_portsinteger[]Optional
pop3_portsinteger[]Optional
max_message_sizeintegerOptional
patch/api/sandboxes/{sandbox_id}/all_read

Reset credentials

patch

Reset SMTP credentials of the sandbox.

Authorizations
Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters
sandbox_idinteger · int64 · min: 1Required

Unique sandbox ID

Example: 4015
Responses
200

Returns attributes of the sandbox.

  • permissions returns the permissions of the token for the sandbox.
application/json
idintegerOptional
namestringOptional
usernamestringOptional
passwordstring · nullableOptional

Password is only available if you have admin permissions for the sandbox.

max_sizeintegerOptional
statusstring · enumOptionalPossible values:
email_usernamestringOptional
email_username_enabledbooleanOptional
sent_messages_countintegerOptional
forwarded_messages_countintegerOptional
usedbooleanOptional
forward_from_email_addressstringOptional
project_idintegerOptional
domainstringOptional
pop3_domainstringOptional
email_domainstringOptional
api_domainstringOptional
emails_countintegerOptional
emails_unread_countintegerOptional
last_message_sent_atstring · nullableOptional
smtp_portsinteger[]Optional
pop3_portsinteger[]Optional
max_message_sizeintegerOptional
patch/api/sandboxes/{sandbox_id}/reset_credentials

Enable email address

patch

Turn the email address of the sandbox on/off.

Authorizations
Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters
sandbox_idinteger · int64 · min: 1Required

Unique sandbox ID

Example: 4015
Responses
200

Returns attributes of the sandbox.

  • permissions returns the permissions of the token for the sandbox.
application/json
idintegerOptional
namestringOptional
usernamestringOptional
passwordstring · nullableOptional

Password is only available if you have admin permissions for the sandbox.

max_sizeintegerOptional
statusstring · enumOptionalPossible values:
email_usernamestringOptional
email_username_enabledbooleanOptional
sent_messages_countintegerOptional
forwarded_messages_countintegerOptional
usedbooleanOptional
forward_from_email_addressstringOptional
project_idintegerOptional
domainstringOptional
pop3_domainstringOptional
email_domainstringOptional
api_domainstringOptional
emails_countintegerOptional
emails_unread_countintegerOptional
last_message_sent_atstring · nullableOptional
smtp_portsinteger[]Optional
pop3_portsinteger[]Optional
max_message_sizeintegerOptional
patch/api/sandboxes/{sandbox_id}/toggle_email_username

Reset email address

patch

Reset username of email address per sandbox.

Authorizations
Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters
sandbox_idinteger · int64 · min: 1Required

Unique sandbox ID

Example: 4015
Responses
200

Returns attributes of the sandbox.

  • permissions returns the permissions of the token for the sandbox.
application/json
idintegerOptional
namestringOptional
usernamestringOptional
passwordstring · nullableOptional

Password is only available if you have admin permissions for the sandbox.

max_sizeintegerOptional
statusstring · enumOptionalPossible values:
email_usernamestringOptional
email_username_enabledbooleanOptional
sent_messages_countintegerOptional
forwarded_messages_countintegerOptional
usedbooleanOptional
forward_from_email_addressstringOptional
project_idintegerOptional
domainstringOptional
pop3_domainstringOptional
email_domainstringOptional
api_domainstringOptional
emails_countintegerOptional
emails_unread_countintegerOptional
last_message_sent_atstring · nullableOptional
smtp_portsinteger[]Optional
pop3_portsinteger[]Optional
max_message_sizeintegerOptional
patch/api/sandboxes/{sandbox_id}/reset_email_username

Last updated

Was this helpful?