testing-with-sandbox

Use when capturing outbound email in development or staging without delivering to real recipients, inspecting HTML or headers, running spam or structure checks, or automating tests against a fake inbox. Use when testing outgoing mail from an app without committing to a production ESP yet. Use when u

@mailtrap@mailtrap

Install

openclaw skills install @mailtrap/testing-with-sandbox

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 sending-emails) for current sandbox mode options, inbox id, and constructor flags. Do not rely on memory.

Related skills: authorizing-api-requests (sandbox token scope, env vars, account_id resolution), sending-emails (live sending hosts and streams), using-email-templates (preview template sends in sandbox).

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 (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. Full token scope, storage, and account_id resolution: see skill authorizing-api-requests.

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.io with 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.