Command-line interface (CLI)¶

mailexam-cli is the official command-line tool for the Mailexam REST API. Use it for local debugging, QA, and CI/CD without writing Python or Node.js scripts or long curl pipelines.

Typical flow: your app sends mail via SMTP, and one pipeline command waits for delivery and verifies content:

mailexam email assert --subject "CI check" --contains "Hello"

When to use the CLI

CI/CD — wait and assert with clear exit codes.
Quick checks — list projects, inboxes, and messages from the terminal.
Direct REST API — for full flexibility (creating projects, custom logic), see REST API and Swagger UI.

Installation¶

go installBuild from sourceVerify

Requires Go 1.22+:

go install github.com/mailexam/mailexam-cli/cmd/mailexam@latest

The binary is placed in $GOPATH/bin or $HOME/go/bin. Ensure that directory is on your PATH.

git clone https://github.com/mailexam/mailexam-cli.git
cd mailexam-cli
go build -o mailexam ./cmd/mailexam
sudo mv mailexam /usr/local/bin/   # optional

mailexam version
mailexam --help

Configuration¶

Get your API token from the dashboard. This is not your SMTP password — the token is for REST API access only (see REST API — authentication).

Variable	Description
`MAILEXAM_API_TOKEN`	API token (required)
`MAILEXAM_API_BASE`	Base URL (default: `https://mailexam.io/api/v1`)
`MAILEXAM_PROJECT_UUID`	Default project UUID
`MAILEXAM_INBOX_UUID`	Default inbox UUID

The same values can be passed as flags: --token, --base, --project, --inbox.

Regional domains

Region	`MAILEXAM_API_BASE`
Russia	`https://mailexam.ru/api/v1`
China	`https://mailexam.cn/api/v1`
International	`https://mailexam.io/api/v1`

Example for local use:

export MAILEXAM_API_TOKEN="your_token"
export MAILEXAM_PROJECT_UUID="536a47df-5aad-44d0-8163-a39bb55abe0b"
export MAILEXAM_API_BASE="https://mailexam.io/api/v1"

Secrets in CI/CD

Do not commit the token to your repository. Store MAILEXAM_API_TOKEN in GitLab CI, GitHub Actions, or your pipeline secrets.

CI/CD flow¶

sequenceDiagram
    participant App as Application
    participant SMTP as Mailexam SMTP
    participant CLI as mailexam CLI
    participant API as REST API

    App->>SMTP: sendMail()
    Note over SMTP: Message in sandbox
    CLI->>API: polling GET /email
    API-->>CLI: message found
    CLI->>CLI: assert subject, body
    Note over CLI: exit 0 or 1

Your app sends mail via SMTP (see integration examples).
The pipeline runs mailexam email wait or mailexam email assert.
The CLI polls the API every 2 seconds (default) until timeout.

Command reference¶

Global flags are available for every command: --token, --base, --project, --inbox.

Projects¶

Command	Description
`mailexam project list`	List projects
`mailexam project get UUID`	Get project details

Use --json for raw API JSON output.

mailexam project list
mailexam project list --json
mailexam project get 536a47df-5aad-44d0-8163-a39bb55abe0b

Find the project UUID via project list or in the dashboard.

Inboxes¶

Command	Description
`mailexam inbox list`	List inboxes (requires `--project` or `MAILEXAM_PROJECT_UUID`)
`mailexam inbox get UUID`	Get inbox details

mailexam inbox list --project $MAILEXAM_PROJECT_UUID
mailexam inbox get deab7974-a252-4412-9169-b965116b63cf

Messages¶

Command	Description
`mailexam email list`	List messages in an inbox
`mailexam email get UUID`	Get full message
`mailexam email wait`	Wait for a message matching filters
`mailexam email assert`	Wait and verify content
`mailexam email delete UUID`	Delete a message

For email list, wait, and assert, MAILEXAM_PROJECT_UUID is enough: the CLI picks the default inbox or the first one. Set --inbox or MAILEXAM_INBOX_UUID to target a specific inbox.

List and view¶

mailexam email list
mailexam email list --json

