mailtrap Mailtrap CLI Skill
The mailtrap CLI is the official command-line interface for the Mailtrap email platform.
It covers transactional/bulk email sending, sandbox testing, domain management, templates,
contacts, statistics, and account administration.
Authentication
The CLI requires an API token. Set it via any of these (highest priority first):
--api-tokenflag on any commandMAILTRAP_API_TOKENenvironment variable~/.mailtrap.yamlconfig file (api-tokenkey)
Most commands also require an account ID, set the same way (--account-id, MAILTRAP_ACCOUNT_ID, or account-id in config).
Run mailtrap configure --api-token <token> to auto-detect the account ID and save both to ~/.mailtrap.yaml.
Non-Interactive Mode
The CLI never prompts for input. All required values must be supplied as flags. If a required flag is missing, the command exits with an error listing the missing flag.
Output Formats
Use -o / --output to control output format:
table(default) — human-readable tablejson— machine-readable JSONtext— plain text
For scripting and piping, always use --output json.
Key Conventions
- Email address format:
"email@example.com"or"Name <email@example.com>" - Repeated flags: flags like
--to,--cc,--bcc,--domain-idscan be specified multiple times - Batch operations: use
--file path/to/payload.jsonwith a JSON array of email objects - Config priority: CLI flags > environment variables > config file
- Exit codes: 0 on success, 1 on error (with descriptive message)
- API base: most requests go to
https://mailtrap.io/api/accounts/{account-id}/.... Several groups do not and take no--account-id:inbound(/api/inbound/...),company-info(/api/domains/{domain-id}/company_info),tracking-opt-outs(/api/tracking_opt_outs),email-campaigns(/api/email_campaigns) andorganizations(/api/organizations/...).sendandsandbox-sendgo to their own hosts entirely.
Command Groups
| Group | Purpose | Reference |
|---|---|---|
send |
Transactional & bulk email sending | sending.md |
domains |
Sending domain management | domains.md |
company-info |
Sending domain company info for compliance verification | domains.md |
templates |
Email template CRUD | templates.md |
stats |
Aggregated sending statistics | email-logs.md |
email-logs |
Individual email log lookup | email-logs.md |
inbound |
Inbound email folders, inboxes, messages & threads | inbound.md |
contacts |
Contact management & import/export | contacts.md |
contact-lists |
Contact list CRUD | contacts.md |
contact-fields |
Custom contact fields | contacts.md |
sandbox-send |
Sandbox email testing | sandbox.md |
projects |
Sandbox project management | sandbox.md |
sandboxes |
Sandbox management | sandbox.md |
messages |
Sandbox message inspection | sandbox.md |
attachments |
Sandbox attachment retrieval | sandbox.md |
accounts |
Account listing | accounts.md |
account-access |
Account access management | accounts.md |
tokens |
API token management | accounts.md |
permissions |
Permission management | accounts.md |
billing |
Usage information | accounts.md |
organizations |
Sub-account management | accounts.md |
suppressions |
Suppression list management | domains.md |
tracking-opt-outs |
Open and click tracking opt-outs | domains.md |
Gotchas
sandbox-sendrequires--sandbox-id— this is separate from the productionsendcommands- Batch commands require a
--fileflag pointing to a valid JSON file; they do not accept inline JSON - Stats commands always require
--start-dateand--end-date - Message inspection commands (
messages html,messages raw, etc.) require both--sandbox-idand--id - The
configurecommand validates the token against the API before saving - Domain verification is handled through the Mailtrap web dashboard, not the CLI