GitBlixt
Docs Navigation

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 — use port 587 with the credentials from your provider's SMTP settings page.

Resend

Resend can be used through its API instead of SMTP, and GitBlixt sets up the sending domain for you:

  1. At resend.com → API Keys, click Create API key, name it GitBlixt and give it Full access (GitBlixt registers the From domain with it). Copy the key; it starts with re_ and is shown only once.
  2. Under Admin → Settings → Email, click Configure (or Edit), set Send with to Resend API, and enter the key and the From email.
  3. Save. GitBlixt registers the From address's domain with Resend (or uses the one already in your Resend account) and lists its DNS records. Add them at your DNS provider and click Check DNS; Resend only sends once the domain is verified. Then click Send Test.

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), Resend's verdicts in Resend mode (a DMARC pass for the From domain, or an SPF pass for the Return-Path domain; Resend names no DKIM signer, so a DKIM pass alone doesn't count), 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.vianet.us/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.

Resend

  1. At resend.com → API Keys, create an API key with Full access and copy it (it starts with re_ and is shown only once).
  2. Pick a domain for the board addresses that doesn't already receive mail elsewhere, such as ideas.example.com: Resend's MX record takes over its mail.
  3. Choose the Resend mode, enter the domain, the key and the region for a new domain, and save. GitBlixt registers the domain with Resend with receiving on (or turns receiving on for your existing one) and subscribes https://git.vianet.us/inbound/resend to received mail.
  4. Add the DNS records the card lists (the receiving MX record and DKIM) and click Check DNS until Resend reports the domain verified.

GitBlixt checks each webhook's signature, fetches the original message from Resend and processes it like any other; a message over 5 MB is logged as rejected from the headers Resend reported. Saving the settings again replaces the webhook.

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.