go-mailtester

go-mailtester

Tired of guessing why your emails aren't sending? go-mailtester is a Go CLI tool that diagnoses SMTP and IMAP servers layer by layer, so you know exactly what's broken.

For SMTP, it tests everything from raw TCP connections up through STARTTLS negotiation, implicit TLS, authentication, and actually sending messages. For IMAP, it checks connections, TLS, authentication, mailbox listing, status, and message fetching.

Built on top of the excellent github.com/emersion/go-smtp and github.com/emersion/go-imap libraries.

Install

The fastest way to get started:

go install github.com/btafoya/go-mailtester@latest

Or if you prefer to build from source:

git clone https://github.com/btafoya/go-mailtester.git
cd go-mailtester
go build -o mailtester .

AI Agent Skill

You can also install go-mailtester as a skill for Claude Code or other compatible agents:

npx skills add btafoya/go-mailtester

Privacy-conscious? Disable telemetry:

DISABLE_TELEMETRY=1 npx skills add btafoya/go-mailtester

After installing, just invoke /mailtester or let it trigger automatically when you're debugging email issues.

Quick Start

Check if a server is reachable:

mailtester -host smtp.gmail.com -port 587 -mode connection

Run the full SMTP diagnostic suite:

mailtester -host smtp.gmail.com -port 587 -starttls \
  -from me@example.com -to you@example.net \
  -user me -pass secret -mode all

Test implicit TLS (port 465):

mailtester -host smtp.gmail.com -port 465 -tls \
  -from me@example.com -to you@example.net \
  -user me -pass secret -mode send

Check IMAP connectivity:

mailtester -host imap.gmail.com -port 993 -tls -mode imap-connection

Run the full IMAP diagnostic suite:

mailtester -host imap.gmail.com -port 993 -tls \
  -user me -pass secret -mode imap-all

Test Modes

Use -mode to pick which layer you want to exercise. The default is all (SMTP tests only) — use imap-all for IMAP.

Flags

-host        SMTP/IMAP server hostname (default: localhost)
-port        SMTP/IMAP server port (default: 25)
-from        Sender email address
-to          Recipient(s), comma-separated
-subject     Email subject (default: "SMTP Test")
-body        Email body (default: "This is a test email from go-mailtester.")
-user        SMTP/IMAP username
-pass        SMTP/IMAP password
-auth        Auth mechanism: plain, login, none (default: plain)
-tls         Use implicit TLS (port 465 for SMTP, 993 for IMAP)
-starttls    Use STARTTLS
-skip-verify Skip TLS certificate verification
-timeout     Connection timeout (default: 30s)
-helo        EHLO/HELO hostname (default: go-mailtester)
-mode        Test mode (default: all)
-mailbox     IMAP mailbox to test (default: INBOX)

Examples

Test connectivity only:

mailtester -host smtp.example.com -port 25 -mode connection

Test STARTTLS negotiation:

mailtester -host smtp.example.com -port 587 -mode starttls

Test authentication:

mailtester -host smtp.example.com -port 587 -starttls \
  -user alice -pass secret -mode auth

Send a single test email via STARTTLS:

mailtester -host smtp.example.com -port 587 -starttls \
  -from alice@example.com -to bob@example.net \
  -user alice -pass secret -mode send

Send via implicit TLS (port 465):

mailtester -host smtp.example.com -port 465 -tls \
  -from alice@example.com -to bob@example.net \
  -user alice -pass secret -mode send

Use LOGIN auth instead of PLAIN:

mailtester -host smtp.example.com -port 587 -starttls -auth login \
  -from alice@example.com -to bob@example.net \
  -user alice -pass secret -mode send

Skip certificate verification (self-signed certs):

mailtester -host mail.local -port 465 -tls -skip-verify \
  -from test@local -to admin@local -mode connection

Custom timeout:

mailtester -host slow.server.com -timeout 60s -mode connection

Raw SMTP session (see server responses line-by-line):

mailtester -host smtp.example.com -port 25 -mode raw

Test IMAP connectivity:

mailtester -host imap.example.com -port 993 -tls -mode imap-connection

Test IMAP STARTTLS:

mailtester -host imap.example.com -port 143 -mode imap-starttls

Test IMAP authentication:

mailtester -host imap.example.com -port 993 -tls \
  -user alice -pass secret -mode imap-auth

List IMAP mailboxes:

mailtester -host imap.example.com -port 993 -tls \
  -user alice -pass secret -mode imap-list

Check IMAP mailbox status:

mailtester -host imap.example.com -port 993 -tls \
  -user alice -pass secret -mode imap-status -mailbox INBOX

Fetch first IMAP message:

mailtester -host imap.example.com -port 993 -tls \
  -user alice -pass secret -mode imap-fetch -mailbox INBOX

Full IMAP diagnostic suite:

mailtester -host imap.example.com -port 993 -tls \
  -user alice -pass secret -mode imap-all

Dependencies

• github.com/emersion/go-smtp
• github.com/emersion/go-imap
• github.com/emersion/go-sasl (transitive)

License

MIT