diff --git a/docs/config-examples/ews-basic.yaml b/docs/config-examples/ews-basic.yaml new file mode 100644 index 0000000..26c7481 --- /dev/null +++ b/docs/config-examples/ews-basic.yaml @@ -0,0 +1,12 @@ +# EWS — Basic authentication (legacy; requires basic auth enabled on Exchange) +# Usage: gomailtest ews testconnect|testauth|getfolder --config ews-basic.yaml +host: mail.example.com +port: 443 +username: user@example.com +password: change-me +authmethod: Basic +# ewspath: /EWS/Exchange.asmx # default; override for non-standard installations +# mailbox: targetuser@example.com # set for mailbox impersonation +# skipverify: true # skip TLS certificate verification (testing only) +# tlsversion: "1.3" # minimum TLS version; default is 1.2 +# proxy: http://proxy.example.com:8080 diff --git a/docs/config-examples/ews-bearer.yaml b/docs/config-examples/ews-bearer.yaml new file mode 100644 index 0000000..2d33f0c --- /dev/null +++ b/docs/config-examples/ews-bearer.yaml @@ -0,0 +1,12 @@ +# EWS — OAuth2 Bearer token auth with mailbox impersonation +# Usage: gomailtest ews testauth|getfolder --config ews-bearer.yaml +host: mail.example.com +port: 443 +username: serviceaccount@example.com +accesstoken: eyJ0eXAiOiJKV1Qi...your-oauth2-token-here +authmethod: Bearer +# mailbox is required when using a service account to access another user's mailbox +mailbox: targetuser@example.com +# ewspath: /EWS/Exchange.asmx # default; override for non-standard installations +# skipverify: true # skip TLS certificate verification (testing only) +# proxy: http://proxy.example.com:8080 diff --git a/docs/config-examples/ews-ntlm.yaml b/docs/config-examples/ews-ntlm.yaml new file mode 100644 index 0000000..748e2b4 --- /dev/null +++ b/docs/config-examples/ews-ntlm.yaml @@ -0,0 +1,14 @@ +# EWS — NTLM auth for on-premises Exchange with Active Directory +# Usage: gomailtest ews testconnect|testauth|getfolder|autodiscover --config ews-ntlm.yaml +host: mail.contoso.com +port: 443 +username: CONTOSO\user +password: change-me +authmethod: NTLM +# domain: CONTOSO # alternative to embedding domain in username (DOMAIN\user form) +# ewspath: /EWS/Exchange.asmx # default; override for non-standard installations +# autodiscoverpath: /autodiscover/autodiscover.svc # used by the autodiscover action +# mailbox: targetuser@contoso.com # set for mailbox impersonation (service account scenario) +# skipverify: true # skip TLS certificate verification (testing only) +# tlsversion: "1.3" # minimum TLS version; default is 1.2 +# proxy: http://proxy.example.com:8080 diff --git a/docs/config-examples/imap-exportmessages.yaml b/docs/config-examples/imap-exportmessages.yaml new file mode 100644 index 0000000..5728478 --- /dev/null +++ b/docs/config-examples/imap-exportmessages.yaml @@ -0,0 +1,16 @@ +# IMAP — export matching messages as .eml files +# Usage: gomailtest imap exportmessages --config imap-exportmessages.yaml +host: imap.example.com +port: 993 +imaps: true +username: user@example.com +password: change-me +# Search filters — at least one of subject or messageid is typically provided +subject: "Invoice" +# messageid: "" +mailbox: INBOX +count: 25 +exportdir: C:\exports +# proxy: http://proxy.example.com:8080 +# maxretries: 3 +# retrydelay: 2000 diff --git a/docs/config-examples/imap-imaps.yaml b/docs/config-examples/imap-imaps.yaml new file mode 100644 index 0000000..71fee6c --- /dev/null +++ b/docs/config-examples/imap-imaps.yaml @@ -0,0 +1,19 @@ +# IMAP — implicit TLS / IMAPS (port 993): Gmail, Microsoft 365, Yahoo, iCloud +# Usage: gomailtest imap testconnect|testauth|listfolders --config imap-imaps.yaml +host: imap.example.com +port: 993 +imaps: true +username: user@example.com +password: change-me +# authmethod: auto # auto-selects: PLAIN or LOGIN +# skipverify: true # skip TLS certificate verification (testing only) +# tlsversion: "1.3" # minimum TLS version; default is 1.2 +# proxy: http://proxy.example.com:8080 +# maxretries: 3 +# retrydelay: 2000 + +# Provider quick-reference: +# Gmail: host: imap.gmail.com port: 993 +# Microsoft 365: host: outlook.office365.com port: 993 +# Yahoo: host: imap.mail.yahoo.com port: 993 +# iCloud: host: imap.mail.me.com port: 993 diff --git a/docs/config-examples/imap-oauth2.yaml b/docs/config-examples/imap-oauth2.yaml new file mode 100644 index 0000000..b92a847 --- /dev/null +++ b/docs/config-examples/imap-oauth2.yaml @@ -0,0 +1,10 @@ +# IMAP — XOAUTH2 token auth (Microsoft 365 / Google Workspace) +# Usage: gomailtest imap testauth|listfolders --config imap-oauth2.yaml +host: imap.gmail.com +port: 993 +imaps: true +username: user@example.com +accesstoken: ya29.your-oauth2-token-here +authmethod: XOAUTH2 +# skipverify: true # skip TLS certificate verification (testing only) +# proxy: http://proxy.example.com:8080 diff --git a/docs/config-examples/imap-starttls.yaml b/docs/config-examples/imap-starttls.yaml new file mode 100644 index 0000000..987e37f --- /dev/null +++ b/docs/config-examples/imap-starttls.yaml @@ -0,0 +1,13 @@ +# IMAP — explicit TLS via STARTTLS (port 143) +# Usage: gomailtest imap testconnect|testauth|listfolders --config imap-starttls.yaml +host: imap.example.com +port: 143 +starttls: true +username: user@example.com +password: change-me +# authmethod: auto # auto-selects: PLAIN or LOGIN +# skipverify: true # skip TLS certificate verification (testing only) +# tlsversion: "1.3" # minimum TLS version; default is 1.2 +# proxy: http://proxy.example.com:8080 +# maxretries: 3 +# retrydelay: 2000 diff --git a/docs/config-examples/jmap-basic.yaml b/docs/config-examples/jmap-basic.yaml new file mode 100644 index 0000000..f162f70 --- /dev/null +++ b/docs/config-examples/jmap-basic.yaml @@ -0,0 +1,9 @@ +# JMAP — Basic (password) auth for self-hosted JMAP servers (Cyrus IMAP, Apache James) +# Usage: gomailtest jmap testconnect|testauth|getmailboxes --config jmap-basic.yaml +host: jmap.example.com +port: 443 +username: user@example.com +password: change-me +authmethod: basic +# skipverify: true # skip TLS certificate verification — useful for self-signed certs +# address: 192.168.1.10 # connect to this IP instead of --host (host still used for TLS SNI) diff --git a/docs/config-examples/jmap-bearer.yaml b/docs/config-examples/jmap-bearer.yaml new file mode 100644 index 0000000..dc61243 --- /dev/null +++ b/docs/config-examples/jmap-bearer.yaml @@ -0,0 +1,11 @@ +# JMAP — Bearer token auth (Fastmail and similar providers) +# Usage: gomailtest jmap testconnect|testauth|getmailboxes --config jmap-bearer.yaml +host: jmap.fastmail.com +port: 443 +username: user@fastmail.com +accesstoken: fmu1-xxxxxxxx-your-api-token-here +authmethod: bearer +# skipverify: true # skip TLS certificate verification (testing only) + +# Getting a Fastmail API token: +# Settings → Password & Security → API Tokens → New Token diff --git a/docs/config-examples/msgraph-bearer.yaml b/docs/config-examples/msgraph-bearer.yaml new file mode 100644 index 0000000..771df3e --- /dev/null +++ b/docs/config-examples/msgraph-bearer.yaml @@ -0,0 +1,8 @@ +# Microsoft Graph — pre-obtained Bearer token auth +# Usage: gomailtest msgraph testconnect|testauth|getevents|getinbox --config msgraph-bearer.yaml +# Useful when a token has already been obtained outside gomailtest (e.g. via az cli or custom OAuth flow). +tenantid: 00000000-0000-0000-0000-000000000000 +clientid: 00000000-0000-0000-0000-000000000000 +bearertoken: eyJ0eXAiOiJKV1Qi...your-bearer-token-here +mailbox: user@example.com +# proxy: http://proxy.example.com:8080 diff --git a/docs/config-examples/msgraph-pfx.yaml b/docs/config-examples/msgraph-pfx.yaml new file mode 100644 index 0000000..4a76518 --- /dev/null +++ b/docs/config-examples/msgraph-pfx.yaml @@ -0,0 +1,10 @@ +# Microsoft Graph — PFX certificate file auth +# Usage: gomailtest msgraph testconnect|testauth|getevents|getinbox --config msgraph-pfx.yaml +tenantid: 00000000-0000-0000-0000-000000000000 +clientid: 00000000-0000-0000-0000-000000000000 +pfx: C:\Certs\app-cert.pfx +pfxpass: certificate-password +mailbox: user@example.com +# proxy: http://proxy.example.com:8080 +# maxretries: 3 +# retrydelay: 2000 diff --git a/docs/config-examples/msgraph-secret.yaml b/docs/config-examples/msgraph-secret.yaml new file mode 100644 index 0000000..5f2ea29 --- /dev/null +++ b/docs/config-examples/msgraph-secret.yaml @@ -0,0 +1,10 @@ +# Microsoft Graph — client secret auth (most common app registration scenario) +# Usage: gomailtest msgraph testconnect|testauth|getevents|getinbox|getschedule --config msgraph-secret.yaml +tenantid: 00000000-0000-0000-0000-000000000000 +clientid: 00000000-0000-0000-0000-000000000000 +secret: your-client-secret-here +mailbox: user@example.com +# proxy: http://proxy.example.com:8080 +# maxretries: 3 +# retrydelay: 2000 +# count: 3 # number of items for getevents / getinbox (default 3) diff --git a/docs/config-examples/msgraph-sendmail.yaml b/docs/config-examples/msgraph-sendmail.yaml new file mode 100644 index 0000000..0b67ab2 --- /dev/null +++ b/docs/config-examples/msgraph-sendmail.yaml @@ -0,0 +1,22 @@ +# Microsoft Graph — full sendmail scenario: HTML body, CC/BCC, attachments, inline images, headers +# Usage: gomailtest msgraph sendmail --config msgraph-sendmail.yaml +tenantid: 00000000-0000-0000-0000-000000000000 +clientid: 00000000-0000-0000-0000-000000000000 +secret: your-client-secret-here +mailbox: sender@example.com +to: recipient@example.com +# cc: cc@example.com +# bcc: bcc@example.com +subject: "Test Email from gomailtest" +body: "Plain-text fallback for clients that do not render HTML." +bodyHTML: "

