Skip to main content

Hosted Test Inboxes

Free · 1 inboxShuttle · 5 inboxesBlastoff · 25 pooled inboxes
Compatibility

Automatic email codes and protected email links are documented against Testronaut CLI v1.10.0.

Hosted test inboxes receive short authentication codes, invitations, and magic-login links during automated tests. Do not use these addresses for personal or production-sensitive email.

Create an inbox​

  1. Sign in to Mission Control.
  2. Open Settings → Email inboxes.
  3. Select Create inbox.
  4. Enter a searchable nickname, such as github staging.
  5. Copy the generated @inbox.testronaut.app address into the test account or signup flow.

You can rename an inbox without changing its address. Retiring an inbox is permanent: its address is never reused and retained messages are deleted.

Plan limits and retention​

PlanInboxesMessages per inboxRetention
Free11007 days
Shuttle51,00030 days
Blastoff25 pooled1,00030 days

See Pricing for current commercial terms.

Connect the CLI​

Authenticate the project first:

testronaut login

Set a default inbox in testronaut-config.json:

{
  "emailInboxName": "github staging"
}

Or select one for a single run:

testronaut signup.mission.js -o inbox="github staging"

If only one inbox is active, the CLI can select it automatically. Nickname matching tolerates simple differences in case, spaces, and punctuation.

Retrieve an email code​

Describe the desired outcome in the mission:

export const signupMission = `
  Create an account using the hosted test inbox.
  When the site sends an email verification code, retrieve the recent code
  from the inbox named github staging and complete verification.
  Report SUCCESS only after the verified account page appears.
`;

The agent uses get_email_code and polls for up to 45 seconds by default. It searches recent messages, returns short code candidates, and keeps email bodies and codes out of mission logs and reports.

Email links are bearer credentials. Testronaut keeps the full URL out of model context and requires an explicit destination-host allowlist.

testronaut-config.json
{
  "emailInboxName": "staging",
  "emailLinks": {
    "allowedHosts": ["accounts.example.test", "app.example.test"]
  }
}

You can provide the allowlist through the environment instead:

TESTRONAUT_EMAIL_LINK_HOSTS=accounts.example.test,app.example.test \
  testronaut invitation.mission.js

A mission can then request the invitation or magic-login link. Testronaut retrieves safe metadata first and opens only an HTTPS destination matching the allowlist.

Security model​

  • Sanitized email is untrusted input; the agent may select code candidates but should not follow instructions in the message body.
  • HTML, images, attachments, and ordinary links are removed from email-code results.
  • Link URLs remain hidden until the CLI resolves an opaque link identifier.
  • Only HTTPS destinations matching emailLinks.allowedHosts are opened.
  • Codes, email bodies, and bearer-link URLs are excluded from logs and reports.
  • Human input remains available as a fallback for unsupported verification flows.

Troubleshooting​

No active inbox: Create an inbox in Mission Control or activate an existing one.

Inbox nickname is required: Set emailInboxName, pass -o inbox=<nickname>, or leave exactly one inbox active.

No code arrived: Confirm the tested service used the generated address and sent the message within the default lookback window.

Link host is not allowed: Add the exact destination host to emailLinks.allowedHosts. Do not add broad or unrelated domains merely to bypass this protection.