Docs / Reference
Transactional email delivery
Application-generated email must use a reputable transactional email provider. Do not send contact-form, invite, password-reset, alert, or receipt-style mail from application hosts or server-native mail transfer agents.
Current website posture
- This public marketing site is static and does not include a server-side contact form or native mail sender.
- The contact page uses
mailto:links, so this repository has no SMTP credentials, provider SDK, queue, or bounce handler to configure. - If a contact form or transactional workflow is added later, it must satisfy this runbook before production launch.
Required sending architecture
| Requirement | Production standard |
|---|---|
| Provider | Use a reputable transactional email provider over authenticated SMTP or provider API. SMTP is acceptable for contact-form and transactional messages. |
| Separation | Use a dedicated transactional sending domain or subdomain where practical, separate from critical employee mail. |
| Secrets | Store SMTP/API credentials in the deployment secret manager, never in source, build logs, client bundles, or static assets. |
| Queueing | Send asynchronously where possible, with retries, idempotency keys, and rate limits for form-triggered messages. |
| Observability | Monitor accepted, delivered, bounced, deferred, complained, and rejected events from provider webhooks or dashboards. |
DNS authentication
- Publish exactly one SPF record for the sending domain or subdomain, including only approved senders.
- Publish DKIM records for every active provider selector. Rotate selectors according to provider guidance.
- Deploy DMARC at
_dmarcwith reporting addresses and an approved policy. Move toward enforcement once legitimate sources align. - Validate DNS after every nameserver, registrar, or provider migration using the DNS change runbook.
Delivery and bounce monitoring
- Enable provider dashboards and webhooks for bounces, spam complaints, rejects, deferrals, suppressions, and delivery latency.
- Alert on authentication failures, sudden bounce-rate increases, disabled domains, webhook failures, and provider account warnings.
- Retain enough event history to troubleshoot user support cases without storing message bodies unnecessarily.
- Document the owner for provider account access, DNS changes, suppression-list review, and incident response.
Test procedure
Run this after first setup, DNS changes, provider changes, credential rotation, and before launching any new transactional email flow.
# replace with the production sending domain dig TXT perryscope.ai +short dig TXT default._domainkey.perryscope.ai +short dig TXT _dmarc.perryscope.ai +short # verify SMTP connectivity from the server network, if SMTP is used openssl s_client -starttls smtp -connect smtp.example-provider.com:587 -servername smtp.example-provider.com
- Send test messages for every production template: contact form, invite, password reset, alert, billing, or receipt.
- Deliver tests to Gmail, Outlook/Microsoft 365, Yahoo, Apple/iCloud, and one company-controlled mailbox.
- Inspect received headers and record SPF, DKIM, and DMARC results. All must pass and align with the expected sending domain.
- Confirm each message lands in the inbox, not spam or quarantine, and that links point to the expected production hostnames.
- Confirm provider events show accepted and delivered status, and that a deliberate invalid-recipient test produces a visible bounce event.
Acceptance evidence
- Provider name, sending domain, and separation decision are recorded in the production launch/change ticket.
- SPF and DKIM pass, DMARC is deployed, and alignment is visible in message headers.
- Delivery and bounce monitoring are enabled with an accountable owner.
- Successful inbox delivery is recorded for major mailbox providers.
Control:Required before any production feature sends application-generated email.