openinvoice-docs
Troubleshooting

Email Issues

Troubleshooting email delivery and tracking problems

Email Not Sending

Check Configuration

Verify:

  1. Resend API key is correct
  2. From email is verified
  3. Email service is enabled
  4. Environment variables are set

Solutions:

  • Verify API key in Resend Dashboard
  • Check from email is verified
  • Review Resend API status
  • Test API key with curl

Check Logs

Review email logs:

  1. Go to invoice
  2. Navigate to Emails tab
  3. Check email status
  4. Review error messages
  5. Check Resend Dashboard logs

Email Delivery Issues

Emails Not Delivered

Common Causes:

  • Spam folder
  • Invalid email address
  • Domain not verified
  • DNS records incorrect
  • Email service issues

Solutions:

  • Check spam folder
  • Verify email address format
  • Verify domain in Resend
  • Check DNS records (SPF, DKIM)
  • Review bounce reports

Emails Going to Spam

Check:

  1. Domain is verified
  2. SPF record is set
  3. DKIM record is set
  4. DMARC policy (optional)
  5. Email content

Solutions:

  • Verify domain in Resend
  • Add SPF record to DNS
  • Add DKIM record to DNS
  • Set up DMARC policy
  • Review email content

Email Tracking Issues

Opens Not Tracking

Check:

  1. Webhook is configured
  2. Webhook secret is correct
  3. Events are subscribed
  4. Webhook is receiving events

Solutions:

  • Verify webhook URL
  • Check webhook secret
  • Review webhook logs
  • Test webhook with Resend

Clicks Not Tracking

Check:

  1. Links are properly formatted
  2. Tracking pixels are included
  3. Webhook events are received
  4. Database is updating

Solutions:

  • Verify link format
  • Check tracking implementation
  • Review webhook events
  • Check database updates

Email Template Issues

Template Not Rendering

Check:

  1. HTML is valid
  2. Template variables are correct
  3. Email service supports HTML
  4. Template is saved correctly

Solutions:

  • Validate HTML
  • Check template variables
  • Review template syntax
  • Test template rendering

Branding Not Applied

Check:

  1. Branding is configured
  2. Logo is uploaded
  3. Colors are set
  4. Template uses branding

Solutions:

  • Verify branding settings
  • Check logo URL
  • Review color configuration
  • Test email preview

Webhook Issues

Webhook Not Receiving Events

Check:

  1. Webhook URL is accessible
  2. Webhook secret matches
  3. Events are subscribed
  4. Webhook endpoint is working

Solutions:

  • Verify webhook URL
  • Check webhook secret
  • Review subscribed events
  • Test webhook endpoint
  • Use ngrok for local testing

Webhook Verification Failing

Check:

  1. Webhook secret is correct
  2. Signature verification logic
  3. Request headers
  4. Webhook payload

Solutions:

  • Verify webhook secret
  • Check signature verification
  • Review request headers
  • Test webhook verification

Email Service Limits

Rate Limits

Resend Limits:

  • Free tier: 3,000 emails/month
  • Pro tier: Higher limits

Solutions:

  • Upgrade Resend plan
  • Implement rate limiting
  • Queue emails
  • Monitor usage

API Errors

Check:

  1. API key is valid
  2. Rate limits not exceeded
  3. API status is healthy
  4. Request format is correct

Solutions:

  • Verify API key
  • Check rate limits
  • Review API status
  • Check request format

Best Practices

  1. Verify Domain - Always verify domain for production
  2. Monitor Bounces - Track bounce rates
  3. Test Templates - Test email rendering
  4. Track Engagement - Monitor opens and clicks
  5. Handle Errors - Implement error handling

Getting Help

For email issues:

  1. Check Resend Dashboard
  2. Review email logs
  3. Check webhook logs
  4. Review DNS records
  5. Contact Resend support if needed

Next Steps

Payment Issues

Troubleshooting payment processing problems