This site is self-hosted on HomeFree — running everything you see, on the same box.

Outbound Email

Some apps on your HomeFree box want to send email — a signature request from Documenso, a "verify your email" message when someone signs up, a notification from Forgejo when an issue is assigned to you. The Email page in the admin UI (under System) gives all of them one shared way to do that: an outbound SMTP relay.

A relay is simply an existing mail service that agrees to send mail on your behalf. HomeFree does not run its own mail server — running one at home is a losing battle against spam filters. Instead, you point HomeFree at a mail account you already have (Proton Mail, a transactional mail service, your mail host's submission server), and apps hand their outgoing messages to it.

If you never configure this page, nothing breaks — apps that would send mail simply don't. Documenso auto-verifies new signups instead of emailing a confirmation link, and Forgejo skips notification mail.

The settings

Field What it is
Send app email through this relay The master switch. Off = apps behave as if no email exists.
SMTP Host The relay's hostname, e.g. smtp.protonmail.ch.
Port Usually 587 (STARTTLS) or 465 (implicit TLS).
Username The account you authenticate as — usually your sending email address. Leave blank only for an unauthenticated relay on your own network.
Transport Security STARTTLS for port 587, Implicit TLS for port 465. None is only for a relay on the box itself or a trusted LAN.
From Address The address mail is sent as. Most providers require this to match the authenticated account.
From Name The display name next to the address. Individual apps substitute their own (e.g. "Documenso").
SMTP Password / Token The account password or app token. It is encrypted into HomeFree's secrets store — it never appears in the config file, and you'll see a "Set" badge once stored.

After filling the form, use Send test email with your own address. The test uses the values currently on the page plus the stored password, so you can verify credentials before applying the configuration. Apps only start using the relay after you Apply and the box rebuilds.

Using Proton Mail

Proton doesn't accept normal SMTP logins with your account password. On paid plans with a custom domain, you can generate an SMTP submission token instead:

  1. In the Proton web app, open Settings → All settings → IMAP/SMTP → SMTP tokens.
  2. Click Generate token, name it (e.g. homefree), and pick the custom-domain address it sends as.
  3. Copy the token immediately — Proton shows it only once.

Then on the Email page:

  • SMTP Host: smtp.protonmail.ch
  • Port: 587
  • Transport Security: STARTTLS
  • Username: your custom-domain address (the one you picked for the token)
  • From Address: the same address
  • SMTP Password / Token: paste the token

Free Proton accounts and accounts without a custom domain can't generate SMTP tokens. Support for those accounts via a bridge is planned but not available yet.

Using another provider

Any SMTP submission endpoint works the same way:

  • Transactional mail services (the kind developers use for app email) give you an SMTP hostname, a port, and a username/API-key pair — enter them directly.
  • A mailbox you already own usually exposes a submission server (often smtp.<your-host> on port 587 or 465) using your mailbox credentials. Some providers require an app-specific password instead of your login password.
  • A mail server on your LAN can be used with None transport security if it doesn't speak TLS — never do this across the open internet.

What uses the relay today

  • Documenso — signup verification and document-signing emails. Without a relay, Documenso auto-verifies accounts so signups don't get stuck; with a relay, real verification emails flow.
  • Forgejo — issue/PR/actions notification mail. Sign-in stays SSO-only either way.
  • Snipe-IT — alerts and notification mail.

More apps (and HomeFree's own alert notifications) will pick the relay up over time.

Troubleshooting

  • "Authentication failed" — the username/password pair is wrong, or the provider wants a token/app-password rather than your login password (Proton always does).
  • The test email arrives twice — you sent it to the same account it sends from. Your mailbox then holds both the Sent copy and the delivered Inbox copy, and conversation view shows them together. It was one send (the copies share a Message-ID); a test to any other address arrives once.
  • "Sender address rejected: not owned by user" (or any refusal mentioning the sender) — set From Address to match Username. Proton tokens only send as the address they were generated for.
  • "Relay refused the destination/sender" — most providers only send when the From Address matches the authenticated account. Check the From Address field.
  • Test works but an app's mail doesn't arrive — apps pick up the relay on Apply/rebuild, not immediately; check the app was restarted since the relay was configured. Then check the recipient's spam folder — new sender domains often land there.