What gets generated
SendGrid handler with multi-provider fallback
# app/services/email_service.py — generated structure
def _send(to_email, subject, html, text=""):
provider = os.environ.get("EMAIL_PROVIDER", "console")
dispatch = {
"sendgrid": _send_sendgrid,
"resend": _send_resend,
"postmark": _send_postmark,
}
chain = [provider] + [
p for p in dispatch
if p != provider and _has_credentials_for(p)
]
for p in chain:
try:
if dispatch[p](to_email, subject, html, text):
if p != provider:
logger.warning("Email sent via fallback '%s'", p)
return True
except Exception as e:
logger.warning("Provider '%s' failed: %s", p, e)
logger.error("All email providers failed: to=%s", to_email)
return False
The configured provider is tried first. If the API key has been revoked, the request is rate-limited, or the provider's API has an outage, the dispatcher walks through the other providers that have credentials configured.
Bounce handling
SendGrid's Event Webhook is wired to a route that updates the user's email status. Hard bounces flag the address as undeliverable and prevent further sends. Soft bounces increment a counter; three consecutive soft bounces escalate to hard.
Suppression list sync
When a user unsubscribes, the local suppression list is updated and SendGrid's suppression group is synced via the API. Re-subscribe flow is supported with an explicit opt-in confirmation email.
Sender authentication
The generated docs/ includes a setup guide for SPF + DKIM + DMARC + DNS records, because deliverability without these is materially worse and most teams skip them at first.
Templates
Transactional emails (verify email, password reset, welcome, invite, payment-failed, codegen-complete, marketplace-receipt) all generated with consistent branding and a plaintext fallback.
What ships in docs/
docs/decisions/ADR-0007-email-provider-cascade.md— why the multi-provider fallback exists, with the lesson from the password-reset-silently-failing incidentdocs/runbooks/email-deliverability.md— what to check when emails aren't landing (DNS, sender reputation, suppression list, bounce log)docs/setup/sender-authentication.md— the SPF + DKIM + DMARC walkthrough for archiet.com or your domain
Environment variables generated
EMAIL_PROVIDER=sendgrid # one of: console, sendgrid, resend, postmark
EMAIL_FROM=noreply@your-domain.com
SENDGRID_API_KEY=SG.... # from SendGrid dashboard
SENDGRID_WEBHOOK_VERIFICATION_KEY=... # if Event Webhook signing enabled
RESEND_API_KEY=re_... # optional fallback
POSTMARK_SERVER_TOKEN=... # optional fallback
SendGrid documentation references
Internal links
- Twilio integration for SMS
- for/cto covers operational concerns
CTA
Try it — free plan, no credit card. archiet.com.
Generate a codebase with SendGrid wired plus the fallback chain, decide if it's the deliverability architecture you'd ship.