Email Configuration

Email is optional but recommended. GitBlixt uses email for account confirmation, password resets, and notifications.

This is GitBlixt's own email. To send email from an app you deploy, see App Deployment.

Configuration

Configure SMTP under Admin → Settings → SMTP; it applies without a restart. On a fresh install, these environment variables are used until it is set there:

SMTP_HOST=smtp.yourmailprovider.com
SMTP_PORT=587
SMTP_USERNAME=your-smtp-username
SMTP_PASSWORD=your-smtp-password
[email protected]

Provider Examples

AWS SES (recommended for self-hosters)

SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USERNAME=<SES SMTP username>
SMTP_PASSWORD=<SES SMTP password>

Gmail (for low-volume testing only)

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=<app password>  # not your account password

Postmark, Mailgun, Resend — use port 587 with the credentials from your provider's SMTP settings page.

Inbound mail (Ideas)

Inbound mail lets board editors email ideas and comments to a board's address, ideas+<token>@<domain> (see Ideas). Set it up under Admin → Settings → Inbound mail (Ideas): choose a mode, and enter the domain the addresses use. Every message received is listed in the inbound log there, with what became of it.

Require sender authentication (on by default) takes mail only when the sender's domain passed DMARC, or SPF or DKIM for that domain (or a subdomain of it): SES's verdicts in SES mode (for DKIM, the signers SES reports in its own Authentication-Results header), and in IMAP mode the top-most Authentication-Results header written by your mail provider, which you name by its authserv-id (the first word of the header, e.g. mx.google.com; Microsoft 365 omits the authserv-id, so enter none); a header that reports a DMARC fail counts for nothing, whatever else passed. Anyone can put such a header in a message, so only your provider's counts, and only if it adds its own to every message it receives. In IMAP mode the settings aren't saved without an authserv-id while sender authentication is on, and the mailbox isn't polled while it's blank. Turn sender authentication off only if your mailbox provider already rejects spoofed mail. A message whose From holds more than one address, or that's over 5 MB, is rejected.

IMAP

GitBlixt polls a mailbox every minute. Create a mailbox that receives all mail for the domain (a catch-all, or a provider that delivers ideas+anything@ to ideas@), then enter its IMAP host, port, TLS setting, username, password, folder and the authserv-id of its Authentication-Results headers (open a message's headers in the mailbox to find it). Processed messages are marked read, or deleted if you tick that box; one that can't be processed is tried again on the next polls, and given up on after 3 tries. A message over 5 MB is logged as rejected from its headers alone, and one the server won't hand over is marked read and skipped. Test connection checks the login.

Amazon SES

1. In SES (in a region that receives email), verify the domain and point its MX record at inbound-smtp.<region>.amazonaws.com.
2. Create an S3 bucket for the mail and an SNS topic; save the region, bucket, optional key prefix and topic ARN in the settings.
3. Add an HTTPS subscription to the topic for https://git.michlp.com/inbound/ses (the settings page shows it too). GitBlixt verifies the SNS signatures and confirms the subscription itself.
4. Create a receipt rule for the domain with an S3 action that stores mail in that bucket and prefix and notifies the topic.
5. Save the access key of an IAM user that may s3:GetObject in the bucket.

Mail that fails SES's spam, virus, SPF or DKIM checks, or DMARC under a reject policy, is logged and dropped. The S3 object must be in the bucket and key prefix above.

Running Without Email

If SMTP_HOST is not set, GitBlixt operates without email. Account confirmation is skipped, and password resets must be performed by an administrator through the admin panel.