temp-mail

name	temp-mail
description	Provision disposable email inboxes for agent workflows such as website registration, account activation, email verification, OTP retrieval, waitlist signup, and tests that need to receive email.

Temp Mail

Use It For

• Website registration and account creation
• Account activation and email confirmation
• OTP and verification-code retrieval
• Waitlist, onboarding, and test flows that require inbox access

Do Not Use It For

• Clicking around a temp-mail frontend UI
• Configuring domains, routes, or backend email infrastructure
• Debugging SMTP, MX, DNS, or provider deliverability issues
• Long-lived mailbox workflows

Quick Start

python scripts/temp_mail.py create
python scripts/temp_mail.py inbox --state-file /tmp/temp-mail.json
python scripts/temp_mail.py wait-code --state-file /tmp/temp-mail.json --timeout 120

Workflow

1. Create a mailbox with scripts/temp_mail.py create.
2. Reuse the saved state file or raw jwt.
3. Poll with inbox, wait-mail, or wait-code.
4. Use mail --id <mail_id> when you need the full parsed message.

Command Guide

• create: Create a new temporary mailbox. If no domain is given, the script reads /open_api/settings and picks the first default domain.
• settings: Resolve the mailbox address behind a jwt and confirm the token is still valid.
• inbox: List recent mails with parsed subject, from, preview text, links, and candidate codes.
• mail: Fetch one mail by ID and parse the MIME body.
• wait-mail: Poll until at least one mail, or a mail matching --match, arrives.
• wait-code: Poll until a likely verification code is found. Prefer this for OTP and signup flows.

Defaults

• API base: https://mail-api.growvv.xyz
• State file: /tmp/temp-mail.json
• Poll interval: 5 seconds

Implementation Notes

• Read references/api.md when you need the exact endpoints, headers, or response shape.
• If a jwt works for login but /api/settings fails, the address was likely deleted or cleaned up.