Prompt
My transactional emails work in staging but not production, how do I debug that?
Latest observation
When transactional emails work in staging but fail in production, the problem is usually one of these: environment configuration, provider restrictions, DNS/authentication, network/security rules, or code paths that differ in production.
Here’s a practical way to debug it.
1) Confirm the failure mode
First determine what “not working” means:
- Email request never leaves your app
- Your app sends the request, but the provider rejects it
- Provider accepts it, but email never arrives
- Email arrives in spam or is delayed
- Only some templates/recipients fail
Check:
- application logs
- SMTP/API provider logs
- bounce/complaint logs
- inbox/spam of a test recipient
2) Compare staging vs production config
Most issues come from mismatched environment variables.
Check that production has the same expected values for:
- SMTP host / port / username / password
- API keys / secrets
- sender/from address
- reply-to address
- base URL used in email links
- template IDs
- feature flags
Common problem:
- staging uses a test key
- production uses a live key with stricter rules
- production is missing one variable entirely
Tip: print a sanitized config summary at startup in production logs.
3) Verify the email provider allows production sending
Many providers treat staging and production differently:
- domain not verified
- “from” address not authorized
- sandbox mode still enabled
- sending quota exhausted
- production account restricted or paused
- account requires payment or identity verification
If using an API provider, check:
- request status code
- response body
- provider dashboard logs
If using SMTP, check:
- auth success/failure
- relay denied
- TLS negotiation issues
4) Inspect server logs around the send attempt
Look for:
- exceptions thrown during send
- timeout errors
- connection refused
- authentication failures
- DNS lookup failures
- rate limit errors
- “message accepted” vs “message queued”
Make sure your app logs the provider response, not just “email sent” before the request actually succeeds.
5) Check DNS and email authentication
In production, deliverability often depends on proper domain setup:
- SPF
- DKIM
- DMARC
- MX records, if relevant
Problems here can cause:
- rejection by the provider
- spam filtering
- silent delivery issues
Use tools like:
- MXToolbox
- dmarcian
- Google Postmaster Tools
- your provider’s DNS verification page
6) Confirm production outbound network access
Production servers may have stricter networking than staging.
Check:
- firewall rules
- outbound SMTP blocked by cloud provider
- VPC security groups
- private subnet with no NAT
- port 25 blocked
- proxy issues
Many cloud providers block port 25 by default. Prefer port 587 or the provider’s HTTPS API.
7) Compare code paths between environments
Sometimes production follows a different path:
- background jobs enabled only in staging
- async queue misconfigured
- cron worker not running
- email task failures hidden by retries
- feature flag disables sending
- production uses a different template or locale that crashes
Check:
- job queue status
- worker processes
- retry counts
- dead-letter queues
- scheduled jobs
8) Look for “success” masking failures
Your app may log success after enqueuing, not after delivery.
Example:
- “Queued email job” is not the same as “sent email”
- the job worker may be down in production
- a swallowed exception may prevent delivery
Make sure you log:
- enqueue success
- worker start
- send attempt
- provider response
- final status
9) Test with a minimal production send
Send a very simple transactional email from production:
- plain text
- one recipient you control
- no template variables
- no attachments
- no links if possible
If this works, the issue may be in template rendering or recipient-specific logic.
10) Check spam, suppression, and bounce handling
Production recipients may be suppressed if:
- bounced before
- unsubscribed
- on a suppression list
- spam complaints caused reputation issues
Provider dashboards often show:
- suppressed recipients
- bounce reasons
- complaint rates
11) Reproduce locally with production settings
If possible:
- use the production API key in a safe test environment
- point local code at the same provider
- run a one-off send script
This helps separate app logic from server/network issues.
12) Add better observability
For long-term debugging, add:
- correlation IDs for each email
- structured logs
- provider message ID
- recipient, template name, environment
- send duration
- error code and response body
Example log fields:
email_typeenvironmentrecipient_domainprovidermessage_idstatuserror_code
13) Common production-only causes
A quick checklist:
- wrong env vars in production
- sandbox/test mode still on
- sender domain not verified
- SPF/DKIM missing
- outbound SMTP blocked
- background worker not running
- queue misconfigured
- account quota exceeded
- provider account paused
- emails going to spam
- hidden exception in template rendering
Suggested debugging order
- Check provider dashboard logs
- Check production app logs
- Compare env vars with staging
- Verify sender/domain auth
- Test outbound connectivity
- Confirm worker/queue health
- Send a minimal test email
- Check suppression/bounce lists
If you want, I can help you build a production email debugging checklist for your stack, like Node, Python, Rails, Django, Laravel, or SMTP/API provider-specific steps.