resend-debug

name	resend-debug
description	Debug and troubleshoot Resend email issues. Diagnose rate limiting, webhook failures, domain verification, bounce rates, and authentication errors. Use when emails aren't sending, delivery is slow, webhooks aren't triggering, or bounces are high.
license	MIT
compatibility	Node.js 18+, RESEND_API_KEY env var, access to email logs
metadata	{"version":"1.0.0","parent-skill":"resend-email-integration"}

Resend Debugging Guide

Resend failures fall into 6 categories. This skill helps you identify and fix yours.

---

Diagnosis Flow

Answer these questions in order:

Q1: Are emails sending at all?

❌ No emails in Resend dashboard

→ Go to Diagnosis #1: Authentication Failure

✅ Emails show "Sent" but not "Delivered"

→ Go to Diagnosis #2: Domain Verification

✅ Emails deliver but bounce rate > 4%

→ Go to Diagnosis #3: High Bounce Rate

✅ Emails send fine but webhooks don't trigger

→ Go to Diagnosis #4: Webhook Failure

✅ Everything works but requests are slow/rate limited

→ Go to Diagnosis #5: Rate Limiting

✅ Webhook verify fails (signature invalid)

→ Go to Diagnosis #6: Webhook Security

---

Diagnosis #1: Authentication Failure (Emails Not Sending)

Symptoms:

• Error: 401 missing_api_key or 403 restricted_api_key
• No emails appear in Resend dashboard
• Network request fails immediately

Checklist:

1. Is RESEND_API_KEY set?

   echo $RESEND_API_KEY
   # Should print: re_xxxxxxxxxxxx
   # If empty → SET THE ENV VAR
   

2. Is the key correct?

   # Go to resend.com → Settings → API Keys
   # Copy the key exactly (no spaces, no extra characters)
   

3. Is the key expired?

   # In Resend dashboard, check key status
   # If it says "Inactive" → create a new one
   

4. Does the key have "Full access"?

   # Settings → API Keys → select key
   # Should show "Full access" not "Sending access only"
   # If limited → create a new key with full access
   

5. Are you using the SDK correctly?

   // ✅ CORRECT
   const resend = new Resend(process.env.RESEND_API_KEY);
   
   // ❌ WRONG
   const resend = new Resend('re_xxxxxxxxxxxx');  // hardcoded
   

Fix: Update .env.local, restart server, retry.

---

Diagnosis #2: Domain Verification (Emails "Sent" but Not Delivered)

Symptoms:

• Resend dashboard shows "Sent" status
• Email never arrives in recipient inbox
• Bounce rate high or no bounces reported
• Error: validation_error with "domain not verified"

Checklist:

1. Is the "from" domain verified?

   # Resend dashboard → Settings → Domains
   # Should show: ✅ Verified
   # If ❌ Not verified or ⏳ Pending → wait 15 min - 72 hours
   

2. Are SPF/DKIM records added?

   # Go to your domain registrar (GoDaddy, AWS Route53, etc)
   # Add the SPF and DKIM records from Resend dashboard
   # Example SPF: v=spf1 include:sendgrid.net ~all
   

3. Did you wait long enough?

   # DNS propagation can take 15 min to 72 hours
   # Use: dig yourdomain.com TXT
   # Should see the SPF record you added
   

4. Are you sending from the verified domain?

   // ✅ CORRECT (if yourdomain.com is verified)
   await resend.emails.send({
     from: '[e-mail]',  // verified domain
     to: recipient,
     // ...
   });
   
   // ❌ WRONG
   await resend.emails.send({
     from: '[e-mail]',  // not verified
     to: recipient,
     // ...
   });
   

5. Using test domain?

   // ✅ For testing only:
   from: '[e-mail]',  // always works in testing
   to: '[e-mail]',     // simulates delivery
   

Fix: Verify domain, add DNS records, wait for propagation, retry.

---

Diagnosis #3: High Bounce Rate (> 4%)

Symptoms:

• Webhooks report email.bounced events
• Bounce rate in dashboard > 4%
• Resend notifies you reputation is degraded
• Some emails delivered, some bounced

Checklist:

