Resend Email API

--- name: Resend Email API description: Use when you need to send transactional emails, manage email templates, verify domains, or handle email delivery through Resend's API. Ideal for application notifications, user onboarding, password resets, and marketing campaigns. category: ops metadata: author: skynet version: 1.0.0 --- # Resend Email API ## Quick Start ### Installation ```bash # Install Resend CLI npm install -g resend # Set API key export RESEND_API_KEY="re_your_api_key_here" # Verify installation resend --version ``` ### Basic Email Send ```bash # Send simple email curl -X POST 'https://api.resend.com/emails' \ -H 'Authorization: Bearer re_your_api_key' \ -H 'Content-Type: application/json' \ -d '{ "from": "onboarding@yourdomain.com", "to": ["user@example.com"], "subject": "Hello World", "text": "Your message here" }' ``` ## Common Workflows ### 1. Send HTML Email with Attachments ```bash curl -X POST 'https://api.resend.com/emails' \ -H 'Authorization: Bearer re_your_api_key' \ -H 'Content-Type: application/json' \ -d '{ "from": "support@yourdomain.com", "to": ["recipient@example.com"], "subject": "Invoice #12345", "html": "<h1>Thank you for your order</h1><p>Please find your invoice attached.</p>", "attachments": [ { "filename": "invoice.pdf", "content": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCg==", "content_type": "application/pdf" } ], "tags": [ {"name": "category", "value": "invoice"}, {"name": "priority", "value": "high"} ] }' ``` ### 2. Bulk Email Send ```bash # Send to multiple recipients curl -X POST 'https://api.resend.com/emails/batch' \ -H 'Authorization: Bearer re_your_api_key' \ -H 'Content-Type: application/json' \ -d '[ { "from": "newsletter@yourdomain.com", "to": ["user1@example.com"], "subject": "Weekly Newsletter", "html": "<h1>This weeks updates</h1>" }, { "from": "newsletter@yourdomain.com", "to": ["user2@example.com"], "subject": "Weekly Newsletter", "html": "<h1>This weeks updates</h1>" } ]' ``` ### 3. Email with Template ```bash # Create template first curl -X POST 'https://api.resend.com/emails' \ -H 'Authorization: Bearer re_your_api_key' \ -H 'Content-Type: application/json' \ -d '{ "from": "welcome@yourdomain.com", "to": ["newuser@example.com"], "subject": "Welcome {{name}}!", "template": "welcome-template-id", "template_data": { "name": "John Doe", "company": "Acme Corp", "trial_days": 14 } }' ``` ## Domain Management ### Verify Domain ```bash # Add domain curl -X POST 'https://api.resend.com/domains' \ -H 'Authorization: Bearer re_your_api_key' \ -H 'Content-Type: application/json' \ -d '{"name": "yourdomain.com"}' # Check domain status curl -X GET 'https://api.resend.com/domains/domain_id' \ -H 'Authorization: Bearer re_your_api_key' # List all domains curl -X GET 'https://api.resend.com/domains' \ -H 'Authorization: Bearer re_your_api_key' ``` ### DNS Records Setup ```bash # Get DNS records for domain verification curl -X GET 'https://api.resend.com/domains/domain_id/verification' \ -H 'Authorization: Bearer re_your_api_key' # Example DNS records to add: # TXT record: _resend.yourdomain.com → "resend-verification=abc123" # MX record: yourdomain.com → mx1.resend.com (priority 10) # CNAME record: resend._domainkey.yourdomain.com → resend._domainkey.resend.com ``` ## Email Status & Analytics ### Check Email Status ```bash # Get email by ID curl -X GET 'https://api.resend.com/emails/email_id' \ -H 'Authorization: Bearer re_your_api_key' # List recent emails curl -X GET 'https://api.resend.com/emails?limit=10&from=sender@yourdomain.com' \ -H 'Authorization: Bearer re_your_api_key' ``` ### Webhook Setup ```bash # Create webhook for delivery events curl -X POST 'https://api.resend.com/webhooks' \ -H 'Authorization: Bearer re_your_api_key' \ -H 'Content-Type: application/json' \ -d '{ "endpoint": "https://yourapp.com/webhooks/resend", "events": ["email.sent", "email.delivered", "email.bounced", "email.complained"] }' ``` ## Decision Trees ### Email Type Selection ``` Are you sending? ├─ Single transactional email → Use /emails endpoint ├─ Multiple emails at once → Use /emails/batch endpoint ├─ Recurring template emails → Create template + use template_id └─ Marketing campaigns → Use batch with scheduling Is delivery critical? ├─ Yes → Add webhooks for delivery tracking ├─ Somewhat → Use tags for easy filtering └─ No → Basic send is sufficient ``` ### Domain Configuration ``` Domain setup status? ├─ New domain → POST /domains → Verify DNS → Test send ├─ Existing unverified → Check DNS records → Retry verification ├─ Verified but issues → Check domain reputation + logs └─ Working fine → Monitor delivery rates Email volume? ├─ < 100/day → Single domain OK ├─ 100-10k/day → Consider subdomain for different email types ├─ > 10k/day → Multiple domains + IP warming strategy └─ > 100k/day → Contact Resend for enterprise setup ``` ## Troubleshooting ### Authentication Errors ``` Error: "Invalid API key" Fix: - Check API key format (starts with "re_") - Verify key in Resend dashboard - Ensure key has correct permissions curl -X GET 'https://api.resend.com/domains' \ -H 'Authorization: Bearer YOUR_CORRECT_API_KEY' ``` ### Send Failures ``` Error: "Domain not verified" Fix: 1. Check domain verification status: curl -X GET 'https://api.resend.com/domains/domain_id' -H 'Authorization: Bearer re_key' 2. Verify DNS records are properly configured 3. Wait up to 72 hours for DNS propagation Error: "Rate limit exceeded" Fix: - Check current limits: curl -X GET 'https://api.resend.com/emails?limit=1' - Implement exponential backoff - Consider upgrading plan for higher limits ``` ### Delivery Issues ``` Email sent but not delivered: 1. Check email status: curl -X GET 'https://api.resend.com/emails/email_id' 2. Common status meanings: - "queued" → Email accepted, waiting to send - "sent" → Delivered to recipient server - "delivered" → Successfully delivered - "bounced" → Recipient server rejected - "complained" → Marked as spam 3. For bounces, check bounce reason and update recipient list 4. For spam complaints, review email content and sender reputation ``` ### Content Validation ``` Error: "Invalid email format" Fix: - Ensure "from" field uses verified domain - Check "to" field contains valid email addresses - Validate HTML content is properly encoded - Ensure attachment content is base64 encoded Example validation: echo "user@domain.com" | grep -E "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$" ``` ### Rate Limiting Best Practices ```bash # Implement retry logic with backoff for i in {1..3}; do response=$(curl -w "%{http_code}" -s -o response.json \ -X POST 'https://api.resend.com/emails' \ -H 'Authorization: Bearer re_your_api_key' \ -H 'Content-Type: application/json' \ -d '{"from":"test@domain.com","to":["user@example.com"],"subject":"Test","text":"Test"}') if [ "$response" = "200" ]; then echo "Success" break elif [ "$response" = "429" ]; then echo "Rate limited, waiting..." sleep $((2**i)) else echo "Error: $response" cat response.json break fi done ``` ### Monitoring Setup ```bash # Create monitoring script #!/bin/bash # Check domain health daily for domain in $(resend domains list --format=json | jq -r '.[].name'); do status=$(resend domains get $domain --format=json | jq -r '.status') if [ "$status" != "verified" ]; then echo "ALERT: Domain $domain status is $status" fi done # Add to crontab echo "0 9 * * * /path/to/domain-check.sh" | crontab - ```