Self-hosting
Email server
Connect an SMTP server so the Viewer can send comment mentions, sign-in links, and invites, with settings for common providers.
The Viewer sends email for three things: comment mentions (someone @-mentions you on a project), sign-in links (magic links, when email sign-in is enabled), and invites (so a new member gets their link directly). None of them are sent until an email server is connected. Everything else works without one.
It connects over plain SMTP, so any mailbox or email provider that offers SMTP credentials works.
Two ways to configure it#
- In the product: Settings → Viewer settings → Email server. An Admin fills in the five fields below and saves. This is the usual path.
- Environment variables:
VIEWER_SMTP_HOST,VIEWER_SMTP_PORT,VIEWER_SMTP_USER,VIEWER_SMTP_PASS,VIEWER_SMTP_FROM. SettingVIEWER_SMTP_HOSTrequires the user, password, and from address too, and it wins: the in-product form shows the values but can't change them.
The fields#
| Field | What it is |
|---|---|
| Server | The provider's SMTP hostname, e.g. smtp.gmail.com. |
| Port | Almost always 587. Port 465 also works and uses implicit TLS; every other port upgrades the connection with STARTTLS. |
| Username | The account the Viewer signs in to the mail server as. For some providers this is a literal word like apikey, not an address. |
| Password | The SMTP password or API key. Stored on your server and never shown again; leaving the field blank on a later save keeps it. |
| From address | What appears in the recipient's inbox as the sender. Some providers require it to be a verified address or domain. |
Common providers#
Transactional email services are the easiest fit: their credentials are made for exactly this, and deliverability is their whole job.
| Provider | Server | Port | Username | Password |
|---|---|---|---|---|
| Resend | smtp.resend.com |
587 | resend |
an API key |
| Postmark | smtp.postmarkapp.com |
587 | the Server API token | the same token |
| SendGrid | smtp.sendgrid.net |
587 | apikey |
an API key |
| Mailgun | smtp.mailgun.org |
587 | an SMTP user from the dashboard | its SMTP password |
| Amazon SES | email-smtp.<region>.amazonaws.com |
587 | SMTP credentials | SMTP credentials |
With these, the From address must be one you have verified with the provider (usually a domain you own).
A regular mailbox also works:
- Gmail / Google Workspace: server
smtp.gmail.com, port 587. Your normal password will not work: create an app password (requires 2-step verification on the account) and use that, with your full address as the username and the From address. - Outlook / Microsoft 365: server
smtp.office365.com, port 587, your full address as the username. SMTP AUTH is disabled on many tenants by default; an admin may need to enable it for the mailbox.
A dedicated mailbox (e.g. reviews@yourcompany.com) is better than a personal one: replies and bounces land somewhere shared, and rotating a person's password doesn't silently stop the mail.
Checking it works#
Create an invite from Settings → Members → Add member. The reveal says whether the email actually went out; a failed send still creates the invite and shows you the link to pass on by hand. Mentions behave the same way: the comment always lands, the email is best-effort.