Mail setup & deliverability

Two separate concerns, two separate places: transactional email (signup confirmation, password reset, team invites, billing receipts) flows through admin-managed NotificationMailers. Customer campaigns flow through customer-managed DeliveryServers. Configure both before going live.

Architecture overview

Transactional mailer (required)

Without this configured, password resets, team invites, signup welcomes won't reach anyone.

1. Open Admin → Notifications → Mailers.
2. Edit the system mailer (or create a new one).
3. Fill in SMTP credentials. For Hostinger / Gmail / SES SMTP / SendGrid SMTP / etc:

   Provider	Host	Port	Encryption
   Gmail App Password	smtp.gmail.com	465	SSL
   Hostinger	smtp.hostinger.com	465	SSL
   AWS SES SMTP	email-smtp.us-east-1.amazonaws.com	587	STARTTLS
   SendGrid SMTP	smtp.sendgrid.net	587	STARTTLS
   Postmark SMTP	smtp.postmarkapp.com	587	STARTTLS
   Mailgun SMTP	smtp.mailgun.org	587	STARTTLS

4. From address — must be a mailbox you own on the provider. Verified domain only (DKIM/SPF set up).
5. Save. Click the Send test button on the mailer row.

Per-event mailer routing

Each notification event (welcome, billing, security alert) can route through a different mailer. Best practice:

• system — all user / auth events (welcome, password reset, 2FA, login alerts).
• billing — payment receipts, invoices, refund confirmations. Separate sender = trust signal for recipient.
• alerts — security alerts (new device, suspicious location, failed logins).

Edit each event at Admin → Notifications → Edit event → SMTP relay.

Customer campaign sending

Customers manage their own delivery servers under Customer → Sending relays. Available drivers:

DKIM, SPF, DMARC

The 3 DNS records that decide whether Gmail / Outlook / Yahoo trust your mail.

SPF

Tells receivers which servers may send for your domain. Owned by your SMTP relay.

; example.com TXT
v=spf1 include:_spf.mail.hostinger.com ~all

DKIM

KodMail generates an RSA-2048 keypair per sending domain. Add the domain at Customer → Sending domains → Add domain, then publish the TXT record shown:

; kodmail._domainkey.example.com TXT
v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ...

DMARC

Tells receivers what to do when SPF or DKIM fails. Start with p=none (monitor mode), graduate to quarantine / reject after two weeks of clean reports:

; _dmarc.example.com TXT
v=DMARC1; p=none; rua=mailto:[email protected]

Verification flow

1. Add the domain in KodMail.
2. Publish DKIM + SPF + DMARC at your DNS host (Cloudflare, Route 53, etc).
3. Click Verify DNS. KodMail polls the records; green check appears when all three pass.
4. Use the domain as the From on a List or Campaign.

Bounce processing

Set up an IMAP/POP3 inbox that receives bounce notifications (most relays send these back to the Return-Path):

1. Admin → Bounce inboxes → New (platform-wide) OR Customer → Bounce inbox (per-customer).
2. IMAP host, port (993 SSL or 143 STARTTLS), username, password.
3. Folder (usually INBOX).
4. Cron's bounces:process runs every 5 min — parses messages, classifies as hard / soft / complaint, auto-suppresses recipients.

Sending limits + warmup

Three layers of throttle:

• Per-customer plan limits — max_sends_per_month, max_sends_per_day, max_sends_per_hour at quota tier level.
• Per-relay throttle policy — global limit shared by every customer using that relay.
• IP warmup — gradual ramp curve for fresh dedicated IPs.

Smoke-test checklist

• Admin → Notifications → Edit "user.registered" → click Send test → email arrives in inbox (not spam).
• Customer → Sending domains → all 3 records show green.
• Customer → Lists → add a subscriber, send a single-recipient test campaign → arrives.
• Bounce a known-bad address → check Admin → Bounce logs within 5 min.
• mail-tester.com score 8/10 or higher.