Common Email API Issues & Solutions
This troubleshooting guide covers the most common email API problems and provides step-by-step solutions. Whether you're experiencing delivery failures, authentication errors, or webhook issues, you'll find solutions here.
Emails Not Being Delivered
Symptoms: Emails are sent successfully via API but recipients don't receive them, or you receive bounce notifications.
Solutions:
- Check Bounce Messages: Review bounce notifications in your dashboard. Common reasons include invalid email addresses, full mailboxes, or recipient server rejections.
- Verify Domain Authentication: Ensure SPF, DKIM, and DMARC records are properly configured. Use email authentication testing tools to verify.
- Check Sender Reputation: Monitor your sender reputation score. Low reputation can cause emails to be filtered to spam folders.
- Validate Email Addresses: Use email validation APIs to verify recipient addresses before sending. Invalid addresses will always bounce.
- Review Content: Avoid spam trigger words, excessive links, or suspicious content that might trigger spam filters.
- Check Blacklists: Verify your sending IP or domain isn't on email blacklists using tools like MXToolbox.
# Check bounce reasons in webhook
{
"event": "bounce",
"reason": "550 5.1.1 User unknown",
"email": "invalid@example.com"
}
API Authentication Errors
Symptoms: Receiving 401 Unauthorized or 403 Forbidden errors when making API requests.
Solutions:
- Verify API Key: Double-check your API key for typos. API keys are case-sensitive and must match exactly.
- Check Key Status: Ensure your API key hasn't been disabled or regenerated. Regenerated keys invalidate old ones.
- Verify Header Format: Use the correct authentication header format. Most APIs use "Authorization: Bearer YOUR_API_KEY" or "X-API-Key: YOUR_API_KEY".
- Check Key Permissions: Ensure your API key has the necessary permissions for the operation you're trying to perform.
- Test with cURL: Test authentication directly with cURL to isolate the issue from your application code.
- Regenerate Key: If all else fails, regenerate your API key in the dashboard and update your application.
# Correct authentication header
curl -X POST https://api.sparkmailr.com/v1/emails \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
Rate Limit Errors
Symptoms: Receiving 429 Too Many Requests errors, or emails being queued instead of sent immediately.
Solutions:
- Implement Exponential Backoff: Add retry logic with exponential backoff when you receive 429 errors. Wait progressively longer between retries.
- Spread Sending Over Time: Instead of sending all emails at once, spread them over time to stay within rate limits.
- Use Queue Systems: Implement message queues (RabbitMQ, Redis, etc.) to throttle email sending and respect rate limits.
- Check Rate Limit Headers: Most APIs include rate limit information in response headers (X-RateLimit-Remaining, X-RateLimit-Reset).
- Upgrade Plan: Consider upgrading to a plan with higher rate limits if you consistently hit limits.
- Contact Support: Enterprise customers can request custom rate limits for high-volume sending.
# Exponential backoff retry example
import time
import random
def send_with_retry(email_data, max_retries=3):
for attempt in range(max_retries):
try:
return api.send_email(email_data)
except RateLimitError:
wait_time = (2 ** attempt) + random.uniform(0, 1)
time.sleep(wait_time)
raise Exception("Max retries exceeded")
Webhook Not Receiving Events
Symptoms: Webhook URL configured but not receiving event notifications for email events (delivered, opened, clicked, etc.).
Solutions:
- Verify Webhook URL: Ensure your webhook URL is publicly accessible (not localhost or private IP). Use ngrok for local testing.
- Check SSL Certificate: Webhook URLs must use HTTPS with valid SSL certificates. Self-signed certificates won't work.
- Test Webhook Endpoint: Use webhook testing tools or manually send POST requests to verify your endpoint accepts requests.
- Check Firewall Rules: Ensure your server firewall allows incoming POST requests on the webhook endpoint.
- Review Server Logs: Check your server logs for incoming webhook requests. They may be arriving but failing silently.
- Verify Response Format: Your webhook endpoint should return 200 OK status quickly (within 5 seconds) to acknowledge receipt.
- Check Webhook Secret: If using webhook signatures, verify your secret key matches the one configured in the API dashboard.
⚠️ Important:
Webhook endpoints must respond within 5 seconds. Slow responses may cause the API to retry or drop events. Implement async processing for heavy webhook handlers.
Invalid Email Address Errors
Symptoms: Receiving validation errors when sending emails, or emails bouncing due to invalid addresses.
Solutions:
- Validate Before Sending: Use email validation APIs to check addresses before sending. This prevents bounces and improves deliverability.
- Check Format: Ensure email addresses follow RFC 5322 format: local-part@domain. Common issues include missing @, spaces, or invalid characters.
- Handle Typos: Implement client-side validation to catch common typos (e.g., "gmial.com" → "gmail.com").
- Use Double Opt-in: Require email confirmation before sending to new addresses to ensure they're valid and consented.
- Clean Your List: Regularly clean your email list to remove invalid, bounced, or unsubscribed addresses.
Template Rendering Errors
Symptoms: Emails sent but with broken HTML, missing variables, or incorrect formatting.
Solutions:
- Check Variable Syntax: Verify template variable syntax matches the API's requirements (e.g., {{variable}}, ${variable}, or {variable}).
- Validate Required Variables: Ensure all required template variables are provided in the API request.
- Test Template Rendering: Use the API's template preview feature to test rendering before sending.
- Check HTML Validity: Validate your HTML template for syntax errors that might break rendering.
- Review Email Clients: Test rendered emails in multiple email clients (Gmail, Outlook, Apple Mail) to ensure compatibility.
Quick Reference: Common Error Codes
| Error Code |
Meaning |
Solution |
| 400 |
Bad Request |
Check request format and required fields |
| 401 |
Unauthorized |
Verify API key and authentication headers |
| 403 |
Forbidden |
Check API key permissions |
| 429 |
Rate Limit |
Implement backoff and retry logic |
| 500 |
Server Error |
Retry request or contact support |
Still Need Help?
If you've tried these solutions and still experiencing issues, our support team is here to help.