Hello! This is a test message from gomailtest.

" +# attachments: C:\Reports\report.pdf,C:\Reports\data.csv +# inline-attachments: C:\Branding\logo.png # embedded inline; reference as cid:logo.png in bodyHTML +# body-template: C:\Templates\email.html # path to HTML template file (alternative to bodyHTML) +# Graph only passes through X- prefixed custom headers; standard RFC headers are controlled by the API +header: + - "X-Custom-Header: example-value" +# priority: high # high | normal (default) | low +# proxy: http://proxy.example.com:8080 +# maxretries: 3 +# retrydelay: 2000 diff --git a/docs/config-examples/msgraph-thumbprint.yaml b/docs/config-examples/msgraph-thumbprint.yaml new file mode 100644 index 0000000..4200d1d --- /dev/null +++ b/docs/config-examples/msgraph-thumbprint.yaml @@ -0,0 +1,10 @@ +# Microsoft Graph — Windows certificate store auth via thumbprint (Windows only) +# Usage: gomailtest msgraph testconnect|testauth|getevents|getinbox --config msgraph-thumbprint.yaml +# Certificate must be present in the CurrentUser\My store on the machine running gomailtest. +tenantid: 00000000-0000-0000-0000-000000000000 +clientid: 00000000-0000-0000-0000-000000000000 +thumbprint: CD817B3329802E692CF30D8DDF896FE811B048AB +mailbox: user@example.com +# proxy: http://proxy.example.com:8080 +# maxretries: 3 +# retrydelay: 2000 diff --git a/docs/config-examples/pop3-exportmessages.yaml b/docs/config-examples/pop3-exportmessages.yaml new file mode 100644 index 0000000..56c3375 --- /dev/null +++ b/docs/config-examples/pop3-exportmessages.yaml @@ -0,0 +1,15 @@ +# POP3 — export matching messages as .eml files +# Usage: gomailtest pop3 exportmessages --config pop3-exportmessages.yaml +host: pop.example.com +port: 995 +pop3s: true +username: user@example.com +password: change-me +# Search filters — at least one of subject or messageid is typically provided +subject: "Invoice" +# messageid: "" +count: 25 +exportdir: C:\exports +# proxy: http://proxy.example.com:8080 +# maxretries: 3 +# retrydelay: 2000 diff --git a/docs/config-examples/pop3-pop3s.yaml b/docs/config-examples/pop3-pop3s.yaml new file mode 100644 index 0000000..4aa5775 --- /dev/null +++ b/docs/config-examples/pop3-pop3s.yaml @@ -0,0 +1,19 @@ +# POP3 — implicit TLS / POP3S (port 995) +# Usage: gomailtest pop3 testconnect|testauth|listmail --config pop3-pop3s.yaml +host: pop.example.com +port: 995 +pop3s: true +username: user@example.com +password: change-me +# authmethod: auto # auto-selects: USER/PASS or APOP +# maxmessages: 100 # limit for listmail (default 100) +# skipverify: true # skip TLS certificate verification (testing only) +# tlsversion: "1.3" # minimum TLS version; default is 1.2 +# proxy: http://proxy.example.com:8080 +# maxretries: 3 +# retrydelay: 2000 + +# Provider quick-reference: +# Gmail: host: pop.gmail.com port: 995 +# M365: host: outlook.office365.com port: 995 +# Yahoo: host: pop.mail.yahoo.com port: 995 diff --git a/docs/config-examples/pop3-starttls.yaml b/docs/config-examples/pop3-starttls.yaml new file mode 100644 index 0000000..7dda762 --- /dev/null +++ b/docs/config-examples/pop3-starttls.yaml @@ -0,0 +1,14 @@ +# POP3 — explicit TLS via STLS (port 110) +# Usage: gomailtest pop3 testconnect|testauth|listmail --config pop3-starttls.yaml +host: pop.example.com +port: 110 +starttls: true +username: user@example.com +password: change-me +# authmethod: auto # auto-selects: USER/PASS or APOP +# maxmessages: 100 # limit for listmail (default 100) +# skipverify: true # skip TLS certificate verification (testing only) +# tlsversion: "1.3" # minimum TLS version; default is 1.2 +# proxy: http://proxy.example.com:8080 +# maxretries: 3 +# retrydelay: 2000 diff --git a/docs/config-examples/serve.yaml b/docs/config-examples/serve.yaml new file mode 100644 index 0000000..d060407 --- /dev/null +++ b/docs/config-examples/serve.yaml @@ -0,0 +1,26 @@ +# Serve mode — HTTP REST server with SMTP and Microsoft Graph backends +# Usage: gomailtest serve --config serve.yaml +port: 8080 +listen: 127.0.0.1 +api-key: change-me + +# SMTP backend — seeds the /smtp/sendmail endpoint +# Environment variables (SMTP*) take precedence over values here. +smtp: + host: smtp.example.com + port: 587 + starttls: true + username: user@example.com + password: change-me + from: sender@example.com + # skipverify: true + # proxy: http://proxy.example.com:8080 + +# Microsoft Graph backend — seeds the /msgraph/sendmail endpoint +# Environment variables (MSGRAPH*) take precedence over values here. +msgraph: + tenantid: 00000000-0000-0000-0000-000000000000 + clientid: 00000000-0000-0000-0000-000000000000 + secret: your-client-secret-here + mailbox: sender@example.com + # proxy: http://proxy.example.com:8080 diff --git a/docs/config-examples/smtp-gssapi.yaml b/docs/config-examples/smtp-gssapi.yaml new file mode 100644 index 0000000..5c70a85 --- /dev/null +++ b/docs/config-examples/smtp-gssapi.yaml @@ -0,0 +1,11 @@ +# SMTP — GSSAPI/Kerberos auth for on-premises Active Directory (port 25) +# Usage: gomailtest smtp testconnect|testauth --config smtp-gssapi.yaml +host: mail.contoso.com +port: 25 +# username must be in user@REALM format; realm is auto-extracted +username: alice@CONTOSO.COM +password: change-me +authmethod: GSSAPI +# realm: CONTOSO.COM # optional — auto-extracted from username if omitted +# kdc: dc01.contoso.com # optional — uses DNS SRV records if omitted; set when SRV records are missing +# proxy: http://proxy.example.com:8080 diff --git a/docs/config-examples/smtp-ntlm.yaml b/docs/config-examples/smtp-ntlm.yaml new file mode 100644 index 0000000..0d831bd --- /dev/null +++ b/docs/config-examples/smtp-ntlm.yaml @@ -0,0 +1,11 @@ +# SMTP — NTLM auth for on-premises Exchange / Windows SMTP relay (port 25) +# Usage: gomailtest smtp testconnect|testauth --config smtp-ntlm.yaml +host: mail.contoso.com +port: 25 +# username in DOMAIN\user format; plain user@domain.com is also accepted +username: CONTOSO\user +password: change-me +authmethod: NTLM +# no-starttls: true # force plain connection when the server advertises STARTTLS but you want to skip it +# skipverify: true # skip TLS certificate verification (testing only) +# proxy: http://proxy.example.com:8080 diff --git a/docs/config-examples/smtp-oauth2.yaml b/docs/config-examples/smtp-oauth2.yaml new file mode 100644 index 0000000..bbf10d5 --- /dev/null +++ b/docs/config-examples/smtp-oauth2.yaml @@ -0,0 +1,11 @@ +# SMTP — OAuth2 token auth (XOAUTH2 for M365/Google, OAUTHBEARER for RFC 7628 servers) +# Usage: gomailtest smtp testauth --config smtp-oauth2.yaml +host: smtp.office365.com +port: 587 +starttls: true +username: user@example.com +accesstoken: eyJ0eXAiOiJKV1Qi...your-oauth2-token-here +# authmethod: XOAUTH2 # for Microsoft 365 and Google Workspace +# authmethod: OAUTHBEARER # for Dovecot and other RFC 7628-compliant servers +authmethod: XOAUTH2 +# proxy: http://proxy.example.com:8080 diff --git a/docs/config-examples/smtp-sendmail.yaml b/docs/config-examples/smtp-sendmail.yaml new file mode 100644 index 0000000..29787df --- /dev/null +++ b/docs/config-examples/smtp-sendmail.yaml @@ -0,0 +1,23 @@ +# SMTP — full sendmail scenario: HTML body, CC/BCC, attachments, inline images, headers +# Usage: gomailtest smtp sendmail --config smtp-sendmail.yaml +host: smtp.example.com +port: 587 +starttls: true +username: user@example.com +password: change-me +from: sender@example.com +to: recipient@example.com +# cc: cc@example.com # visible in Cc: header and SMTP envelope +# bcc: bcc@example.com # SMTP envelope only — never written to message headers +subject: "Test Email from gomailtest" +body: "Plain-text fallback for clients that do not render HTML." +bodyhtml: "

