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=2525andSMTP_SUBMISSION_PORT=2587move Corsair off the public ports so the terminator can take them.SMTP_BIND=127.0.0.1keeps 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.1lets the terminator say which address a session is really from, usingXCLIENT. 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=truetells 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 atmode: 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#
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:
sudo systemctl restart corsair
# or
docker compose up -dThere is no reload signal. A mail server that reconfigures itself mid-connection is a source of bugs nobody enjoys.