Test email delivery in sandbox without real sends
Test email sending against Mailtrap's Sandbox - captured test inboxes with no real delivery, inspected via API, SMTP, or the UI.
Maintainer of this project? Claim this page to edit the listing.
13.6.1Add to Favorites
Why it matters
Capture and inspect outbound emails in a safe test environment during development, staging, and CI without delivering to real recipients, enabling validation of message content, headers, attachments, and spam scores.
Outcomes
What it gets done
Capture all outbound emails in sandboxes during dev, staging, or CI runs
Inspect message bodies, headers, attachments, and spam reports via API or UI
Automate integration tests by reading captured messages from the Sandbox API
Test email templates by routing sends to sandbox inboxes with inbox ID
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/ag-mailtrap-testing-with-sandbox | bash Overview
Testing with Mailtrap Email Sandbox
Covers testing email sending against Mailtrap's Sandbox test inboxes, using a separate token, host, and API from live sending to inspect captured mail. Use for dev, staging, CI, or demo environments where mail must stay captured in a test inbox and never reach a real recipient.
What it does
Email Sandbox captures outbound mail in test inboxes that are never delivered to real recipients, reachable via SDKs, the HTTP Email Testing API, or SMTP. It uses an entirely separate credential set from live sending - a $MAILTRAP_SANDBOX_API_TOKEN with Testing/Sandbox scope, never the live $MAILTRAP_API_TOKEN - and a distinct host, sandbox.api.mailtrap.io, which the skill explicitly warns is not the same as send.api.mailtrap.io used for real sends.
When to use - and when NOT to
Use it for dev, staging, CI, or demo environments where mail must never leave a test inbox, for inspecting sent message bodies/headers/attachments/spam scores via the Sandbox API or UI, for automated tests asserting against captured mail, or for testing Mailtrap templates by pointing at sandbox endpoints with a valid inbox ID. It is not for live sends to real recipients (mailtrap-sending-emails covers that), and it defers to Mailtrap's own docs for full framework setup guides rather than covering every framework here.
Inputs and outputs
Every sandbox (test inbox) has a unique inbox ID, visible in its UI URL and required for both sending and reading via the REST API. Core endpoints: GET /inboxes lists sandboxes, GET /inboxes/{inbox_id}/messages lists captured messages, GET /inboxes/{inbox_id}/messages/{id} fetches one, and POST /inboxes/{inbox_id}/messages sends a test email. SMTP testing uses sandbox.smtp.mailtrap.io on port 2525 (default; 25/465-SSL/587 also work) with sandbox-specific credentials from the Integration tab - SMTP suits apps that already send via SMTP and just need host/port/credential changes, while the HTTP API suits new integrations and programmatic test automation. Official SDKs (Node.js, Python, PHP, Ruby, Java, .NET, CLI) expose test-mode and inbox-ID flags, so the same integration code can point at sandbox or live simply by switching credentials/mode between environments. Each sandbox also has an inbound test address (alias@inbox.mailtrap.io), with plus-addressing available to isolate test scenarios.
GET https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes/{inbox_id}/messages
Integrations
Sandbox and live sending share the same account and SDK codebases but never the same tokens, hosts, or endpoints - mixing them up (using a production token for sandbox, or hitting sandbox.api.mailtrap.io expecting live delivery behavior) is the most common mistake the skill flags. Template testing pairs with Mailtrap's Handlebars-based email templates, pointed at the sandbox host with a valid inbox ID instead of the live send endpoint.
Who it's for
Developers who need to verify outbound email content and behavior - headers, HTML rendering, attachments, spam scoring, template variables - in development, staging, or CI without any risk of a real recipient receiving test mail, using the same SDK and API patterns they'll later point at live sending once ready.
Source README
Testing with Mailtrap Email Sandbox
Overview
Email Sandbox captures mail in sandboxes (test inboxes)-a test environment where messages are not delivered to real recipients. You can send to sandboxes using our SDKs, HTTP API, or SMTP, depending on your needs.
Before generating SDK code: read the README of the relevant SDK repository (see mailtrap-sending-emails) for current sandbox mode options, inbox id, and constructor flags. Do not rely on memory.
Related skills: mailtrap-sending-emails (live sending hosts and streams).
When to use
- You want no real delivery: dev, staging, CI, or demos where mail must stay in a test inbox.
- You need to inspect what was sent: bodies, headers, attachments, or basic checks (e.g. spam report) via Sandbox / Testing API or the UI.
- You are automating tests against captured mail.
- You will only change SMTP settings so an existing app sends into a sandbox-no need for a framework-by-framework tutorial from this skill.
When not to use
- Live sends to real recipients (
mailtrap-sending-emails). - For full framework setup guides or detailed API references, link users to Mailtrap's Integration tab for SMTP/API details and the API docs for specifics-don't cover every framework or API field here.
Quick reference
API base
| Service | Send mail URL | Auth header examples |
|---|---|---|
| Email Testing API (REST) | https://sandbox.api.mailtrap.io/api/send/{inbox_id} |
Authorization: Bearer $MAILTRAP_SANDBOX_API_TOKEN |
Tokens and account_id
Sandbox uses a separate token ($MAILTRAP_SANDBOX_API_TOKEN, Testing/Sandbox scope) - never reuse the live $MAILTRAP_API_TOKEN. The account_id in the example endpoints below is resolved at runtime via GET https://mailtrap.io/api/accounts. Store tokens in environment variables or a secrets manager.
When to use API vs SMTP
Use SMTP when testing apps that already send mail via SMTP (just update the host, port, and credentials).
Use the HTTP API when building new integrations or your app can make HTTP requests; it's better for programmatic testing and automation.
SMTP settings (sandbox)
| Setting | Value |
|---|---|
| Host | sandbox.smtp.mailtrap.io |
| Ports | 2525 (default), 25, 465 (SSL), 587 |
| Username / Password | Per sandbox credentials from the Integration tab in the Mailtrap UI |
Never use sandbox credentials or endpoints in production. Messages will only be captured in the sandbox, not delivered.
Key parameters
- Inbox ID: Every sandbox (test inbox) has a unique inbox id, visible in the UI URL and needed for sending or REST API operations.
- Token scope: Use a token with permissions for the relevant project and test inbox.
Typical use cases
- Capture all outbound mail in dev, test, or staging (no real recipients).
- View, validate, and assert message headers, bodies, HTML, attachments, or spam score.
- Run integration or CI checks that read from the Email Sandbox API.
- Test Mailtrap templates by pointing API or SDK/SMTP at
sandbox.api.mailtrap.io/sandbox.smtp.mailtrap.iowith a valid inbox id.
Example API paths
Use API docs for details, but typical endpoints include:
| Operation | URL | Reference |
|---|---|---|
| List sandboxes | GET https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes |
Sandboxes API |
| List messages | GET https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes/{inbox_id}/messages |
Messages |
| Fetch a message | GET https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes/{inbox_id}/messages/{id} |
Message details |
| Send test email | POST https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes/{inbox_id}/messages |
Send test emails |
For template testing, see the Integration tab of your template and Handlebars.
SDKs
Official Mailtrap SDKs support sandbox/inbox operations and provide flags or methods to set test mode and inbox id. This allows you to use the same integration for both live sending and sandbox testing-simply change the mode or credentials depending on your environment (development, staging, or production). For install commands and language coverage, see Mailtrap developer documentation. Repository READMEs have the latest sandbox options:
Common mistakes
| Mistake | Fix/Explanation |
|---|---|
| Expecting real delivery from sandbox | Mail in the sandbox is never delivered to recipients |
| Using production API token for sandbox | Use a token with proper sandbox/testing scope, granting access to the target inbox |
| Forgetting inbox id parameter | Always supply the inbox id (from UI or Integration tab) to associate messages with the correct inbox |
| Mixing sandbox and transactional endpoints | Testing API (sandbox.api.mailtrap.io) is not the same as send.api.mailtrap.io (live sending)! |
Sandbox email address
Each sandbox (test inbox) has an address like alias@inbox.mailtrap.io for inbound tests; plus-addressing can help isolate scenarios. See Email address per sandbox for limits and behavior.
Limitations
- This skill covers sandbox usage patterns; use Mailtrap's current API docs for full endpoint schemas.
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.