SDKs & CLI

MailAfrica CLI

The official command-line client for MailAfrica. Manage inbound addresses, webhooks, and sending domains, and drive sandbox, wallet, SMS, compliance, and AI auto-reply — all from your terminal.

Overview

The MailAfrica CLI is a user-side terminal client for the MailAfrica API. It covers the whole user-facing surface — inbound addresses and domains, webhooks, transactional sending from verified sending domains, sandbox testing, TZS wallet billing, SMS notifications, compliance, and the AI auto-responder — with no admin or operator commands. It is built on Go and spf13/cobra, and every list/send command can emit JSON for scripting.

Source: github.com/MailAfrica/CLI · Module: github.com/MailAfrica/MailAfrica-CLI · Go 1.25+.

Install

bash

go install github.com/MailAfrica/MailAfrica-CLI/cmd/mailafrica@latest

This builds mailafrica into $GOBIN (defaults to $GOPATH/bin). Alternatively, make build produces bin/mailafrica. Verify the install:

bash

mailafrica version
# mailafrica dev

Configure

Settings are resolved in precedence order: flags, then environment variables, then the config file at ~/.config/mailafrica/config.json (or $XDG_CONFIG_HOME/mailafrica/config.json). The config file is written atomically and readable only by your user (chmod 0600).

Setting	Flag	Environment	Config file
API base URL	`--api-url`	`MAILAFRICA_API_URL`	`api-url`
API key	`--api-key`	`MAILAFRICA_API_KEY`	`api-key`

Use mailafrica config path to print the config location. mailafrica config set api-url api.mailafrica.online points at a different base URL (only api-url is settable; store credentials with apikeys create --save or auth login). mailafrica config get api-key confirms a key is present — the key itself is never printed.

Authenticate

Two paths, both handled automatically on every request:

Interactive session — mailafrica auth login --identifier you@example.com. The CLI stores a refresh token in the config file, mints a JWT in-process, and auto-refreshes the token exactly once on 401.
API key — create one with mailafrica apikeys create --name prod --save, or set MAILAFRICA_API_KEY=MAIL_... for scripted/CI use. The CLI sends it as X-API-Key on every request.

bash

# interactive (development)
mailafrica auth login --identifier you@example.com

# scripted / CI
export MAILAFRICA_API_KEY=MAIL_...

Global flags

Flag	Purpose
`--api-url`	Override the API base URL for this invocation.
`--api-key`	API key for this invocation (overrides env and config).
`--json`	Render output as JSON instead of tables.
`--debug`	Print the request/response exchange to stderr, with secrets redacted.
`-v`, `--version`	Print the version.

Quick start

bash

# account
mailafrica apikeys list
mailafrica wallet balance

# receive: inbound address -> webhook
mailafrica inbound address create --local-part support
mailafrica webhook create --address-id 1 --url https://you.example/hooks/mail
mailafrica inbound message list --address-id 1

# send from your own signed domain
mailafrica domain add --domain mail.example.com      # publish DKIM/SPF/DMARC
mailafrica domain verify 1
mailafrica send email --to you@corp.com --subject "Hi" --text-body "hello"
mailafrica send batch --to-file recipients.txt --subject "Bulk"

# sandbox: test SMTP flows without paying
mailafrica sandbox smtp
mailafrica sandbox message list

# AI auto-responder on an address
mailafrica agent config 1 --mode auto --persona "You are our sales rep..."
mailafrica agent draft 1 --subject "Pricing?" --text-body "How much?"

Command reference

Bare mailafrica prints help; every group supports mailafrica <group> --help. --json is available on every list and send command.

Account & API keys

Command	Purpose	Key flags
`auth register`	Create an account and start a session.	`--email` / `--phone` (one required), `--name` (required), `--company`, `--password` (prompted)
`auth login`	Log in and store a refresh token.	`--identifier` (required), `--password` (prompted)
`auth refresh`	Rotate the stored refresh token now.	—
`auth logout`	Forget stored credentials.	—
`auth me`	Show the authenticated user.	—
`auth update`	Update your name and/or company.	`--name`, `--company`
`auth verify email`	Confirm email with a verification token.	`--token` (required)
`auth verify phone`	Confirm phone with a 6-digit code.	`--code` (required)
`auth verify resend-email`	Re-send the email verification link.	—
`auth verify resend-phone`	Re-send the phone OTP.	—
`apikeys create`	Create a `MAIL_...` key, shown exactly once.	`--name` (required), `--scopes` (default `full`), `--expires-at`, `--save`
`apikeys list`	List active API keys.	—
`apikeys revoke <id>`	Revoke an API key.	—
`config path`	Print the config file location.	—
`config get <key>`	Show a config value (`api-url` prints; secrets report set/not-set).	—
`config set <key> <value>`	Set a config value (only `api-url` is settable).	—

Inbound email

Command	Purpose	Key flags
`inbound address create`	Create a receiving address.	`--local-part` (required), `--label`, `--domain-id`
`inbound address list`	List receiving addresses.	—
`inbound address delete <id>`	Delete a receiving address.	—
`inbound domain add`	Add a custom inbound domain and get DNS records.	`--domain` (required)
`inbound domain list`	List custom inbound domains and verification status.	—
`inbound domain verify <id>`	Re-check DNS and mark verified when ready.	—
`inbound domain delete <id>`	Delete a custom inbound domain.	—
`inbound message list`	List received messages.	`--address-id` (required), `--unread`, `--page`, `--per-page`
`inbound message get <id>`	Show one received message including body.	—
`inbound message read <id>`	Mark a received message as read.	—

