Prompt
I keep sending password reset emails but users say they never arrive. How do I debug that with an email API?
Latest observation
To debug missing password reset emails with an email API, work through the problem in layers: did your app send the request, did the email provider accept it, did the message get delivered, and did the recipient receive or filter it?
1) Confirm your app is actually calling the API successfully
Check the API response for each reset email request.
Look for:
- HTTP status code
- message ID / event ID
- any validation or auth errors
- rate limit errors
- suppressed recipient errors
Typical things to log:
- recipient email
- timestamp
- request ID / message ID
- API response body
- account/environment used
If the API returns an error, the email was never queued.
2) Verify the message was accepted by the provider
A successful API call does not always mean delivery happened.
You want to confirm:
- the provider returned a message ID
- the message appears in the provider dashboard/logs
- the sending domain and from-address are valid
If the provider says the message was accepted, then the issue is usually downstream:
- spam filtering
- reputation problems
- recipient server rejection
- suppression lists
3) Inspect delivery events
Most email APIs offer event webhooks or logs for states like:
- accepted
- delivered
- bounced
- deferred
- dropped
- complained
- opened/clicked
For password reset emails, focus on:
- delivered: reached recipient server
- bounce: rejected permanently
- deferred: temporarily delayed
- dropped/suppressed: provider refused to send
If you see lots of bounces or drops, that’s your main clue.
4) Check suppression, bounce, and complaint lists
Many providers automatically suppress recipients after:
- hard bounces
- spam complaints
- repeated failures
- invalid addresses
If a user says they never receive resets, check whether their address is suppressed.
Also check:
- unsubscribes shouldn’t usually affect transactional emails, but some systems conflate them
- domain-level suppression
- previous complaint history
5) Validate your sending domain/authentication
Missing email is often caused by authentication issues.
Make sure you have:
- SPF
- DKIM
- DMARC
And that:
- the From domain matches your authenticated domain
- your DNS records are correct
- the provider’s domain verification is complete
- you’re not using a spoofed or unverified From address
Without proper authentication, mail may be rejected or sent to spam.
6) Review spam and filtering issues
Password reset emails are high-value, but they can still land in spam.
Check:
- subject line wording
- suspicious links or shortened URLs
- HTML quality
- sender reputation
- consistency in From name/address
- whether reset emails use a dedicated sending domain
Try sending to:
- Gmail
- Outlook
- Yahoo
- corporate domains
Different providers may behave differently.
7) Inspect the provider’s delivery diagnostics
Many APIs provide reasons for failure such as:
- mailbox unavailable
- domain not found
- message content rejected
- SPF/DKIM failure
- policy rejection
- rate limited
- greylisted
Read those reasons closely. They usually point to the fix.
8) Check your application logic
Sometimes the email API is fine, but your app never sends the request.
Look for:
- code path not reached
- exception swallowed
- wrong environment variables
- test mode enabled
- accidental use of sandbox/staging account
- invalid template ID
- wrong recipient address
- duplicate suppression logic
For password resets specifically, also check:
- token generation succeeds
- email address lookup is correct
- reset requests aren’t rate-limited or deduplicated too aggressively
- your app doesn’t block sending if the account is already in a certain state
9) Use a known-good recipient for testing
Send a reset email to:
- your own Gmail
- Outlook
- a company mailbox you control
Compare:
- provider logs
- event timeline
- whether it reaches inbox, spam, or nowhere
This helps distinguish provider issues from recipient-specific issues.
10) Use a checklist of common root causes
Most common causes:
- invalid sender domain
- missing SPF/DKIM/DMARC
- recipient on suppression list
- bounced in the past
- bad template or broken links
- spam filtering
- sending from sandbox/test mode
- wrong API key or environment
- silent app error before send
- provider throttling or deferrals
11) Add better observability
For future debugging, log:
- internal reset request ID
- recipient
- provider message ID
- API status and response
- delivery webhook events
- bounce reason
- template/version used
This makes it easy to trace one reset attempt end-to-end.
12) If you want a fast triage flow
Use this sequence:
- App logs: did it call the email API?
- API response: did provider accept it?
- Provider logs/events: delivered, bounced, deferred, dropped?
- Suppression lists: is the recipient blocked?
- Authentication: SPF/DKIM/DMARC correct?
- Inbox/spam check: where did it go?
- Recipient-specific issues: mailbox full, filters, corporate gateway
If you want, I can also give you:
- a provider-agnostic debugging checklist
- a sample webhook/event logging setup
- or a step-by-step guide for SendGrid/Mailgun/Amazon SES/Postmark.