Configuration

Mailyard reads ./mailyard.yaml (override with --config) and every key can also be set as an environment variable. The variable name is the YAML path, uppercased, with dots replaced by underscores and a MAILYARD_ prefix — server.public_url is MAILYARD_SERVER_PUBLIC_URL. Environment wins over the file, and the file is optional, so a deployment can be configured entirely from the environment.

Put secrets in the environment rather than the file: MAILYARD_AUTH_JWT_SECRET, MAILYARD_DATABASE_CRYPTO_ENCRYPTION_KEY, MAILYARD_DATABASE_DSN and MAILYARD_RELAY_NODES_AUTO_REGISTER_TOKEN.

Server

The console frontend and the documentation you are reading are compiled into the binary, so there is no asset path to configure.

Database (PostgreSQL)

PostgreSQL is the only supported engine. One connection string, no host/port/user parts - put it in MAILYARD_DATABASE_DSN rather than YAML so the password stays out of the config file.

database:
    dsn: postgres://mailyard:secret@localhost:5432/mailyard?sslmode=disable

Migrations run automatically at startup (goose, embedded in the binary), so a fresh empty database is all the service needs.

PostgreSQL is the only service to configure: it holds the delivery queue and is how several nodes coordinate - see Scaling out .

Logging

One sink, written exactly where you point it.

An invalid format or level fails at startup rather than falling back, because a silent fallback to human-readable text produces a log your shipper cannot parse and never says why.

The first-run bootstrap password is written straight to stderr, not through the logger, so it is still visible when logs are directed to a file.

Authentication

Single sign-on is configured per provider in the console under Admin → OAuth Providers, not through the environment, because the settings are stored in the database and editable at runtime. See OAuth Providers .

Encryption at rest

Required. Mailyard refuses to start without it.

Changing it later orphans every row already sealed under the old key, so treat it like a database credential.

A stored value is base64(nonce||ciphertext) and nothing else.

Amazon SES notifications

SES replaces the envelope sender with its own, so no return path can collect its bounces. It reports over SNS instead. See Bounce Handling .

There is nothing to configure here. POST /webhooks/ses always exists, and the SNS topic ARN is set on the SMTP server that uses SES — under SMTP Servers, or Shared SMTP Pool for a platform-owned one.

That is deliberate. SES belongs to one server: a project configures its own SES account as its own server, so a platform-wide list could only ever serve an operator who owned the account themselves, and a tenant had no way to register a topic at all.

The endpoint is public, because SNS presents no session and no API key. Two things authenticate a notification, and it needs both: the SNS signature, verified against a certificate fetched only from sns.<region>.amazonaws.com, and the topic being configured on a server. The signature alone proves Amazon sent the message, not that your account did — anyone can open an AWS account and point a topic at your URL.

With no server carrying a topic, nothing is accepted. That is why the endpoint needs no switch: it gates itself on the data.

A notification is additionally required to be about a message that actually left through a server publishing to that topic. Attribution still comes from the X-Mailyard-Email-Id header — this is what stops one tenant’s topic reporting on another tenant’s mail.

Metrics

Rate Limiting

Fixed-window counters held in process memory, so on a multi-node deployment the effective ceiling is the value here times the node count. Size accordingly, or terminate the limit at a shared proxy instead. Zero on an individual limit disables just that one.

Per-project sending volume is a separate mechanism: it comes from the plan assigned to the project, not from configuration. See Plans . The SMTP listeners have their own per-IP session limits, MAILYARD_SUBMISSION_RATE_PER_MINUTE and MAILYARD_INBOUND_RATE_PER_MINUTE.

Worker

The delivery worker runs inside the server process, so there is nothing to enable. Running more nodes runs more workers - every serve node claims from the same queue.

Exactly one node carries --init, which applies pending migrations. The rest start without it and skip goose entirely. Two nodes migrating an empty database at the same time race, and a node that starts before anybody has applied the schema says so rather than failing on the first query. See Scaling out .

These settings are per node. Three nodes at concurrency 4 give you twelve parallel deliveries, not four.

Campaigns

Webhooks

Delivery

Email Verification

Controls the POST /api/v1/emails/verify endpoint: syntax, disposable and role-account checks, and an MX lookup with an A/AAAA fallback per RFC 5321. Off by default because the MX check makes outbound DNS queries, which an operator on a locked-down network should opt into rather than discover. Results are cached in process memory, so each node builds its own cache and the TTLs below are per node.

There is deliberately no SMTP probe, so mailbox_verified is always false. See Email Verification for why.

Platform mail

The platform’s own outbound mail: project invitations, password resets, signup confirmations and alerts. It is sent as a message of a project you name, through that project’s servers and DKIM key, marked as system mail so it never consumes the project’s plan quota, appears in its email log, or fires its webhooks.

There is nothing to configure here. Both the address and the project are platform settings rather than config:

They are settings and not config keys on purpose: the project beside them is edited in the console by the same administrator, and a value that needs a restart to correct is the one thing they cannot fix when it is wrong.

platform_mail_from requires MAILYARD_SERVER_PUBLIC_URL, since every link it sends is absolute — and that requirement is checked at the moment somebody writes the address, which is where it is actionable.

Until both are set, invitations still work — the console returns a copyable link instead — but password reset is not offered at all. Status and a test live at GET/POST /api/v1/admin/system-mail[/test]. See Platform Mail .

Relay nodes

A relay node is a machine somewhere else — often another provider, often another continent — that delivers straight to recipient mail exchangers from its own address, and can run an MX of its own. Two config blocks, and they point in opposite directions.

The control plane, on an API node

A leaked token is not a disaster on its own: enrolment lands in pending, and a node carries no mail until somebody approves it. Whether that approval is automatic is the relay_nodes_auto_approve platform setting, off by default.

A project’s own node enrols with an API key carrying relay:enroll instead of this token, and is approved by an administrator of that project.

The node itself

Read only by mailyard relay. A node ships neither the database DSN nor the encryption key.

IPv6 is off by default, and that default is the point: a box with a AAAA address will happily prefer v6, where receivers want a PTR and SPF coverage a v4-only setup does not have, and the mail is refused for reasons that look nothing like the cause.

The control channel is plain HTTPS with a nil transport, so HTTPS_PROXY, ALL_PROXY and SOCKS5 work with no configuration — which is the whole point for a node behind a national firewall or a VPN.

A node that also receives

Point the MX record at the node rather than at Mailyard. See Relay Nodes .

Sending Limits

Caps applied to every send, on both the console API and the machine API.

See Attachments for the request shape and the GET /api/v1/emails/limits endpoint that reports the effective values.

Sender Authentication

Outbound mail is DKIM signed automatically for every domain a project has verified. Keys are RSA-2048, generated when ownership verifies, and the private half is encrypted with database.crypto.encryption_key before it reaches the database. There is no variable to turn signing on: a verified domain with a key gets signed mail.

Inbound mail is always authenticated and the verdict always stored. MAILYARD_INBOUND_REJECT_ON_DMARC_FAIL only decides whether a failure is also a refusal. See Domain Verification .

Attachment Storage

Where attachment bytes live. The default keeps them inline as base64 in the database, which needs no configuration at all. The fs and s3 backends move the bytes out and store only metadata plus a storage key.

Inbound Email

Recipients are gated at RCPT TO on domains the project verified by DNS TXT — there is no authentication on this listener, and mail for anything unclaimed is refused. See Inbound Email .

SMTP submission

Outbound submission for applications that speak SMTP rather than HTTP. Off by default, MAILYARD_SUBMISSION_ENABLED=true turns it on and MAILYARD_SUBMISSION_ADDR defaults to :587. The full table, including AUTH and STARTTLS, is in SMTP Submission .

CORS

Off by default, and it should stay off unless something needs it: the console is served from the same origin as the API, so it never does. This exists for a separately hosted front end or a browser-based integration.

cors:
    enabled: true
    allowed_origins:
        - https://app.example.com
    allow_credentials: true

