Skip to main content
Open console

OpenSMTPD

Outbound mail relay for environments not using a hosted provider

3 min read

Outbound mail relay. Every site gets one, and your application reaches it at SMTP_HOST (see Variables).

A Drupal site using settings.vallic.php is pointed at it already and needs nothing.

Two ports, two hops

Hop Port Notes
Your site to the relay 25, inside the stack Stays on the environment's private network; nothing blocks it.
The relay to the world 587, through your provider STARTTLS to the relay host you set.

Mail waits in the queue and never arrives unless you set a relay host. Without one, the relay tries to deliver straight to each recipient's mail server, which is always port 25. Port 25 to the internet is refused on every machine, as 465 is (see Machines). Set a relay host for any environment that sends mail.

Relaying through your own provider

version: 1
type: drupal

services:
  - mariadb: '11.8'
  - opensmtpd:
      version: '7.8'
      environment:
        RELAY_HOST: smtp.sendgrid.net
        RELAY_PORT: '587'
        RELAY_USER: apikey

The password does not go here. Anything set on a service is stored where a task can be read from. Add RELAY_PASSWORD as a secret project variable instead: it is encrypted at rest and never shown again.

The relay is the one service that reads a variable of that name. Any other variable reaches only your application: RELAY_HOST set on the Variables page leaves the relay without one, and mail waits in its queue.

RELAY_PORT defaults to 587 and RELAY_PROTO to smtp+tls (STARTTLS). For most providers you write only RELAY_HOST and RELAY_USER.

To give one environment its own relay, such as a staging account or a test inbox, set it on that environment's Variables page under Service settings. It overrides vallic.yaml. See Service settings.

Provider RELAY_HOST RELAY_USER RELAY_PASSWORD
SendGrid smtp.sendgrid.net apikey, literally An API key
Mailgun smtp.mailgun.org (smtp.eu.mailgun.org in the EU) The domain's SMTP login Its SMTP password
Postmark smtp.postmarkapp.com A server API token The same token
Amazon SES email-smtp.<region>.amazonaws.com SMTP credentials made in SES — not an IAM access key Their password
Brevo smtp-relay.brevo.com Your SMTP login An SMTP key
Mailjet in-v3.mailjet.com An API key Its secret key
MailerSend smtp.mailersend.net The domain's SMTP user Its password

Check the values against your provider's own page; these are where each publishes its relay today. All of them take 587.

Port 465 is refused on every machine (see Machines). For a provider that offers only implicit TLS, set RELAY_PROTO: smtps and, as RELAY_PORT, the other port it publishes for that (2465, say).

Deliverability is still yours

The relay sends what it is given. Whether mail arrives depends on SPF, DKIM and DMARC records on the domain you send from. Those live in your DNS, so you publish them; your provider tells you which it needs.

Versions

Version Status
7.8 Supported, and the default

Pin the version, not the build: name 7.8 and the platform matches it to the current build, so a security rebuild reaches you without anybody editing a repository.

What you can change

In vallic.yaml — what each one does is on Service settings:

services:
  - opensmtpd:
      version: '7.8'
      environment:
        RELAY_HOST: …
        RELAY_PORT: …
        RELAY_PROTO: …
        RELAY_USER: …
        OPENSMTPD_MAX_MESSAGE_SIZE: …
        OPENSMTPD_EXPIRE: …
        OPENSMTPD_BOUNCE_WARN: …

Anything not on this list refuses the deploy, naming the variable — rather than being accepted and quietly ignored.

Need a hand?

Open a ticket from Support in the console. We answer on the ticket.

Open the console How support works