Hello! This is a test message from gomailtest.

" +# attachments: ./report.pdf,./data.csv # comma-separated regular attachments +# inline-attachments: ./logo.png # embedded inline; reference as cid:logo.png in bodyhtml +header: + - "X-Custom-Header: example-value" +# priority: high # high | normal (default) | low — adds X-Priority/Importance/Priority headers +# use-mx: true # resolve --to recipient domain MX and connect there directly +# proxy: http://proxy.example.com:8080 +# maxretries: 3 +# retrydelay: 2000 diff --git a/docs/config-examples/smtp-smtps.yaml b/docs/config-examples/smtp-smtps.yaml new file mode 100644 index 0000000..1e51663 --- /dev/null +++ b/docs/config-examples/smtp-smtps.yaml @@ -0,0 +1,11 @@ +# SMTP — password auth with implicit TLS / SMTPS (port 465) +# Usage: gomailtest smtp testconnect|teststarttls|testauth --config smtp-smtps.yaml +host: smtp.example.com +port: 465 +smtps: true +username: user@example.com +password: change-me +# authmethod: auto # auto-selects strongest advertised method +# skipverify: true # skip TLS certificate verification (testing only) +# tlsversion: "1.3" # minimum TLS version; default is 1.2 +# proxy: http://proxy.example.com:8080 diff --git a/docs/config-examples/smtp-starttls.yaml b/docs/config-examples/smtp-starttls.yaml new file mode 100644 index 0000000..3fd42c8 --- /dev/null +++ b/docs/config-examples/smtp-starttls.yaml @@ -0,0 +1,11 @@ +# SMTP — password auth over STARTTLS (port 587) +# Usage: gomailtest smtp testconnect|teststarttls|testauth --config smtp-starttls.yaml +host: smtp.example.com +port: 587 +starttls: true +username: user@example.com +password: change-me +# authmethod: auto # auto-selects strongest advertised method (CRAM-MD5 > NTLM > PLAIN > LOGIN) +# skipverify: true # skip TLS certificate verification (testing only) +# tlsversion: "1.3" # minimum TLS version; default is 1.2 +# proxy: http://proxy.example.com:8080 diff --git a/docs/env-examples/ews-basic.env b/docs/env-examples/ews-basic.env new file mode 100644 index 0000000..2b8d081 --- /dev/null +++ b/docs/env-examples/ews-basic.env @@ -0,0 +1,22 @@ +# EWS — Basic authentication (legacy; requires basic auth enabled on Exchange) +# Usage: set these variables, then run: +# gomailtest ews testconnect|testauth|getfolder + +# ── Connection ─────────────────────────────────────────────────────────────── +EWSHOST=mail.example.com +EWSPORT=443 +# EWSTIMEOUT=30 +# EWSPATH=/EWS/Exchange.asmx +# EWSPROXY=http://proxy.example.com:8080 + +# ── TLS ────────────────────────────────────────────────────────────────────── +# EWSSKIPVERIFY=false +# EWSTLSVERSION=1.2 + +# ── Authentication ─────────────────────────────────────────────────────────── +EWSUSERNAME=user@example.com +EWSPASSWORD=change-me +EWSAUTHMETHOD=Basic + +# ── Impersonation ──────────────────────────────────────────────────────────── +# EWSMAILBOX=targetuser@example.com diff --git a/docs/env-examples/ews-bearer.env b/docs/env-examples/ews-bearer.env new file mode 100644 index 0000000..66ba294 --- /dev/null +++ b/docs/env-examples/ews-bearer.env @@ -0,0 +1,22 @@ +# EWS — OAuth2 Bearer token auth with mailbox impersonation +# Usage: set these variables, then run: +# gomailtest ews testauth|getfolder + +# ── Connection ─────────────────────────────────────────────────────────────── +EWSHOST=mail.example.com +EWSPORT=443 +# EWSTIMEOUT=30 +# EWSPATH=/EWS/Exchange.asmx +# EWSPROXY=http://proxy.example.com:8080 + +# ── TLS ────────────────────────────────────────────────────────────────────── +# EWSSKIPVERIFY=false + +# ── Authentication ─────────────────────────────────────────────────────────── +EWSUSERNAME=serviceaccount@example.com +EWSACCESSTOKEN=eyJ0eXAiOiJKV1Qi...your-oauth2-token-here +EWSAUTHMETHOD=Bearer + +# ── Impersonation ──────────────────────────────────────────────────────────── +# Required when a service account accesses another user's mailbox +EWSMAILBOX=targetuser@example.com diff --git a/docs/env-examples/ews-ntlm.env b/docs/env-examples/ews-ntlm.env new file mode 100644 index 0000000..2e381d3 --- /dev/null +++ b/docs/env-examples/ews-ntlm.env @@ -0,0 +1,25 @@ +# EWS — NTLM auth for on-premises Exchange with Active Directory +# Usage: set these variables, then run: +# gomailtest ews testconnect|testauth|getfolder|autodiscover + +# ── Connection ─────────────────────────────────────────────────────────────── +EWSHOST=mail.contoso.com +EWSPORT=443 +# EWSTIMEOUT=30 +# EWSPATH=/EWS/Exchange.asmx # default; override for non-standard installations +# EWSAUTODISCOVERPATH=/autodiscover/autodiscover.svc +# EWSPROXY=http://proxy.example.com:8080 + +# ── TLS ────────────────────────────────────────────────────────────────────── +# EWSSKIPVERIFY=false +# EWSTLSVERSION=1.2 + +# ── Authentication ─────────────────────────────────────────────────────────── +# Username in DOMAIN\user format +EWSUSERNAME=CONTOSO\user +EWSPASSWORD=change-me +EWSAUTHMETHOD=NTLM +# EWSDOMAIN=CONTOSO # alternative to embedding domain in username (DOMAIN\user form) + +# ── Impersonation ──────────────────────────────────────────────────────────── +# EWSMAILBOX=targetuser@contoso.com # set for mailbox impersonation (service account scenario) diff --git a/docs/env-examples/imap-exportmessages.env b/docs/env-examples/imap-exportmessages.env new file mode 100644 index 0000000..533c33d --- /dev/null +++ b/docs/env-examples/imap-exportmessages.env @@ -0,0 +1,27 @@ +# IMAP — export matching messages as .eml files +# Usage: set these variables, then run: +# gomailtest imap exportmessages + +# ── Connection ─────────────────────────────────────────────────────────────── +IMAPHOST=imap.example.com +IMAPPORT=993 +IMAPIMAPS=true +# IMAPPROXY=http://proxy.example.com:8080 +# IMAPMAXRETRIES=3 +# IMAPRETRYDELAY=2000 + +# ── Authentication ─────────────────────────────────────────────────────────── +IMAPUSERNAME=user@example.com +IMAPPASSWORD=change-me + +# ── Export ─────────────────────────────────────────────────────────────────── +# At least one of IMAPSUBJECT or IMAPMESSAGEID is typically provided +IMAPSUBJECT=Invoice +# IMAPMESSAGEID= +IMAPMAILBOX=INBOX +IMAPCOUNT=25 +IMAPEXPORTDIR=C:\exports + +# ── Output ──────────────────────────────────────────────────────────────────── +# IMAPVERBOSE=false +# IMAPLOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR diff --git a/docs/env-examples/imap-imaps.env b/docs/env-examples/imap-imaps.env new file mode 100644 index 0000000..f6093a7 --- /dev/null +++ b/docs/env-examples/imap-imaps.env @@ -0,0 +1,34 @@ +# IMAP — implicit TLS / IMAPS (port 993): Gmail, Microsoft 365, Yahoo, iCloud +# Usage: set these variables, then run: +# gomailtest imap testconnect|testauth|listfolders + +# ── Connection ─────────────────────────────────────────────────────────────── +IMAPHOST=imap.example.com +IMAPPORT=993 +IMAPIMAPS=true +# IMAPTIMEOUT=30 +# IMAPADDRESS= # connect to this IP instead of IMAPHOST (host still used for TLS SNI) +# IMAPIPV4=false +# IMAPIPV6=false +# IMAPPROXY=http://proxy.example.com:8080 +# IMAPMAXRETRIES=3 +# IMAPRETRYDELAY=2000 + +# ── TLS ────────────────────────────────────────────────────────────────────── +# IMAPSKIPVERIFY=false +# IMAPTLSVERSION=1.2 + +# ── Authentication ─────────────────────────────────────────────────────────── +IMAPUSERNAME=user@example.com +IMAPPASSWORD=change-me +# IMAPAUTHMETHOD=auto # auto-selects: PLAIN or LOGIN + +# ── Output ──────────────────────────────────────────────────────────────────── +# IMAPVERBOSE=false +# IMAPLOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR + +# Provider quick-reference: +# Gmail: IMAPHOST=imap.gmail.com +# Microsoft 365: IMAPHOST=outlook.office365.com +# Yahoo: IMAPHOST=imap.mail.yahoo.com +# iCloud: IMAPHOST=imap.mail.me.com diff --git a/docs/env-examples/imap-oauth2.env b/docs/env-examples/imap-oauth2.env new file mode 100644 index 0000000..066d121 --- /dev/null +++ b/docs/env-examples/imap-oauth2.env @@ -0,0 +1,21 @@ +# IMAP — XOAUTH2 token auth (Microsoft 365 / Google Workspace) +# Usage: set these variables, then run: +# gomailtest imap testauth|listfolders + +# ── Connection ─────────────────────────────────────────────────────────────── +IMAPHOST=imap.gmail.com +IMAPPORT=993 +IMAPIMAPS=true +# IMAPPROXY=http://proxy.example.com:8080 + +# ── TLS ────────────────────────────────────────────────────────────────────── +# IMAPSKIPVERIFY=false + +# ── Authentication ─────────────────────────────────────────────────────────── +IMAPUSERNAME=user@example.com +IMAPACCESSTOKEN=ya29.your-oauth2-token-here +IMAPAUTHMETHOD=XOAUTH2 + +# ── Output ──────────────────────────────────────────────────────────────────── +# IMAPVERBOSE=false +# IMAPLOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR diff --git a/docs/env-examples/imap-starttls.env b/docs/env-examples/imap-starttls.env new file mode 100644 index 0000000..22fbd2d --- /dev/null +++ b/docs/env-examples/imap-starttls.env @@ -0,0 +1,28 @@ +# IMAP — explicit TLS via STARTTLS (port 143) +# Usage: set these variables, then run: +# gomailtest imap testconnect|testauth|listfolders + +# ── Connection ─────────────────────────────────────────────────────────────── +IMAPHOST=imap.example.com +IMAPPORT=143 +IMAPSTARTTLS=true +# IMAPTIMEOUT=30 +# IMAPADDRESS= # connect to this IP instead of IMAPHOST (host still used for TLS SNI) +# IMAPIPV4=false +# IMAPIPV6=false +# IMAPPROXY=http://proxy.example.com:8080 +# IMAPMAXRETRIES=3 +# IMAPRETRYDELAY=2000 + +# ── TLS ────────────────────────────────────────────────────────────────────── +# IMAPSKIPVERIFY=false +# IMAPTLSVERSION=1.2 + +# ── Authentication ─────────────────────────────────────────────────────────── +IMAPUSERNAME=user@example.com +IMAPPASSWORD=change-me +# IMAPAUTHMETHOD=auto + +# ── Output ──────────────────────────────────────────────────────────────────── +# IMAPVERBOSE=false +# IMAPLOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR diff --git a/docs/env-examples/jmap-basic.env b/docs/env-examples/jmap-basic.env new file mode 100644 index 0000000..54b26e7 --- /dev/null +++ b/docs/env-examples/jmap-basic.env @@ -0,0 +1,18 @@ +# JMAP — Basic (password) auth for self-hosted JMAP servers (Cyrus IMAP, Apache James) +# Usage: set these variables, then run: +# gomailtest jmap testconnect|testauth|getmailboxes + +# ── Connection ─────────────────────────────────────────────────────────────── +JMAPHOST=jmap.example.com +JMAPPORT=443 +# JMAPADDRESS=192.168.1.10 # connect to this IP instead of JMAPHOST (host still used for TLS SNI) +# JMAPIPV4=false +# JMAPIPV6=false + +# ── TLS ────────────────────────────────────────────────────────────────────── +# JMAPSKIPVERIFY=false # useful for self-signed certs on self-hosted servers + +# ── Authentication ─────────────────────────────────────────────────────────── +JMAPUSERNAME=user@example.com +JMAPPASSWORD=change-me +JMAPAUTHMETHOD=basic diff --git a/docs/env-examples/jmap-bearer.env b/docs/env-examples/jmap-bearer.env new file mode 100644 index 0000000..a6f0e89 --- /dev/null +++ b/docs/env-examples/jmap-bearer.env @@ -0,0 +1,21 @@ +# JMAP — Bearer token auth (Fastmail and similar providers) +# Usage: set these variables, then run: +# gomailtest jmap testconnect|testauth|getmailboxes + +# ── Connection ─────────────────────────────────────────────────────────────── +JMAPHOST=jmap.fastmail.com +JMAPPORT=443 +# JMAPADDRESS= # connect to this IP instead of JMAPHOST (host still used for TLS SNI) +# JMAPIPV4=false +# JMAPIPV6=false + +# ── TLS ────────────────────────────────────────────────────────────────────── +# JMAPSKIPVERIFY=false + +# ── Authentication ─────────────────────────────────────────────────────────── +JMAPUSERNAME=user@fastmail.com +JMAPACCESSTOKEN=fmu1-xxxxxxxx-your-api-token-here +JMAPAUTHMETHOD=bearer + +# Getting a Fastmail API token: +# Settings → Password & Security → API Tokens → New Token diff --git a/docs/env-examples/msgraph-bearer.env b/docs/env-examples/msgraph-bearer.env new file mode 100644 index 0000000..277a2fb --- /dev/null +++ b/docs/env-examples/msgraph-bearer.env @@ -0,0 +1,13 @@ +# Microsoft Graph — pre-obtained Bearer token auth +# Useful when a token has already been obtained outside gomailtest (e.g. via az cli or custom OAuth flow). +# Usage: set these variables, then run: +# gomailtest msgraph testconnect|testauth|getevents|getinbox + +# ── Authentication ─────────────────────────────────────────────────────────── +MSGRAPHTENANTID=00000000-0000-0000-0000-000000000000 +MSGRAPHCLIENTID=00000000-0000-0000-0000-000000000000 +MSGRAPHBEARERTOKEN=eyJ0eXAiOiJKV1Qi...your-bearer-token-here +MSGRAPHMAILBOX=user@example.com + +# ── Optional ───────────────────────────────────────────────────────────────── +# MSGRAPHPROXY=http://proxy.example.com:8080 diff --git a/docs/env-examples/msgraph-pfx.env b/docs/env-examples/msgraph-pfx.env new file mode 100644 index 0000000..b5d76ab --- /dev/null +++ b/docs/env-examples/msgraph-pfx.env @@ -0,0 +1,15 @@ +# Microsoft Graph — PFX certificate file auth +# Usage: set these variables, then run: +# gomailtest msgraph testconnect|testauth|getevents|getinbox + +# ── Authentication ─────────────────────────────────────────────────────────── +MSGRAPHTENANTID=00000000-0000-0000-0000-000000000000 +MSGRAPHCLIENTID=00000000-0000-0000-0000-000000000000 +MSGRAPHPFX=C:\Certs\app-cert.pfx +MSGRAPHPFXPASS=certificate-password +MSGRAPHMAILBOX=user@example.com + +# ── Optional ───────────────────────────────────────────────────────────────── +# MSGRAPHPROXY=http://proxy.example.com:8080 +# MSGRAPHMAXRETRIES=3 +# MSGRAPHRETRYDELAY=2000 diff --git a/docs/env-examples/msgraph-secret.env b/docs/env-examples/msgraph-secret.env new file mode 100644 index 0000000..661020b --- /dev/null +++ b/docs/env-examples/msgraph-secret.env @@ -0,0 +1,15 @@ +# Microsoft Graph — client secret auth (most common app registration scenario) +# Usage: set these variables, then run: +# gomailtest msgraph testconnect|testauth|getevents|getinbox|getschedule + +# ── Authentication ─────────────────────────────────────────────────────────── +MSGRAPHTENANTID=00000000-0000-0000-0000-000000000000 +MSGRAPHCLIENTID=00000000-0000-0000-0000-000000000000 +MSGRAPHSECRET=your-client-secret-here +MSGRAPHMAILBOX=user@example.com + +# ── Optional ───────────────────────────────────────────────────────────────── +# MSGRAPHPROXY=http://proxy.example.com:8080 +# MSGRAPHMAXRETRIES=3 +# MSGRAPHRETRYDELAY=2000 +# MSGRAPHCOUNT=3 # number of items for getevents / getinbox (default 3) diff --git a/docs/env-examples/msgraph-sendmail.env b/docs/env-examples/msgraph-sendmail.env new file mode 100644 index 0000000..c949093 --- /dev/null +++ b/docs/env-examples/msgraph-sendmail.env @@ -0,0 +1,28 @@ +# Microsoft Graph — full sendmail scenario: HTML body, CC/BCC, attachments, inline images, headers, priority +# Usage: set these variables, then run: +# gomailtest msgraph sendmail + +# ── Authentication ─────────────────────────────────────────────────────────── +MSGRAPHTENANTID=00000000-0000-0000-0000-000000000000 +MSGRAPHCLIENTID=00000000-0000-0000-0000-000000000000 +MSGRAPHSECRET=your-client-secret-here +MSGRAPHMAILBOX=sender@example.com + +# ── Message ────────────────────────────────────────────────────────────────── +MSGRAPHTO=recipient@example.com +# MSGRAPHCC=cc@example.com +# MSGRAPHBCC=bcc@example.com +MSGRAPHSUBJECT=Test Email from gomailtest +MSGRAPHBODY=Plain-text fallback for clients that do not render HTML. +MSGRAPHBODYHTML=