The configuration is checked at startup and the server refuses to boot on these, rather than leaving you to debug a silent browser rejection:

• enabled with no origins listed.
• An origin without a scheme (app.example.com instead of https://app.example.com).
• allowed_origins: ["*"] together with allow_credentials: true - browsers reject that combination anyway, and configuring it means somebody expected cookies to work.

TLS

Two separate questions, answered in two separate places, and keeping them apart is the point.

Whether a listener terminates TLS is configuration. It is a port-level decision — the common deployment puts a reverse proxy in front that terminates TLS and speaks HTTP upstream — and it needs a restart either way.

The HTTP default differs from the two SMTP ones deliberately. On 25 and 587 a client prefers encryption and almost none verify the certificate, so even a self-signed pair is a real improvement over cleartext. In front of the console there is usually a proxy, and terminating here would make it talk HTTPS upstream to a certificate it has no reason to trust. Relay nodes are the sharper half of that: a node verifies this certificate with its system trust store, so turning SERVER_TLS_ENABLED on with a self-signed pair stops every node enrolling until you install the root on each machine.

Which certificate is served is not configured in this file. It is assigned in the console under Administration → Certificates, stored in the database, and resolved per handshake — so a replacement takes effect with no restart and reaches every node. Each listener walks one chain:

1. the certificate assigned to it, if any
2. the ACME certificate, if ACME is configured for that hostname
3. a self-signed pair, generated on first use and shared by every node

A listener always has something to present, and an unreachable console is recoverable with mailyard tls unassign --listener server, which writes to the database with no server running.

ACME

Whether to order from Let’s Encrypt, for which hosts and under which account are platform settings (acme_enabled, acme_hosts, acme_email, acme_directory_url), set in the console under Administration → Certificates and read fresh on every handshake and every order. None of them is in this file.

One key is here, because it binds a port:

Empty is right whenever the CA can reach this process’s own TLS handshake. Behind a proxy that terminates TLS, set it to an address the proxy forwards /.well-known/acme-challenge/* to - see Certificates . The port is bound at startup whether ACME is on or not.

A name that is not in acme_hosts falls through to the self-signed pair rather than failing the handshake. That is the ordinary state of an MX: the list is what somebody typed for the console, and the mail listeners may answer under a different hostname.

Issued certificates are stored in the database, so every node serves the same one and a restart re-issues nothing. Renewal happens about 30 days before expiry, and Mailyard touches each configured host at startup and hourly after that, so a listener that has seen no traffic still renews.

Example environment

# Server
MAILYARD_SERVER_ADDR=:3000
MAILYARD_SERVER_PUBLIC_URL=https://mail.example.com
MAILYARD_SERVER_TRUSTED_PROXIES=10.0.0.0/8

# Database
MAILYARD_DATABASE_DSN=postgres://mailyard:secure-password@localhost:5432/mailyard?sslmode=require

# Secrets - generate both with `openssl rand -hex 32`
MAILYARD_AUTH_JWT_SECRET=...
MAILYARD_DATABASE_CRYPTO_ENCRYPTION_KEY=...

# Sign-in
MAILYARD_AUTH_LOCAL_ENABLED=true
MAILYARD_AUTH_LOCAL_EMAIL=admin@example.com

# HTTPS here rather than at a proxy. Which certificate is served, and
# whether Let's Encrypt is asked for one, is chosen in the console.
MAILYARD_SERVER_TLS_ENABLED=true

# Optional SMTP listeners, both off unless enabled
MAILYARD_SUBMISSION_ENABLED=true
MAILYARD_INBOUND_ENABLED=true

# Observability
MAILYARD_LOGGING_FORMAT=json
MAILYARD_METRICS_ENABLED=true
MAILYARD_METRICS_TOKEN=...

On first start against an empty database the bootstrap admin password is written to stderr once. Migrations run automatically, so nothing else is needed.

Platform mail — invitations, password resets, signup confirmations — is not in this list because it is not configured here. Create the project it is sent as, verify its domain, and set platform_mail_from and platform_mail_project in Admin → Settings. See Platform mail .