Non-interactive mail service REST API CLI for humans and AI agents.
- Features
- Requirements
- Setup
- Usage
- Development
- Testing
- Troubleshooting
- Security
- Configuration
- Operations
- Commands
- Exit codes
- Support
- Links
- License
Mailctl uses the authenticated Mail REST API for every mail operation. It emits JSON and does not prompt for input. It supports inbox, message, attachment, search, send, reply, retry, and delete commands. It requires confirmation for uncertain delivery retries and destructive requests.
Use Node.js 26 or later and npm 12 or later. Use an account with access to the Mail REST API.
Install the public package:
npm install --global @eliware/mailctl
Set MAIL_API_URL and MAIL_API_TOKEN in mailctl's local configuration.
Set MAIL_OWNER_ADDRESS in the calling project's local configuration.
Use environment variables when a deployment supplies settings that way.
Run help and version checks:
mailctl --help
mailctl --version
Read messages and check service status:
mailctl inbox
mailctl read MESSAGE_ID
mailctl sent
mailctl health
Send JSON requests through standard input, inline input, or --input FILE.
See the usage guide for command details.
See examples for example files.
See local documentation for all guides.
See release notes for published changes.
Install locked dependencies and run validation:
npm ci
npm test
npm run lint
npm run pack
Read development and API requirements. Read integration test instructions before live tests.
npm test runs lint, format, audit, package, convention, and Jest checks.
The test suite requires 100 percent statement, branch, function, and line coverage.
Live tests need a disposable Mail service endpoint.
Check MAIL_API_URL, MAIL_API_TOKEN, and MAIL_OWNER_ADDRESS when a request fails.
Run mailctl health to check API readiness.
Read the troubleshooting guide for common errors.
Keep API tokens in local configuration or secret injection. Do not put tokens in URLs, logs, examples, or issue reports. Mailctl sends requests only to the configured Mail API.
| Variable | Required | Default | Purpose |
|---|---|---|---|
MAIL_API_URL |
Yes | None | Base URL for the Mail REST API. |
MAIL_API_TOKEN |
Yes | None | Bearer token for API access. |
MAIL_OWNER_ADDRESS |
Mailbox commands | None | Mailbox scope for the caller. |
MAIL_OUTBOUND_STALE_DELIVERY_MS |
No | 300000 | Age threshold for stale delivery status. |
Environment values take precedence over local configuration files. Missing owner scope fails closed.
Mailctl makes no direct database, RabbitMQ, or file storage connections.
The Mail service owns message data and attachments.
The vMAJOR.MINOR.PATCH tag workflow validates and publishes the package to npm.
Publication requires the repository's npm provenance setup.
Publication does not deploy the Mail service.
| Command | Purpose |
|---|---|
inbox, list, headers, read |
Read inbound messages. |
sent, sent-read, outbound-status |
Read outbound messages and delivery status. |
search, thread, domains, health |
Search or inspect service data. |
attachments, save-attachments, save-sent-attachments |
Read and save attachments. |
send, reply, reply-all, forward |
Submit outbound messages. |
retry, retry-uncertain, cancel |
Manage outbound delivery. |
delete |
Soft-delete messages after confirmation. |
retry-uncertain requires confirmation that the recipient may receive a duplicate.
delete requires explicit JSON confirmation or a dry-run request.
Every command emits one JSON result. Errors use one JSON object on stderr.
Exit code 0 means the command succeeded.
Exit code 1 means the command or API request failed.
mailctl --help and mailctl --version return exit code 0.
For help, questions, or to chat with the author and community, visit:
