Corsair

Install and operate

Configuration

Everything is configured through environment variables, read once at startup from the process environment or .env. There is no configuration file and no settings table — a mail server's behaviour should be reproducible from its deployment, not from a row somebody edited.

Defaults below are what the shipped code uses, not suggestions.

Core#

Variable Default What it does
DATABASE_URL postgres://corsair:corsair@localhost:55433/corsair PostgreSQL connection string
DB_POOL_SIZE 10 Connections in the pool
JWT_SECRET corsair-dev-secret-change-me Signs session tokens. Change this
PORT 3000 HTTP listener
HOST 0.0.0.0 Interface the HTTP listener binds
PUBLIC_URL http://localhost:3000 Base URL in emails and redirects
MAIL_WEBMAIL_HOST (empty) Optional CNAME target for customer webmail URLs; requires HTTPS proxy setup
SIGNUPS open open lets anyone sign up; closed allows only the first account
TRUSTED_PROXIES (empty) Proxies whose X-Forwarded-For is believed
METRICS_TOKEN (empty) Bearer token for GET /metrics; unset, the endpoint answers 404. See Monitoring

TRUSTED_PROXIES matters more than it looks. Behind a reverse proxy with it unset, every request appears to come from 127.0.0.1: the rate limiter sees one client, and the ban list bans your own proxy.

HOST defaults to 0.0.0.0 because a container that binds loopback is a container nothing can reach. If your reverse proxy runs on the same box, set it to 127.0.0.1. A firewall rule that closes port 3000 is a promise you have to keep on every rebuild; never listening on the public interface in the first place is not.

The mail listeners ignore HOST and always bind every interface. They are the ones the internet is supposed to reach.

Mail identity#

Variable Default What it does
CORSAIR_HOSTNAME mail.corsair.local The name this server gives in EHLO and stamps into Received headers

This must resolve to the IP you send from, and that IP must reverse-resolve back to it. Without that, the large providers reject on connect.

The next group is what the DNS Setup screen tells customers to point records at — the public names of this installation, not of the customer's domain. On a single-host install, point them all at the same name.

Variable Default
MAIL_MX_HOST mx1.corsair.local
MAIL_SMTP_HOST smtp.corsair.local
MAIL_IMAP_HOST imap.corsair.local
MAIL_POP_HOST pop.corsair.local
MAIL_SPF_HOST spf.corsair.local
MAIL_AUTOCONFIG_HOST autoconfig.corsair.local
MAIL_AUTODISCOVER_HOST autodiscover.corsair.local
MAIL_DKIM_HOSTS dkim-1.corsair.local,dkim-2.corsair.local,dkim-3.corsair.local

MAIL_DKIM_HOSTS is a comma-separated list of three. Customers publish a CNAME per selector pointing at these names and this server answers the lookup — three selectors let a key be rotated without a gap in signing.

DKIM rotation#

Variable Default Meaning
DKIM_ROTATE_DAYS 0 Start a rotation when the active key is this old. 0 never starts one
DKIM_SOAK_HOURS 48 How long a new key sits in DNS before anything signs with it
DKIM_RETIRE_DAYS 7 How long the replaced key stays published

Off by default because every rotation needs you to publish a TXT record, and an install that does that by hand should not find one begun under it. See Key rotation.

Listeners#

Variable Default (dev) Production
SMTP_MX_PORT 2525 25
SMTP_SUBMISSION_PORT 2587 587
SMTP_SUBMISSION_TLS_PORT 2465 465
SMTP_BIND 0.0.0.0 0.0.0.0; 127.0.0.1 behind the terminator
SMTP_TRUSTED_PROXIES empty empty; 127.0.0.1 behind the terminator
SMTP_STARTTLS_FRONTED false false; true behind the terminator
SMTP_PUBLIC_SUBMISSION_PORT the listening port 587
SMTP_PUBLIC_SUBMISSION_TLS_PORT the listening port 465
IMAP_PORT 2143 143
IMAP_TLS_PORT 2993 993
POP3_PORT 2110 110
POP3_TLS_PORT 2995 995
MANAGESIEVE_PORT 4190 4190
SMTP_ENABLED true
IMAP_ENABLED true
POP3_ENABLED true
MANAGESIEVE_ENABLED true

The defaults are unprivileged so development needs no root. Ports below 1024 need CAP_NET_BIND_SERVICE — granted in the systemd unit with AmbientCapabilities, or with setcap on the binary when running outside a service manager. See Installation; the two are not interchangeable.

The *_ENABLED flags accept true, 1, or yes. Turning listeners off is how you split the deployment.

STARTTLS on 25 and 587#

Corsair performs STARTTLS itself on any runtime that can upgrade a socket it accepted. It tests this at startup rather than assuming it, and never advertises what it cannot perform. Bun 1.4.4 passes the test, so on it the production column above is the whole story: Corsair listens on 25 and 587 directly.

engine/ is a small Rust process for a runtime that fails the test. It holds 25 and 587, performs the upgrade, and relays to Corsair on loopback, making no policy decisions of its own. Deploying it means changing four settings, and all four matter:

  • SMTP_MX_PORT=2525 and SMTP_SUBMISSION_PORT=2587 move Corsair off the public ports so the terminator can take them.
  • SMTP_BIND=127.0.0.1 keeps those listeners off the internet. Without it the backend still answers on a public address, which is a way to reach this server without TLS. Submission on 465 is unaffected — it has no plaintext phase.
  • SMTP_TRUSTED_PROXIES=127.0.0.1 lets the terminator say which address a session is really from, using XCLIENT. Leave it empty and every relayed message appears to come from loopback, which breaks SPF for everyone. Only list a proxy you run. Anything in this list can claim to be any sender.
  • SMTP_STARTTLS_FRONTED=true tells the server to describe itself accurately: it changes nothing about what Corsair does, but without it autoconfig steers clients away from 587 and the MTA-STS policy stays at mode: none.

SMTP_PUBLIC_SUBMISSION_PORT=587 is what clients are told to connect to, as opposed to what Corsair listens on.

TLS#

Variable Default What it does
TLS_CERT_PATH (empty) PEM certificate chain
TLS_KEY_PATH (empty) PEM private key

Used by the implicit-TLS listeners and by STARTTLS. Leave them empty to run plaintext-only, which is fine locally and unacceptable anywhere else — Corsair advertises LOGINDISABLED and refuses SMTP AUTH and IMAP LOGIN on an unencrypted connection when a certificate is configured.

See TLS certificates.

Built-in ACME#

Off unless you turn it on. For an install with no reverse proxy and no certbot; see Built-in ACME.

Variable Default What it does
ACME off on to obtain and renew the mail certificate over ACME. TLS_CERT_PATH/TLS_KEY_PATH are then ignored
ACME_EMAIL (empty) Contact address for the CA. Required with ACME=on
ACME_AGREE_TOS false Must be true with ACME=on: you agree to the CA's terms
ACME_DOMAINS CORSAIR_HOSTNAME Comma-separated names on the certificate
ACME_DIRECTORY Let's Encrypt production Staging: https://acme-staging-v02.api.letsencrypt.org/directory
ACME_DIR ./data/acme Account key and certificate, mode 0600
ACME_HTTP_PORT 0 Port for a challenge-only listener (normally 80). 0 means none: port 80 must then reach PORT

Delivery#

Variable Default What it does
DELIVERY_TRANSPORT console direct, relay, or console
SMTP_RELAY_HOST (empty) Smarthost, for relay
SMTP_RELAY_PORT 587
SMTP_RELAY_USER (empty)
SMTP_RELAY_PASS (empty)
SMTP_RELAY_SECURE starttls
DANE auto auto, on, or off. DANE for direct delivery; auto enables it only if the resolver is seen to validate DNSSEC at startup
DANE_RESOLVER (resolv.conf) Validating resolver whose AD bit is trusted, as host or host:port. Defaults to the first nameserver in /etc/resolv.conf
DANE_TRUST_REMOTE_RESOLVER false Accept a resolver that is not on loopback. Its AD bit can be forged in transit; see Deliverability
Transport Behaviour
direct Look up the recipient's MX and talk to it. Needs port 25 outbound
relay Hand everything to an upstream smarthost
console Print to stdout, deliver nothing. The default, for local development

Forwarded mail (ARC)#

Variable Default What it does
ARC_TRUSTED_SEALERS (empty) Comma-separated sealer domains whose ARC pass overrides a DMARC failure, e.g. google.com,outlook.com

Every inbound message has its ARC chain checked and the result recorded as arc= in Authentication-Results. That needs no configuration. This setting covers one decision: when a message fails DMARC but arrives with a passing ARC chain whose newest seal is from a listed domain (or a subdomain of one), the DMARC failure no longer counts against its spam score. The header still says dmarc=fail and notes the override, so it stays visible.

Anyone can seal a message, so a seal is worth only what you know about who made it. List the forwarders and mailing lists your users really receive through, and nothing else. See Forwarding.

Storage#

Variable Default What it does
STORAGE_BUCKET (empty) S3-compatible bucket. Empty keeps bodies in Postgres
STORAGE_REGION nyc3
STORAGE_ENDPOINT (empty) e.g. https://nyc3.digitaloceanspaces.com
STORAGE_ACCESS_KEY_ID (empty)
STORAGE_SECRET_ACCESS_KEY (empty)
STORAGE_PREFIX corsair Key prefix inside the bucket

Objects are written with no ACL and inherit the bucket's default. Check that default is private before pointing Corsair at a bucket you already use.

Workers#

Variable Default What it does
WORKER_CONCURRENCY 8 Jobs processed at once
WORKER_POLL_MS 1000 How often the queue is polled when idle

The queue claims work with FOR UPDATE SKIP LOCKED, so any number of worker processes can drain it without coordinating and without delivering anything twice. Raise concurrency before adding processes.

Payments#

Variable Default What it does
STRIPE_SECRET_KEY (empty) Enables hosted checkout
STRIPE_WEBHOOK_SECRET (empty) Verifies settlement webhooks

Leave both empty and Corsair runs unmetered: plans still gate features and an operator can record payment methods by hand, but nothing is charged. That is the right default for hosting mail for yourself.

Card details never reach this server. The customer enters them on the provider's hosted page; a brand, four digits, and an opaque reference come back. There is no code path here that could accept a card number.

Spam filtering#

Variable Default What it does
SPAM_DNSBL zen.spamhaus.org IP blocklists checked against the connecting client on port 25. Comma-separated; empty disables
SPAM_URIBL dbl.spamhaus.org Domain blocklists checked against the sender's domains and up to 20 link domains. Comma-separated; empty disables
SPAM_DNSBL_REJECT false Refuse clients on SBL, CSS, DROP, or XBL at RCPT instead of only scoring them
SPAM_RESOLVER system resolver Resolver addresses for blocklist queries. Spamhaus refuses public and cloud resolvers, so set this to a local one
SPAM_GREYLIST false Defer first contact from an unknown client, sender, and recipient with 451 4.7.1
SPAM_GREYLIST_DELAY 300 Seconds a greylisted sender must wait before its retry is accepted

If the log says a list "refused a query", blocklists are doing nothing until SPAM_RESOLVER points at a resolver the list will answer. See Spam filtering for what each setting scores and why the defaults are what they are.

Mailbox transfers#

Variable Default Purpose
TRANSFER_ALLOW_PRIVATE false Allow transfer sources on a trusted private network; verified TLS is still required

Webhooks#

Variable Default What it does
WEBHOOK_ALLOW_PRIVATE false Allow endpoints on private, loopback, and link-local addresses

The customer supplies the URL and this server fetches it, which is a server-side request forgery primitive. Corsair resolves the host and refuses private ranges by default, and does not follow redirects. Turn it on only when your consumers are genuinely on the same private network.

Limits#

Variable Default What it does
RATE_LIMIT_PER_SECOND 10 API requests per second, per principal
MAX_MESSAGE_BYTES 26214400 25 MB. Advertised in the SMTP SIZE extension. Raising it costs memory: the pipeline holds several copies of a message at once

Authenticated requests are limited per user; unauthenticated ones per IP. Sign-in and sign-up have their own tighter limit of 5 per second per IP, since there is no principal yet.

A 429 carries retry-after, ratelimit-limit, ratelimit-remaining, and ratelimit-reset.

MAX_MESSAGE_BYTES is the wire size after encoding. Base64 costs about a third, so 25 MB on the wire is roughly an 18 MB attachment.

Authentication reports#

Variable Default What it does
DMARC_REPORTS_SEND true Record inbound DMARC results and send daily aggregate reports
TLSRPT_SEND true Record outbound TLS outcomes and send daily TLS reports
REPORTS_DAILY_CAP 1000 Reports of each kind sent per UTC day
REPORTS_FROM noreply-dmarc@<CORSAIR_HOSTNAME> Sender of outgoing reports. Put it on a hosted domain so reports are DKIM-signed

See Deliverability.

Seeding#

Variable Default What it does
SEED_PASSWORD corsair-dev-password Password for the account scripts/seed.ts creates

Read only by the seed script. Set it on any host that is not your laptop.

A production starting point#

sh
DATABASE_URL=postgres://corsair:LONG_PASSWORD@localhost:5432/corsair
JWT_SECRET=<openssl rand -base64 48>
PUBLIC_URL=https://mail.example.com
HOST=127.0.0.1
SIGNUPS=closed
TRUSTED_PROXIES=127.0.0.1

CORSAIR_HOSTNAME=mail.example.com
MAIL_MX_HOST=mail.example.com
MAIL_SMTP_HOST=mail.example.com
MAIL_IMAP_HOST=mail.example.com
MAIL_POP_HOST=mail.example.com
MAIL_SPF_HOST=mail.example.com
MAIL_AUTOCONFIG_HOST=mail.example.com
MAIL_AUTODISCOVER_HOST=mail.example.com
MAIL_DKIM_HOSTS=dkim-1.mail.example.com,dkim-2.mail.example.com,dkim-3.mail.example.com

SMTP_MX_PORT=25
SMTP_SUBMISSION_PORT=587
SMTP_SUBMISSION_TLS_PORT=465
IMAP_PORT=143
IMAP_TLS_PORT=993
POP3_PORT=110
POP3_TLS_PORT=995

TLS_CERT_PATH=/etc/corsair/certs/fullchain.pem
TLS_KEY_PATH=/etc/corsair/certs/privkey.pem

DELIVERY_TRANSPORT=direct

STORAGE_BUCKET=my-mail-bucket
STORAGE_REGION=nyc3
STORAGE_ENDPOINT=https://nyc3.digitaloceanspaces.com
STORAGE_ACCESS_KEY_ID=...
STORAGE_SECRET_ACCESS_KEY=...

Then walk the production checklist.

Changing configuration#

Every value is read at startup. Restart after any edit:

sh
sudo systemctl restart corsair
# or
docker compose up -d

There is no reload signal. A mail server that reconfigures itself mid-connection is a source of bugs nobody enjoys.