mailexam email get e2f9a506-d766-4935-be11-c413384de020
mailexam email get e2f9a506-d766-4935-be11-c413384de020 --format text
mailexam email get e2f9a506-d766-4935-be11-c413384de020 --format html
mailexam email get e2f9a506-d766-4935-be11-c413384de020 --format uuid

--format options: json (default), text, html, raw, uuid.

Wait for a message (`wait`)¶

At least one filter is required: --subject, --to, or --from.

mailexam email wait --subject "CI check"
mailexam email wait --subject "CI check" --subject-exact
mailexam email wait --to "user@example.com" --timeout 60 --interval 3
mailexam email wait --subject "Code" --format text

Flag	Default	Description
`--subject`	—	Substring in subject
`--subject-exact`	`false`	Exact subject match
`--to`	—	Substring in To field
`--from`	—	Substring in From field
`--timeout`	`30`	Timeout in seconds
`--interval`	`2`	Poll interval in seconds
`--format`	`json`	Output format for the found message

Assertions in tests (`assert`)¶

The main command for pipelines: prints OK and exits with code 0 on success.

mailexam email assert --subject "CI check" --contains "Hello"
mailexam email assert --subject "Code" --contains "123456" --contains "valid"
mailexam email assert --subject "Report" --matches 'total:\s+\d+'
mailexam email assert --subject "File" --require-attachments
mailexam email assert --subject "File" --attachment-count 2

Flag	Description
`--contains`	Body must contain text (repeatable)
`--matches`	Body must match regular expression
`--require-attachments`	Message must have attachments
`--attachment-count`	Exact attachment count

Body checks use the text part first; if missing, HTML is used.

Attachments¶

mailexam email get EMAIL_UUID --format json   # find attachment CIDs
mailexam email attachment download EMAIL_UUID --cid ATTACHMENT_CID -o report.pdf
mailexam email attachment download EMAIL_UUID --cid ATTACHMENT_CID -o -  # stdout

CI/CD examples¶

GitLab CI¶

integration_test:
  stage: test
  image: golang:1.22
  variables:
    MAILEXAM_API_BASE: "https://mailexam.io/api/v1"
    MAILEXAM_PROJECT_UUID: "536a47df-5aad-44d0-8163-a39bb55abe0b"
  before_script:
    - go install github.com/mailexam/mailexam-cli/cmd/mailexam@latest
  script:
    - npm run send-test-email
    - mailexam email assert --subject "CI check" --contains "Hello"
  # MAILEXAM_API_TOKEN — CI/CD Variables (masked)

GitHub Actions¶

- name: Install mailexam CLI
  run: go install github.com/mailexam/mailexam-cli/cmd/mailexam@latest

- name: Send test email
  run: npm run send-test-email

- name: Assert email delivered
  env:
    MAILEXAM_API_TOKEN: ${{ secrets.MAILEXAM_API_TOKEN }}
    MAILEXAM_API_BASE: https://mailexam.io/api/v1
    MAILEXAM_PROJECT_UUID: 536a47df-5aad-44d0-8163-a39bb55abe0b
  run: mailexam email assert --subject "CI check" --contains "Hello"

SMTP credentials (MAILEXAM_LOGIN, MAILEXAM_PASSWORD) are for your app to send mail; the API token is for the CLI only.

Exit codes¶

Code	Meaning
`0`	Success
`1`	Error or failed `assert`
`2`	Authentication error (HTTP 403)
`3`	Timeout waiting for a message

GitLab CI and GitHub Actions fail the job on any non-zero exit code — no wrapper script needed.

Troubleshooting¶

api token is required

Set MAILEXAM_API_TOKEN or pass --token.

Exit code 2 (403)

Token is incomplete or belongs to another account. See REST API — common issues.

Exit code 3 (timeout)

Message not delivered yet — increase --timeout.
Message landed in another project — match SMTP login to MAILEXAM_PROJECT_UUID.
Subject mismatch — verify the exact value or remove --subject-exact.

project or inbox is required

Set MAILEXAM_PROJECT_UUID or --project. For a specific inbox, use --inbox.