Hello! This is a test message from gomailtest.

+# MSGRAPHATTACHMENTS=C:\Reports\report.pdf,C:\Reports\data.csv +# MSGRAPHINLINEATTACHMENTS=C:\Branding\logo.png # embedded inline; reference as cid:logo.png in MSGRAPHBODYHTML +# MSGRAPHBODYTEMPLATE=C:\Templates\email.html # path to HTML template file (alternative to MSGRAPHBODYHTML) +# MSGRAPHPRIORITY=high # high | normal (default) | low +# MSGRAPHHEADER=X-Custom-Header: example-value # comma-separated; avoid commas in header values +# # Graph only passes through X- prefixed custom headers + +# ── Optional ───────────────────────────────────────────────────────────────── +# MSGRAPHPROXY=http://proxy.example.com:8080 +# MSGRAPHMAXRETRIES=3 +# MSGRAPHRETRYDELAY=2000 diff --git a/docs/env-examples/msgraph-thumbprint.env b/docs/env-examples/msgraph-thumbprint.env new file mode 100644 index 0000000..7c69bfd --- /dev/null +++ b/docs/env-examples/msgraph-thumbprint.env @@ -0,0 +1,15 @@ +# Microsoft Graph — Windows certificate store auth via thumbprint (Windows only) +# Certificate must be present in the CurrentUser\My store on the machine running gomailtest. +# Usage: set these variables, then run: +# gomailtest msgraph testconnect|testauth|getevents|getinbox + +# ── Authentication ─────────────────────────────────────────────────────────── +MSGRAPHTENANTID=00000000-0000-0000-0000-000000000000 +MSGRAPHCLIENTID=00000000-0000-0000-0000-000000000000 +MSGRAPHTHUMBPRINT=CD817B3329802E692CF30D8DDF896FE811B048AB +MSGRAPHMAILBOX=user@example.com + +# ── Optional ───────────────────────────────────────────────────────────────── +# MSGRAPHPROXY=http://proxy.example.com:8080 +# MSGRAPHMAXRETRIES=3 +# MSGRAPHRETRYDELAY=2000 diff --git a/docs/env-examples/pop3-exportmessages.env b/docs/env-examples/pop3-exportmessages.env new file mode 100644 index 0000000..f1895d8 --- /dev/null +++ b/docs/env-examples/pop3-exportmessages.env @@ -0,0 +1,26 @@ +# POP3 — export matching messages as .eml files +# Usage: set these variables, then run: +# gomailtest pop3 exportmessages + +# ── Connection ─────────────────────────────────────────────────────────────── +POP3HOST=pop.example.com +POP3PORT=995 +POP3POP3S=true +# POP3PROXY=http://proxy.example.com:8080 +# POP3MAXRETRIES=3 +# POP3RETRYDELAY=2000 + +# ── Authentication ─────────────────────────────────────────────────────────── +POP3USERNAME=user@example.com +POP3PASSWORD=change-me + +# ── Export ─────────────────────────────────────────────────────────────────── +# At least one of POP3SUBJECT or POP3MESSAGEID is typically provided +POP3SUBJECT=Invoice +# POP3MESSAGEID= +POP3COUNT=25 +POP3EXPORTDIR=C:\exports + +# ── Output ──────────────────────────────────────────────────────────────────── +# POP3VERBOSE=false +# POP3LOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR diff --git a/docs/env-examples/pop3-pop3s.env b/docs/env-examples/pop3-pop3s.env new file mode 100644 index 0000000..0ceba77 --- /dev/null +++ b/docs/env-examples/pop3-pop3s.env @@ -0,0 +1,36 @@ +# POP3 — implicit TLS / POP3S (port 995) +# Usage: set these variables, then run: +# gomailtest pop3 testconnect|testauth|listmail + +# ── Connection ─────────────────────────────────────────────────────────────── +POP3HOST=pop.example.com +POP3PORT=995 +POP3POP3S=true +# POP3TIMEOUT=30 +# POP3ADDRESS= # connect to this IP instead of POP3HOST (host still used for TLS SNI) +# POP3IPV4=false +# POP3IPV6=false +# POP3PROXY=http://proxy.example.com:8080 +# POP3MAXRETRIES=3 +# POP3RETRYDELAY=2000 + +# ── TLS ────────────────────────────────────────────────────────────────────── +# POP3SKIPVERIFY=false +# POP3TLSVERSION=1.2 + +# ── Authentication ─────────────────────────────────────────────────────────── +POP3USERNAME=user@example.com +POP3PASSWORD=change-me +# POP3AUTHMETHOD=auto # auto-selects: USER/PASS or APOP + +# ── Output ──────────────────────────────────────────────────────────────────── +# POP3VERBOSE=false +# POP3LOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR + +# ── listmail ───────────────────────────────────────────────────────────────── +# POP3MAXMESSAGES=100 # maximum messages to list (default 100) + +# Provider quick-reference: +# Gmail: POP3HOST=pop.gmail.com +# M365: POP3HOST=outlook.office365.com +# Yahoo: POP3HOST=pop.mail.yahoo.com diff --git a/docs/env-examples/pop3-starttls.env b/docs/env-examples/pop3-starttls.env new file mode 100644 index 0000000..00768e9 --- /dev/null +++ b/docs/env-examples/pop3-starttls.env @@ -0,0 +1,31 @@ +# POP3 — explicit TLS via STLS (port 110) +# Usage: set these variables, then run: +# gomailtest pop3 testconnect|testauth|listmail + +# ── Connection ─────────────────────────────────────────────────────────────── +POP3HOST=pop.example.com +POP3PORT=110 +POP3STARTTLS=true +# POP3TIMEOUT=30 +# POP3ADDRESS= # connect to this IP instead of POP3HOST (host still used for TLS SNI) +# POP3IPV4=false +# POP3IPV6=false +# POP3PROXY=http://proxy.example.com:8080 +# POP3MAXRETRIES=3 +# POP3RETRYDELAY=2000 + +# ── TLS ────────────────────────────────────────────────────────────────────── +# POP3SKIPVERIFY=false +# POP3TLSVERSION=1.2 + +# ── Authentication ─────────────────────────────────────────────────────────── +POP3USERNAME=user@example.com +POP3PASSWORD=change-me +# POP3AUTHMETHOD=auto + +# ── Output ──────────────────────────────────────────────────────────────────── +# POP3VERBOSE=false +# POP3LOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR + +# ── listmail ───────────────────────────────────────────────────────────────── +# POP3MAXMESSAGES=100 diff --git a/docs/env-examples/serve.env b/docs/env-examples/serve.env new file mode 100644 index 0000000..73ba52e --- /dev/null +++ b/docs/env-examples/serve.env @@ -0,0 +1,33 @@ +# Serve mode — HTTP REST server with SMTP and Microsoft Graph backends +# Usage: set these variables, then run: +# gomailtest serve + +# ── HTTP Server ─────────────────────────────────────────────────────────────── +# Required: API key checked via X-API-Key header on all non-health endpoints. +SERVE_API_KEY=change-me +# SERVE_PORT=8080 +# SERVE_LISTEN=127.0.0.1 # set to 0.0.0.0 to listen on all interfaces + +# ── SMTP backend — seeds the /smtp/sendmail endpoint ───────────────────────── +# Required for POST /smtp/sendmail to be available. +SMTPHOST=smtp.example.com +SMTPPORT=587 +SMTPSTARTTLS=true +SMTPUSERNAME=user@example.com +SMTPPASSWORD=change-me +SMTPFROM=sender@example.com +# SMTPSMTPS=false +# SMTPSKIPVERIFY=false +# SMTPAUTHMETHOD=auto +# SMTPPROXY=http://proxy.example.com:8080 + +# ── Microsoft Graph backend — seeds the /msgraph/sendmail endpoint ─────────── +# Required for POST /msgraph/sendmail to be available. +MSGRAPHTENANTID=00000000-0000-0000-0000-000000000000 +MSGRAPHCLIENTID=00000000-0000-0000-0000-000000000000 +MSGRAPHSECRET=your-client-secret-here +# MSGRAPHPFX=C:\Certs\app-cert.pfx # alternative to MSGRAPHSECRET +# MSGRAPHPFXPASS=certificate-password +# MSGRAPHBEARERTOKEN= # alternative to MSGRAPHSECRET +MSGRAPHMAILBOX=sender@example.com +# MSGRAPHPROXY=http://proxy.example.com:8080 diff --git a/docs/env-examples/smtp-gssapi.env b/docs/env-examples/smtp-gssapi.env new file mode 100644 index 0000000..104baa7 --- /dev/null +++ b/docs/env-examples/smtp-gssapi.env @@ -0,0 +1,20 @@ +# SMTP — GSSAPI/Kerberos auth for on-premises Active Directory (port 25) +# Usage: set these variables, then run: +# gomailtest smtp testconnect|testauth + +# ── Connection ─────────────────────────────────────────────────────────────── +SMTPHOST=mail.contoso.com +SMTPPORT=25 +# SMTPPROXY=http://proxy.example.com:8080 + +# ── Authentication ─────────────────────────────────────────────────────────── +# Username must be in user@REALM format; realm is auto-extracted +SMTPUSERNAME=alice@CONTOSO.COM +SMTPPASSWORD=change-me +SMTPAUTHMETHOD=GSSAPI +# SMTPREALM=CONTOSO.COM # optional — auto-extracted from username if omitted +# SMTPKDC=dc01.contoso.com # optional — uses DNS SRV records if omitted; set when SRV missing + +# ── Output ──────────────────────────────────────────────────────────────────── +# SMTPVERBOSE=false +# SMTPLOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR diff --git a/docs/env-examples/smtp-ntlm.env b/docs/env-examples/smtp-ntlm.env new file mode 100644 index 0000000..a43a183 --- /dev/null +++ b/docs/env-examples/smtp-ntlm.env @@ -0,0 +1,20 @@ +# SMTP — NTLM auth for on-premises Exchange / Windows SMTP relay (port 25) +# Usage: set these variables, then run: +# gomailtest smtp testconnect|testauth + +# ── Connection ─────────────────────────────────────────────────────────────── +SMTPHOST=mail.contoso.com +SMTPPORT=25 +# SMTPADDRESS= # connect to this IP instead of SMTPHOST +# SMTPPROXY=http://proxy.example.com:8080 + +# ── Authentication ─────────────────────────────────────────────────────────── +# Username in DOMAIN\user format; plain user@domain.com is also accepted +SMTPUSERNAME=CONTOSO\user +SMTPPASSWORD=change-me +SMTPAUTHMETHOD=NTLM +# SMTPNOSTARTTLS=false # force plain connection when server advertises STARTTLS but you want to skip it + +# ── Output ──────────────────────────────────────────────────────────────────── +# SMTPVERBOSE=false +# SMTPLOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR diff --git a/docs/env-examples/smtp-oauth2.env b/docs/env-examples/smtp-oauth2.env new file mode 100644 index 0000000..2c5ff26 --- /dev/null +++ b/docs/env-examples/smtp-oauth2.env @@ -0,0 +1,20 @@ +# SMTP — OAuth2 token auth (XOAUTH2 for M365/Google, OAUTHBEARER for RFC 7628 servers) +# Usage: set these variables, then run: +# gomailtest smtp testauth + +# ── Connection ─────────────────────────────────────────────────────────────── +SMTPHOST=smtp.office365.com +SMTPPORT=587 +SMTPSTARTTLS=true +# SMTPPROXY=http://proxy.example.com:8080 + +# ── Authentication ─────────────────────────────────────────────────────────── +SMTPUSERNAME=user@example.com +SMTPACCESSTOKEN=eyJ0eXAiOiJKV1Qi...your-oauth2-token-here +# SMTPAUTHMETHOD=XOAUTH2 # for Microsoft 365 and Google Workspace +# SMTPAUTHMETHOD=OAUTHBEARER # for Dovecot and other RFC 7628-compliant servers +SMTPAUTHMETHOD=XOAUTH2 + +# ── Output ──────────────────────────────────────────────────────────────────── +# SMTPVERBOSE=false +# SMTPLOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR diff --git a/docs/env-examples/smtp-sendmail.env b/docs/env-examples/smtp-sendmail.env new file mode 100644 index 0000000..f2ca0a4 --- /dev/null +++ b/docs/env-examples/smtp-sendmail.env @@ -0,0 +1,31 @@ +# SMTP — full sendmail scenario: HTML body, CC/BCC, attachments, inline images, headers, priority +# Usage: set these variables, then run: +# gomailtest smtp sendmail + +# ── Connection ─────────────────────────────────────────────────────────────── +SMTPHOST=smtp.example.com +SMTPPORT=587 +SMTPSTARTTLS=true +# SMTPPROXY=http://proxy.example.com:8080 +# SMTPUSEMX=false # resolve recipient domain MX and connect there directly + +# ── Authentication ─────────────────────────────────────────────────────────── +SMTPUSERNAME=user@example.com +SMTPPASSWORD=change-me + +# ── Message ────────────────────────────────────────────────────────────────── +SMTPFROM=sender@example.com +SMTPTO=recipient@example.com +# SMTPCC=cc@example.com # visible in Cc: header and SMTP envelope +# SMTPBCC=bcc@example.com # SMTP envelope only — never written to headers +SMTPSUBJECT=Test Email from gomailtest +SMTPBODY=Plain-text fallback for clients that do not render HTML. +SMTPBODYHTML=