Webhooks

Command	Purpose	Key flags
`webhook create`	Wire delivery callbacks to a receiving address.	`--address-id` (required), `--url` (required), `--secret` (optional; random if omitted)
`webhook list`	List webhooks for an address.	`--address-id` (required)
`webhook delete <id>`	Delete a webhook.	—
`webhook deliveries <id>`	Show recent delivery attempts.	—
`webhook test <id>`	Ask MailAfrica to POST a test ping to the webhook URL.	—
`webhook trigger <message-id>`	Manually dispatch the delivery notification for a received message.	—

Webhook secrets sign the X-Signature header and are returned in full only once, at creation — store them when you create a webhook.

Sending & domains

Command	Purpose	Key flags
`domain add`	Add a verified sending domain and get DNS records.	`--domain` (required), `--from-local-part` (default `noreply`)
`domain list`	List verified sending domains and status.	—
`domain verify <id>`	Re-check DKIM/SPF/DMARC records.	—
`domain delete <id>`	Delete a sending domain.	—
`domain sender create`	Create a new From identity.	`--domain-id` (required), `--local-part` (required)
`domain sender list`	List all From identities.	—
`domain sender delete <id>`	Delete a From identity.	—
`send email`	Send one email to up to 50 recipients.	send flags below
`send batch`	Send the same email to many recipients; server-side chunking with suppression filtering.	`--to-file` (one address per line)
`send list`	List outbound (billed) emails.	`--page`, `--per-page`
`send get <id>`	Show one outbound email and per-recipient statuses.	—
`send template create`	Create a template.	`--name` (required), `--subject`, `--html-body`/`--html-file`, `--text-body`/`--text-file`
`send template list`	List templates.	—
`send template update <id>`	Replace a template (full replace).	same as create
`send template delete <id>`	Delete a template.	—

Common send flags

Recipients — --to (repeatable or comma-separated), --cc, --bcc; send batch adds --to-file. The API accepts at most 50 recipients per call.
Content — --subject, --html-body / --html-file, --text-body / --text-file, or --template-id (inline bodies override the template).
Template variables — --var name=value, repeatable.
From — --from-domain-id and/or --from-address to send from a verified domain; without a domain, --from-address may be a local part on the platform domain (e.g. food@mailafrica.online), otherwise the platform sender is used.
Attachments — --attach <file>, repeatable (base64-embedded).

Sandbox

Command	Purpose	Key flags
`sandbox credential create`	Create sandbox API credentials (secret shown once).	`--scopes`
`sandbox credential list`	List sandbox credentials (masked).	—
`sandbox credential revoke <id>`	Revoke a sandbox credential.	—
`sandbox smtp`	Show your sandbox SMTP server credentials.	—
`sandbox smtp-regenerate`	Rotate the SMTP password (old one stops working).	—
`sandbox message list`	List captured sandbox messages.	`--page`, `--per-page`
`sandbox message get <id>`	Show one captured sandbox message.	—
`sandbox message clear`	Delete all captured sandbox messages.	—

Wallet

Command	Purpose	Key flags
`wallet balance`	Show the current wallet balance (TZS).	—
`wallet topup`	Top up the wallet.	`--amount` (TZS, min 2000, required), `--via phone` (USSD push to a verified phone)

Compliance & SMS

Command	Purpose	Key flags
`compliance profile`	Show the compliance profile (auto-creates on first read).	—
`compliance update`	Update compliance settings.	`--pdpc`, `--certificate-number`, `--registered-at` (YYYY-MM-DD), `--retention-days`
`compliance audit`	Point-in-time audit export (profile, counts, generated_at).	—
`sms notification create`	Get a short SMS when an inbound address receives mail.	`--address-id` (required), `--phone` (required), `--sendafrica-key` (required, shown once)
`sms notification list`	List SMS notifications.	`--address-id` (required)
`sms notification revoke <id>`	Deactivate an SMS notification.	—
`sms notification deliveries <id>`	Delivery history for one notification.	—

AI agent

Command	Purpose	Key flags
`agent list`	Which addresses have auto-reply configured and their modes.	—
`agent config <address-id>`	Read (no flags) or update an address's auto-reply config.	`--mode` (`off`/`draft`/`auto`), `--persona`, `--enabled`, `--reply-from-domain-id`, `--reply-from-address`
`agent draft <address-id>`	Preview a reply draft the agent would send (never sends).	`--subject`, `--text-body`

agent config is the shared source of truth with the web app. auto mode reads incoming mail and replies itself; reply-from requires a verified sending domain.

Security

Credentials — refresh tokens and API keys live only in the owner-readable config file; commands report set/not set, never values.
One-time secrets — API keys, webhook secrets, SMS keys, and sandbox credentials are shown in plaintext exactly once at creation.
`--debug` redaction — request/response dumps redact password, secret, token, api_key, and credential fields.
Payments — top-ups flow through hosted checkout or USSD push; the CLI never handles card or mobile-money details.

Next steps

Build an end-to-end receiving flow: inbound addresses → webhooks.
Send from a verified domain with the sending domains and outbound guides.
Script against the API directly with the Go SDK or the raw REST reference.