====== Email and SMTP ======

Transactional email for folk.zone services: registration confirmations, password resets, opted-in notifications. Getting it wrong means broken signups and spam-folder delivery.

===== Provider =====

All services send through [[https://resend.com|Resend]] over SMTP:

<code>
Host: smtp.resend.com
Port: 587 (STARTTLS)
Username: resend
Password: <API key>
</code>

The API key is shared through the ''RESEND_API_KEY'' environment variable in the server Compose file and the environment ''~/.env'' on casa. Free tier is 3,000 emails/month, 100/day.

===== DNS Records =====

The ''folk.zone'' domain is verified in Resend. DNS lives at Porkbun; the required records are:

^ Type ^ Host ^ Value ^
| TXT | ''resend._domainkey'' | DKIM public key, copied from the Resend domain dashboard |
| MX | ''send'' | ''feedback-smtp.us-east-1.amazonses.com'', priority 10 |
| TXT | ''send'' | ''v=spf1 include:amazonses.com ~all'' |

The MX and TXT records on ''send'' coexist with the existing ''send.folk.zone'' A record for the file-sharing service. If the domain ever shows "failed" status in Resend, trigger re-verification with ''POST /domains/{id}/verify'' against the API.

Recommended addition: DMARC as a TXT record on ''_dmarc'': ''v=DMARC1; p=quarantine; rua=mailto:dmarc@folk.zone; pct=100''.

===== Per-Service Configuration =====

^ Service ^ Mechanism ^ Sender ^
| WriteFreely (write) | ''WRITEFREELY_SMTP_*'' env vars | configured in WriteFreely config |
| Rallly (meet) | ''SMTP_*'' env vars | ''noreply@folk.zone'' |
| Kutt (go) | ''MAIL_*'' env vars | ''noreply@folk.zone'' |
| DokuWiki (wiki) | [[https://www.dokuwiki.org/plugin:smtp|smtp plugin]] + ''local.php'' | ''noreply@folk.zone'' |
| Mastodon | ''SMTP_*'' env vars | ''notifications@folk.zone'' |
| Forgejo (git) | ''FORGEJO__mailer__*'' env vars | ''git@folk.zone'' |

The DokuWiki container has no MTA, so it needs the plugin. Its config keys are ''plugin.smtp.auth_user'' and ''auth_pass'', not ''smtp_user''/''smtp_pass''. Use ''smtp_ssl = tls'' for port 587.

HedgeDoc runs anonymous-only and does not send mail. IT-Tools, CyberChef, Send, ArchiveBox, and EtherCalc have no account system and send nothing.

===== Registration Spikes =====

Open or semi-open registration can exhaust a 100/day free tier in an hour. Mitigations:

  * Enable the app's email queue where it exists (Mastodon and WriteFreely both support rate-limiting outbound mail)
  * Stagger invite sends; do not issue 500 invites at once
  * Monitor the provider dashboard and alert near the daily limit

===== Why Not Self-Hosted SMTP =====

Deliverability from a residential IP is the blocker: PTR records depend on the ISP, and residential ranges are flagged by default. The fix is routing outbound SMTP through a cheap VPS as a smart relay, which reintroduces a monthly cost for marginal gain. Not worth it until paid ESP tiers become the constraint.

===== See Also =====

  * [[folkzone:policies|folk.zone Policies]]
  * [[folkzone:start|folk.zone Infrastructure]]
  * [[guides:add_new_service|Adding a New Service]]
  * [[start|Return to wiki home]]