Hello! This is a test message from gomailtest.

+# SMTPATTACHMENTS=./report.pdf,./data.csv # comma-separated regular attachments +# SMTPINLINEATTACHMENTS=./logo.png # embedded inline; reference as cid:logo.png in SMTPBODYHTML +# SMTPPRIORITY=high # high | normal (default) | low +# SMTPHEADER=X-Custom-Header: example-value # comma-separated; avoid commas in header values + +# ── Output ──────────────────────────────────────────────────────────────────── +# SMTPVERBOSE=false +# SMTPLOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR diff --git a/docs/env-examples/smtp-smtps.env b/docs/env-examples/smtp-smtps.env new file mode 100644 index 0000000..555592d --- /dev/null +++ b/docs/env-examples/smtp-smtps.env @@ -0,0 +1,26 @@ +# SMTP — password auth with implicit TLS / SMTPS (port 465) +# Usage: set these variables, then run: +# gomailtest smtp testconnect|teststarttls|testauth + +# ── Connection ─────────────────────────────────────────────────────────────── +SMTPHOST=smtp.example.com +SMTPPORT=465 +SMTPSMTPS=true +# SMTPTIMEOUT=30 +# SMTPADDRESS= # connect to this IP instead of SMTPHOST (host still used for TLS SNI) +# SMTPIPV4=false +# SMTPIPV6=false +# SMTPPROXY=http://proxy.example.com:8080 + +# ── TLS ────────────────────────────────────────────────────────────────────── +# SMTPSKIPVERIFY=false +# SMTPTLSVERSION=1.2 + +# ── Authentication ─────────────────────────────────────────────────────────── +SMTPUSERNAME=user@example.com +SMTPPASSWORD=change-me +# SMTPAUTHMETHOD=auto + +# ── Output ──────────────────────────────────────────────────────────────────── +# SMTPVERBOSE=false +# SMTPLOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR diff --git a/docs/env-examples/smtp-starttls.env b/docs/env-examples/smtp-starttls.env new file mode 100644 index 0000000..e3a8fe2 --- /dev/null +++ b/docs/env-examples/smtp-starttls.env @@ -0,0 +1,26 @@ +# SMTP — password auth over STARTTLS (port 587) +# Usage: set these variables, then run: +# gomailtest smtp testconnect|teststarttls|testauth + +# ── Connection ─────────────────────────────────────────────────────────────── +SMTPHOST=smtp.example.com +SMTPPORT=587 +SMTPSTARTTLS=true +# SMTPTIMEOUT=30 +# SMTPADDRESS= # connect to this IP instead of SMTPHOST (host still used for TLS SNI) +# SMTPIPV4=false # force IPv4 +# SMTPIPV6=false # force IPv6 +# SMTPPROXY=http://proxy.example.com:8080 + +# ── TLS ────────────────────────────────────────────────────────────────────── +# SMTPSKIPVERIFY=false # skip certificate verification (testing only) +# SMTPTLSVERSION=1.2 # minimum TLS version; 1.2 or 1.3 + +# ── Authentication ─────────────────────────────────────────────────────────── +SMTPUSERNAME=user@example.com +SMTPPASSWORD=change-me +# SMTPAUTHMETHOD=auto # auto-selects strongest advertised method: CRAM-MD5 > NTLM > PLAIN > LOGIN + +# ── Output ──────────────────────────────────────────────────────────────────── +# SMTPVERBOSE=false +# SMTPLOGLEVEL=INFO # DEBUG, INFO, WARN, ERROR diff --git a/docs/protocols/imap.md b/docs/protocols/imap.md index 2c2ea19..35fc4f0 100644 --- a/docs/protocols/imap.md +++ b/docs/protocols/imap.md @@ -108,8 +108,8 @@ Output goes to `%TEMP%\export\{date}\msg_{uid}.eml`, or | `--maxretries` | Maximum retry attempts | `IMAPMAXRETRIES` | 3 | | `--retrydelay` | Retry delay (milliseconds) | `IMAPRETRYDELAY` | 2000 | | `--ratelimit` | Max requests per second (0 = unlimited) | `IMAPRATELIMIT` | 0 | -| `--verbose` | Enable verbose output | — | false | -| `--loglevel` | Log level: DEBUG, INFO, WARN, ERROR | — | INFO | +| `--verbose` | Enable verbose output | `IMAPVERBOSE` | false | +| `--loglevel` | Log level: DEBUG, INFO, WARN, ERROR | `IMAPLOGLEVEL` | INFO | | `--output` | Output format: text, json | `IMAPOUTPUT` | text | | `--logformat` | Log file format: csv, json | `IMAPLOGFORMAT` | csv | diff --git a/docs/protocols/msgraph.md b/docs/protocols/msgraph.md index 86588e3..792e308 100644 --- a/docs/protocols/msgraph.md +++ b/docs/protocols/msgraph.md @@ -83,6 +83,8 @@ gomailtest msgraph sendmail \ --header "X-Custom-Header: example-value" ``` +> **Note:** Microsoft Graph only passes through `X-`-prefixed custom headers. Standard RFC headers (From, To, Subject, Date, Message-ID, etc.) are set by the Graph API itself and cannot be overridden via `--header`. + ### sendinvite — Create Calendar Invitations ```powershell @@ -179,7 +181,7 @@ Output goes to `%TEMP%\export\{date}\msg_{id}.eml`, or | `--body-template` | Path to HTML template file | `MSGRAPHBODYTEMPLATE` | | `--attachments` | Comma-separated file paths | `MSGRAPHATTACHMENTS` | | `--inline-attachments` | Comma-separated file paths to embed inline via `cid:` (referenced from `--bodyHTML`) | `MSGRAPHINLINEATTACHMENTS` | -| `--header` | Custom header in `"Name: Value"` form (repeatable) | — (CLI only) | +| `--header` | Custom header in `"Name: Value"` form (repeatable); when set via env var use comma-separated values (avoid commas in header values). **Microsoft Graph only passes through `X-`-prefixed custom headers** — standard RFC headers (From, To, Subject, etc.) are controlled by the API itself and cannot be injected here | `MSGRAPHHEADER` | | `--priority` | Email priority/importance: `high`, `normal`, `low` (maps to the Graph `importance` field) | `MSGRAPHPRIORITY` | | `--start` | Start time (RFC3339) | `MSGRAPHSTART` | | `--end` | End time (RFC3339) | `MSGRAPHEND` | diff --git a/docs/protocols/pop3.md b/docs/protocols/pop3.md index 7b08434..a2b7fc0 100644 --- a/docs/protocols/pop3.md +++ b/docs/protocols/pop3.md @@ -115,8 +115,8 @@ Output goes to `%TEMP%\export\{date}\msg_{message-id}.eml`, or | `--maxretries` | Maximum retry attempts | `POP3MAXRETRIES` | 3 | | `--retrydelay` | Retry delay (milliseconds) | `POP3RETRYDELAY` | 2000 | | `--ratelimit` | Max requests per second (0 = unlimited) | `POP3RATELIMIT` | 0 | -| `--verbose` | Enable verbose output | — | false | -| `--loglevel` | Log level: DEBUG, INFO, WARN, ERROR | — | INFO | +| `--verbose` | Enable verbose output | `POP3VERBOSE` | false | +| `--loglevel` | Log level: DEBUG, INFO, WARN, ERROR | `POP3LOGLEVEL` | INFO | | `--logformat` | Log file format: csv, json | `POP3LOGFORMAT` | csv | **Note:** `--pop3s` and `--starttls` cannot be used together. `--no-pop3s`+`--pop3s` and `--no-starttls`+`--starttls` are each mutually exclusive (useful to catch conflicting defaults from `--config`/env vars). diff --git a/docs/protocols/smtp.md b/docs/protocols/smtp.md index a4259c3..b3dabda 100644 --- a/docs/protocols/smtp.md +++ b/docs/protocols/smtp.md @@ -182,7 +182,7 @@ vars). `teststarttls` requires either STARTTLS or `--smtps` to test, so | `--bodyhtml` | HTML body content; combine with `--body` for `multipart/alternative` | `SMTPBODYHTML` | | `--attachments` | Comma-separated file paths to attach | `SMTPATTACHMENTS` | | `--inline-attachments` | Comma-separated file paths to embed inline via `cid:` | `SMTPINLINEATTACHMENTS` | -| `--header` | Custom header in `"Name: Value"` form (repeatable) | — (CLI only) | +| `--header` | Custom header in `"Name: Value"` form (repeatable); when set via env var use comma-separated values (avoid commas in header values) | `SMTPHEADER` | | `--priority` | Email priority: `high`, `normal`, `low`. `high`/`low` add `X-Priority`, `Importance`, and `Priority` headers; `normal` (default) adds no extra headers | `SMTPPRIORITY` | ## Environment Variables diff --git a/internal/protocols/imap/config.go b/internal/protocols/imap/config.go index 15307c5..5acda59 100644 --- a/internal/protocols/imap/config.go +++ b/internal/protocols/imap/config.go @@ -123,8 +123,8 @@ func RegisterPersistentFlags(cmd *cobra.Command) { f.Float64("ratelimit", 0, "Maximum IMAP requests per second (0 = unlimited) (env: IMAPRATELIMIT)") // Output - f.Bool("verbose", false, "Enable verbose output") - f.String("loglevel", "INFO", "Logging level: DEBUG, INFO, WARN, ERROR") + f.Bool("verbose", false, "Enable verbose output (env: IMAPVERBOSE)") + f.String("loglevel", "INFO", "Logging level: DEBUG, INFO, WARN, ERROR (env: IMAPLOGLEVEL)") f.String("output", "text", "Output format: text, json (env: IMAPOUTPUT)") f.String("logformat", "csv", "Log file format: csv, json (env: IMAPLOGFORMAT)") } @@ -155,6 +155,8 @@ func BindEnvs(v *viper.Viper) { "output": "IMAPOUTPUT", "logformat": "IMAPLOGFORMAT", "ratelimit": "IMAPRATELIMIT", + "verbose": "IMAPVERBOSE", + "loglevel": "IMAPLOGLEVEL", "subject": "IMAPSUBJECT", "messageid": "IMAPMESSAGEID", "mailbox": "IMAPMAILBOX", diff --git a/internal/protocols/msgraph/cmd.go b/internal/protocols/msgraph/cmd.go index 4807279..6ac8364 100644 --- a/internal/protocols/msgraph/cmd.go +++ b/internal/protocols/msgraph/cmd.go @@ -157,7 +157,7 @@ func newSendMailCmd(v *viper.Viper) *cobra.Command { cmd.Flags().String("body-template", "", "Path to HTML email body template file (env: MSGRAPHBODYTEMPLATE)") cmd.Flags().String("attachments", "", "Comma-separated file paths to attach (env: MSGRAPHATTACHMENTS)") cmd.Flags().String("inline-attachments", "", "Comma-separated file paths to embed inline via cid: (env: MSGRAPHINLINEATTACHMENTS)") - cmd.Flags().StringArray("header", nil, "Custom header in 'Name: Value' form (repeatable)") + cmd.Flags().StringArray("header", nil, "Custom header in 'Name: Value' form (repeatable) (env: MSGRAPHHEADER — comma-separated; avoid commas in header values)") cmd.Flags().String("priority", "normal", "Email priority/importance: high, normal, low (env: MSGRAPHPRIORITY)") return cmd } diff --git a/internal/protocols/msgraph/config.go b/internal/protocols/msgraph/config.go index 904cf5e..221d5d8 100644 --- a/internal/protocols/msgraph/config.go +++ b/internal/protocols/msgraph/config.go @@ -160,6 +160,7 @@ func BindEnvs(v *viper.Viper) { "output": "MSGRAPHOUTPUT", "logformat": "MSGRAPHLOGFORMAT", "count": "MSGRAPHCOUNT", + "header": "MSGRAPHHEADER", } for key, env := range bindings { _ = v.BindEnv(key, env) diff --git a/internal/protocols/pop3/config.go b/internal/protocols/pop3/config.go index 32fe87a..3dd028c 100644 --- a/internal/protocols/pop3/config.go +++ b/internal/protocols/pop3/config.go @@ -125,8 +125,8 @@ func RegisterPersistentFlags(cmd *cobra.Command) { f.Float64("ratelimit", 0, "Maximum POP3 requests per second (0 = unlimited) (env: POP3RATELIMIT)") // Output - f.Bool("verbose", false, "Enable verbose output") - f.String("loglevel", "INFO", "Logging level: DEBUG, INFO, WARN, ERROR") + f.Bool("verbose", false, "Enable verbose output (env: POP3VERBOSE)") + f.String("loglevel", "INFO", "Logging level: DEBUG, INFO, WARN, ERROR (env: POP3LOGLEVEL)") f.String("output", "text", "Output format: text, json (env: POP3OUTPUT)") f.String("logformat", "csv", "Log file format: csv, json (env: POP3LOGFORMAT)") } @@ -157,6 +157,8 @@ func BindEnvs(v *viper.Viper) { "output": "POP3OUTPUT", "logformat": "POP3LOGFORMAT", "ratelimit": "POP3RATELIMIT", + "verbose": "POP3VERBOSE", + "loglevel": "POP3LOGLEVEL", "maxmessages": "POP3MAXMESSAGES", "subject": "POP3SUBJECT", "messageid": "POP3MESSAGEID", diff --git a/internal/protocols/smtp/cmd.go b/internal/protocols/smtp/cmd.go index 8d875d4..62e4142 100644 --- a/internal/protocols/smtp/cmd.go +++ b/internal/protocols/smtp/cmd.go @@ -228,7 +228,7 @@ upgrades to TLS automatically, and logs the result (including TLS details) to CS cmd.Flags().String("bodyhtml", "", "HTML body content; combine with --body for multipart/alternative (env: SMTPBODYHTML)") cmd.Flags().String("attachments", "", "Comma-separated file paths to attach (env: SMTPATTACHMENTS)") cmd.Flags().String("inline-attachments", "", "Comma-separated file paths to embed inline via cid: (env: SMTPINLINEATTACHMENTS)") - cmd.Flags().StringArray("header", nil, "Custom header in 'Name: Value' form (repeatable)") + cmd.Flags().StringArray("header", nil, "Custom header in 'Name: Value' form (repeatable) (env: SMTPHEADER — comma-separated; avoid commas in header values)") cmd.Flags().String("priority", "normal", "Email priority: high, normal, low; high/low add X-Priority, Importance, and Priority headers (env: SMTPPRIORITY)") return cmd diff --git a/internal/protocols/smtp/config.go b/internal/protocols/smtp/config.go index b051493..ba0bebd 100644 --- a/internal/protocols/smtp/config.go +++ b/internal/protocols/smtp/config.go @@ -136,8 +136,8 @@ func RegisterPersistentFlags(cmd *cobra.Command) { f.Float64("ratelimit", 0, "Maximum SMTP requests per second (0 = unlimited) (env: SMTPRATELIMIT)") // Output - f.Bool("verbose", false, "Enable verbose output") - f.String("loglevel", "INFO", "Logging level: DEBUG, INFO, WARN, ERROR") + f.Bool("verbose", false, "Enable verbose output (env: SMTPVERBOSE)") + f.String("loglevel", "INFO", "Logging level: DEBUG, INFO, WARN, ERROR (env: SMTPLOGLEVEL)") f.String("output", "text", "Output format: text, json (env: SMTPOUTPUT)") f.String("logformat", "csv", "Log file format: csv, json (env: SMTPLOGFORMAT)") } @@ -179,6 +179,9 @@ func BindEnvs(v *viper.Viper) { "output": "SMTPOUTPUT", "logformat": "SMTPLOGFORMAT", "ratelimit": "SMTPRATELIMIT", + "verbose": "SMTPVERBOSE", + "loglevel": "SMTPLOGLEVEL", + "header": "SMTPHEADER", } for key, env := range bindings { _ = v.BindEnv(key, env)