Auth email delivery troubleshooting

Scenario

When Clerk’s verification or password-reset emails consistently land in spam or trigger delivery failures, users experience silent sign-up drop-offs. This workflow combines Clerk’s structured error handling with Resend’s deliverability optimization to diagnose auth failures, fix inbox placement, and restore a reliable authentication loop.

Integration steps

1. Catch Clerk auth errors: Wrap sign-up forms with const { signUp } = useSignUp();. Intercept ClerkAPIError and check err.errors[0].code for form_identifier_not_found or email_not_verified.
2. Extract error metadata: Read err.errors[0].meta for retry_after (ms) or zxcvbn feedback. Log to your telemetry service for correlation with Resend logs.
3. Verify Resend domain: Execute await resend.domains.create({ name: 'yourdomain.com' }). Add the returned spf_record, dkim_record, and mx_record to your DNS provider. Poll resend.domains.get() until status === 'verified'.
4. Route Clerk emails to Resend: In Clerk Dashboard → Email & SMS → Custom Provider, paste your Resend API key. Map verification and password_reset templates to from: '[email protected]'.
5. Send with deliverability headers: When triggering custom emails, call resend.emails.send({ from: '[email protected]', to: email, subject: 'Verify', html: template, headers: { 'X-Entity-Ref-ID': 'clerk_auth', 'Precedence': 'bulk' } }).
6. Handle delivery feedback: Subscribe to Clerk’s user.email.updated webhook. If Resend reports hard_bounce, call PATCH /v1/users/{user_id} with { public_metadata: { email_status: 'undeliverable' } } to block retries.
7. Test end-to-end: Trigger sign-up. Verify Clerk returns 200 and Resend dashboard shows delivered. Implement exponential backoff using meta.retry_after on 429 responses.

Architecture

Clerk manages the auth lifecycle and emits verification/password-reset events. It routes these to Resend via the custom email provider integration. Resend handles SMTP transmission, applies DKIM/SPF signing, and returns delivery status. Your app bridges both by parsing Clerk’s structured errors, enforcing Resend’s deliverability headers, and syncing delivery outcomes back to Clerk’s user metadata.

Prerequisites

• Clerk project with @clerk/nextjs or @clerk/clerk-js
• Resend account, API key, and resend npm package
• DNS access for SPF/DKIM/MX record configuration
• Webhook endpoint to receive Clerk email status events

Common pitfalls

• Unverified DNS: Resend returns 403 or marks emails as spam if SPF/DKIM aren’t fully propagated.
• Ignoring Clerk metadata: Skipping err.errors[0].meta prevents dynamic retry timing and password guidance.
• Mismatched from domains: Resend rejects sends if the from address doesn’t match the verified domain.
• Rate limit blindness: Rapid auth attempts trigger too_many_requests; ignoring meta.retry_after breaks the flow.
• Unvalidated webhooks: Skipping Clerk’s signature validation exposes your app to spoofed delivery updates.

Typical questions

• users can't sign up
• verification email not received
• password reset email in spam
• Clerk auth flow broken
• sign-up emails going to spam
• 用户无法注册
• 验证邮件进入垃圾箱
• 密码重置邮件收不到

Q: Why are users unable to sign up or receive verification and password reset emails? A: Sign-up failures typically occur when verification and password-reset emails land in spam via Resend. To resolve this, use Clerk to handle authentication errors and Resend to optimize email deliverability and restore your complete authentication flow.