https://github.com/btafoya/go-mailtester
Go CLI tool for testing SMTP and IMAP servers — connection, TLS, auth, and delivery diagnostics
https://github.com/btafoya/go-mailtester
cli diagnostics email go golang imap mail-server smtp starttls testing tls
Last synced: 1 day ago
JSON representation
Go CLI tool for testing SMTP and IMAP servers — connection, TLS, auth, and delivery diagnostics
- Host: GitHub
- URL: https://github.com/btafoya/go-mailtester
- Owner: btafoya
- License: mit
- Created: 2026-05-20T20:00:21.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-20T22:20:07.000Z (about 1 month ago)
- Last Synced: 2026-05-21T04:04:34.871Z (about 1 month ago)
- Topics: cli, diagnostics, email, go, golang, imap, mail-server, smtp, starttls, testing, tls
- Language: Go
- Homepage:
- Size: 22.5 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# go-mailtester
[](https://goreportcard.com/report/github.com/btafoya/go-mailtester)
[](LICENSE)
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`](https://github.com/emersion/go-smtp) and [`github.com/emersion/go-imap`](https://github.com/emersion/go-imap) libraries.
## Install
The fastest way to get started:
```bash
go install github.com/btafoya/go-mailtester/cmd/mailtester@latest
```
Or if you prefer to build from source:
```bash
git clone https://github.com/btafoya/go-mailtester.git
cd go-mailtester
go build ./cmd/mailtester
```
### AI Agent Skill
You can also install go-mailtester as a skill for Claude Code or other compatible agents:
```bash
npx skills add btafoya/go-mailtester
```
Privacy-conscious? Disable telemetry:
```bash
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:**
```bash
mailtester -host smtp.gmail.com -port 587 -mode connection
```
**Run the full SMTP diagnostic suite:**
```bash
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):**
```bash
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:**
```bash
mailtester -host imap.gmail.com -port 993 -tls -mode imap-connection
```
**Run the full IMAP diagnostic suite:**
```bash
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.
| Mode | What it tests |
|------|---------------|
| `connection` | TCP connectivity, EHLO, and server extension discovery (STARTTLS, AUTH, SIZE, etc.) |
| `starttls` | Plaintext dial → check STARTTLS extension → upgrade to TLS → inspect TLS state |
| `ssl` | Implicit TLS (port 465): `tls.Dial` → inspect TLS state → EHLO → optional auth |
| `auth` | Dial with selected security, EHLO, then authenticate with PLAIN or LOGIN |
| `send` | Full manual pipeline: `MAIL FROM` → `RCPT TO` → `DATA` → message body → `QUIT` |
| `sendmail` | High-level `smtp.SendMail()` convenience function |
| `sendmailtls` | High-level `smtp.SendMailTLS()` convenience function (implicit TLS) |
| `raw` | Raw `net/textproto` SMTP session, bypassing the library entirely |
| `imap-connection` | Plaintext IMAP dial + greeting + capability listing |
| `imap-starttls` | IMAP STARTTLS upgrade + capability listing |
| `imap-ssl` | Implicit TLS IMAP (port 993) + greeting + capabilities + optional auth |
| `imap-auth` | IMAP connection + authenticate with PLAIN or LOGIN |
| `imap-list` | List all mailboxes |
| `imap-status` | Select a mailbox and report message count, UIDNext, UIDValidity |
| `imap-fetch` | Fetch the first message envelope and flags |
| `all` | Sequentially runs all SMTP tests |
| `imap-all` | Sequentially runs all IMAP tests |
## 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:**
```bash
mailtester -host smtp.example.com -port 25 -mode connection
```
**Test STARTTLS negotiation:**
```bash
mailtester -host smtp.example.com -port 587 -mode starttls
```
**Test authentication:**
```bash
mailtester -host smtp.example.com -port 587 -starttls \
-user alice -pass secret -mode auth
```
**Send a single test email via STARTTLS:**
```bash
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):**
```bash
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:**
```bash
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):**
```bash
mailtester -host mail.local -port 465 -tls -skip-verify \
-from test@local -to admin@local -mode connection
```
**Custom timeout:**
```bash
mailtester -host slow.server.com -timeout 60s -mode connection
```
**Raw SMTP session (see server responses line-by-line):**
```bash
mailtester -host smtp.example.com -port 25 -mode raw
```
**Test IMAP connectivity:**
```bash
mailtester -host imap.example.com -port 993 -tls -mode imap-connection
```
**Test IMAP STARTTLS:**
```bash
mailtester -host imap.example.com -port 143 -mode imap-starttls
```
**Test IMAP authentication:**
```bash
mailtester -host imap.example.com -port 993 -tls \
-user alice -pass secret -mode imap-auth
```
**List IMAP mailboxes:**
```bash
mailtester -host imap.example.com -port 993 -tls \
-user alice -pass secret -mode imap-list
```
**Check IMAP mailbox status:**
```bash
mailtester -host imap.example.com -port 993 -tls \
-user alice -pass secret -mode imap-status -mailbox INBOX
```
**Fetch first IMAP message:**
```bash
mailtester -host imap.example.com -port 993 -tls \
-user alice -pass secret -mode imap-fetch -mailbox INBOX
```
**Full IMAP diagnostic suite:**
```bash
mailtester -host imap.example.com -port 993 -tls \
-user alice -pass secret -mode imap-all
```
## Dependencies
- [`github.com/emersion/go-smtp`](https://github.com/emersion/go-smtp)
- [`github.com/emersion/go-imap`](https://github.com/emersion/go-imap)
- [`github.com/emersion/go-sasl`](https://github.com/emersion/go-sasl) (transitive)
## License
[MIT](LICENSE)