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

Open your Sandbox in Mailtrap.
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

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

get

/api/sandboxes

curl -X GET https://mailtrap.io/api/sandboxes \
  -H 'Authorization: Bearer YOUR_API_KEY'

[
  {
    "id": 3538,
    "name": "Admin Sandbox",
    "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 Sandbox",
    "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 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

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/projects/{project_id}/sandboxes

curl -X POST https://mailtrap.io/api/projects/{project_id}/sandboxes \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": {
      "name": "My Test Sandbox"
    }
  }'

{
  "id": 3538,
  "name": "Admin Sandbox",
  "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 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

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/sandboxes/{sandbox_id}

curl -X GET https://mailtrap.io/api/sandboxes/{sandbox_id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 3538,
  "name": "Admin Sandbox",
  "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 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

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/sandboxes/{sandbox_id}

curl -X DELETE https://mailtrap.io/api/sandboxes/{sandbox_id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 3538,
  "name": "Admin Sandbox",
  "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 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

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/sandboxes/{sandbox_id}

curl -X PATCH https://mailtrap.io/api/sandboxes/{sandbox_id} \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": {
      "name": "Updated Sandbox Name",
      "email_username": "new-username"
    }
  }'

{
  "id": 3538,
  "name": "Admin Sandbox",
  "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 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

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/sandboxes/{sandbox_id}/clean

curl -X PATCH https://mailtrap.io/api/sandboxes/{sandbox_id}/clean \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 3538,
  "name": "Admin Sandbox",
  "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 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

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/sandboxes/{sandbox_id}/all_read

curl -X PATCH https://mailtrap.io/api/sandboxes/{sandbox_id}/all_read \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 3538,
  "name": "Admin Sandbox",
  "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 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

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/sandboxes/{sandbox_id}/reset_credentials

curl -X PATCH https://mailtrap.io/api/sandboxes/{sandbox_id}/reset_credentials \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 3538,
  "name": "Admin Sandbox",
  "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 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

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/sandboxes/{sandbox_id}/toggle_email_username

curl -X PATCH https://mailtrap.io/api/sandboxes/{sandbox_id}/toggle_email_username \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 3538,
  "name": "Admin Sandbox",
  "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 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

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/sandboxes/{sandbox_id}/reset_email_username

curl -X PATCH https://mailtrap.io/api/sandboxes/{sandbox_id}/reset_email_username \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 3538,
  "name": "Admin Sandbox",
  "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
  }
}

PreviousProjects NextMessages

Last updated 2 days ago

Was this helpful?