1. What type of bounces? (check webhook events)

   Hard bounce = permanent (invalid address, domain doesn't exist)
   Soft bounce = temporary (mailbox full, server busy)
   

2. Are you adding to suppressions? (critical!)

   // When webhook event.type === 'email.bounced':
   await resend.contacts.create({
     email: event.data.to[0],
     unsubscribed: true,  // Add to suppressions
   });
   

3. Are you checking suppressions before sending?

   // Before sending, check if email is already bounced
   const bounced = await db.emailLog.findFirst({
     where: {
       to: recipientEmail,
       status: 'bounced',
     },
   });
   
   if (bounced) {
     console.log(`Email already bounced, skipping`);
     return;  // Don't send again
   }
   

4. Is your recipient list clean?

   # Export emails from your database
   # Check for obvious typos: @gmai.com (should be @gmail.com)
   # Remove test emails: @example.com, @test.com
   

5. Are you validating email format?

   const isValidEmail = (email) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.(email);
   
    (!(recipientEmail)) {
     .();
     ;
   }
   

Fix: Add bounces to suppressions, validate emails before sending, monitor bounce rate.

---

Diagnosis #4: Webhook Not Triggering

Symptoms:

• Emails send fine but webhook endpoint never called
• Database EmailLog status stays "pending"
• Resend dashboard shows events but your server doesn't process them

Checklist:

1. Is the webhook endpoint public?

   # Try accessing from outside: curl https://your-domain.com/api/webhooks/resend
   # Should return: 405 Method Not Allowed (POST only)
   # If: connection refused → endpoint not public
   

2. Is the endpoint registered in Resend?

   # Resend dashboard → Webhooks
   # Should show: https://your-domain.com/api/webhooks/resend
   # If empty → register it
   

3. Are you capturing raw body?

   // ❌ WRONG (parsed JSON loses signature)
   const payload = req.body;
   
   // ✅ CORRECT (capture raw first)
   const rawBody = await req.text();
   

4. Is your verification middleware in place?

   // Check: is resend.webhooks.verify() being called?
   // Should verify HMAC before processing
   

5. Are server logs showing requests?

   # Check server logs during Resend "Send test event"
   # Should see: POST /api/webhooks/resend
   # If nothing → firewall/proxy blocking it
   

6. Did you test with Resend's test event?

   # Resend dashboard → Webhooks → Send test event
   # Check server logs immediately after
   

Fix: Verify endpoint is public, register in Resend, check logs.

---

Diagnosis #5: Rate Limiting (429 Errors)

Symptoms:

• Error: 429 rate_limit_exceeded
• Requests fail intermittently when sending many emails
• Getting: x-resend-requests-remaining: 0

Checklist:

1. What's your rate limit?

   Default: 10 requests/second (per team, not per key)
   

2. Are you batching emails?

   // ✅ Better (1 request for 100 emails)
   await resend.emails.sendBatch(emails);  // 1 request
   
   // ❌ Worse (100 requests for 100 emails)
   for (const email of emails) {
     await resend.emails.send(email);      // 100 requests
   }
   

3. Are you implementing backoff?

   // ✅ Implement retry with exponential backoff
   if (error.code === 'rate_limit_exceeded') {
     const delayMs = Math.pow(2, attemptNumber) * 1000;  // 1s, 2s, 4s
     await sleep(delayMs);
     retry();  // Try again
   }
   

4. Are you monitoring remaining quota?

   // Check response headers after each request
   const remaining = response.headers.get('x-resend-requests-remaining');
   console.log(`Requests remaining: ${remaining}`);
   if (remaining < 5) {
     console.();
   }
   

Fix: Batch emails, implement backoff, monitor quota headers.

---

Diagnosis #6: Webhook Verification Fails (Invalid Signature)

Symptoms:

• Error: Invalid webhook signature
• Webhook verification fails in resend.webhooks.verify()
• Status 400 returned to Resend

Checklist:

1. Are you using the SDK to verify?

   // ✅ CORRECT (use SDK)
   const event = resend.webhooks.verify({
     payload: rawBody,
     headers: { ... },
     webhookSecret: process.env.RESEND_WEBHOOK_SECRET,
   });
   
   // ❌ WRONG (don't implement HMAC manually)
   

2. Is the webhook secret correct?

   # Resend dashboard → Webhooks → Select endpoint → Show secret
   # Copy exactly into .env.local: RESEND_WEBHOOK_SECRET=whsec_...
   # Restart server (env var must reload)
   

3. Are you using raw body (not parsed)?

   // ❌ WRONG (parsed JSON, signature mismatch)
   const payload = await req.json();
   
   // ✅ CORRECT (raw body, exact bytes)
   const payload = await req.text();
   

4. Are headers being passed correctly?

   // Must be exact header names:
   svix-id: req.headers.get('svix-id')            // Not svix_id
   svix-timestamp: req.headers.get('svix-timestamp')
   svix-signature: req.headers.get('svix-signature')
   

5. Did you update secret after regenerating?

Fix: Use SDK verification, check secret matches, use raw body, restart server.

---

Quick Reference: 6 Common Errors

Error	Cause	Fix
401 missing_api_key	RESEND_API_KEY not set	Set env var, restart
403 restricted_api_key	Key has "Sending access only"	Create new key with "Full access"
validation_error	Domain not verified	Verify domain + wait for DNS
429 rate_limit_exceeded	Too many requests	Batch emails + implement backoff
Invalid webhook signature	Secret mismatch or parsed JSON	Check secret, use raw body
email.bounced webhook	Invalid recipient address	Add to suppressions, validate emails

---

Testing Checklist

Before going to production:

• Can send email with @resend.dev test domain
• Can send email with verified domain
• Webhook endpoint receives test events
• HMAC verification passes
• Database updates on webhook events
• Bounce rate < 4% in staging
• Rate limit backoff works
• No duplicate emails sent

---

If Still Stuck

1. Enable verbose logging in your code
2. Check Resend dashboard for error details
3. Check server logs (all output)
4. Read docs/base/05-errors.md for error code deep dive
5. Open issue on GitHub with (sanitized) logs

---

See resend-email-integration skill for reference docs.