Skip to main content
Testing your email integration before sending to real recipients is essential. Lettr provides several ways to send test emails, validate your setup, and debug issues without affecting your sending reputation or reaching real inboxes.

​
Test Emails in the Dashboard

The simplest way to test is from the Lettr dashboard:
  1. Go to Emails and open any template
  2. Click Send Test Email
  3. Enter your own email address (or any address you control)
  4. The email is sent through the full delivery pipeline, so you can verify rendering, headers, tracking, and deliverability
Use test emails to verify your email renders correctly before sending to your full audience. Test in multiple email clients by sending to your Gmail, Outlook, and Apple Mail accounts.

​
Sandbox API Keys

The easiest way to test your API integration is with a sandbox API key. Sandbox keys redirect all emails to your own inbox automatically — no domain setup required, no risk of reaching real recipients. 
curl -X POST https://app.lettr.com/api/emails \
  -H "Authorization: Bearer lttr_sandbox_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": ["customer@example.com"],
    "subject": "Test Email",
    "html": "<h1>Hello!</h1>"
  }'
The email above will be delivered to your account email, not to customer@example.com. Sandbox sends are free, don’t require a verified domain, and don’t count against your quota. Create a sandbox key in Settings > API Keys by setting the type to Sandbox. See the Sandbox API Keys guide for full details on rate limits, allowed endpoints, and data isolation.

​
Test Emails via the API

When integrating with the API, send test emails to addresses you control to verify your code works before going live.

​
Basic Test Send

curl -X POST https://app.lettr.com/api/emails \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": ["your-test-address@gmail.com"],
    "subject": "Integration Test",
    "html": "<h1>Test Email</h1><p>If you see this, the integration works.</p>"
  }'

​
Validating the Response

A successful send returns a 202 Accepted response with the email ID: 
{
  "id": "em_xxxxxxxxxxxxxx",
  "status": "queued"
}
Use this ID to check the email’s delivery status: 
curl https://app.lettr.com/api/emails/em_xxxxxxxxxxxxxx \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"
The response includes the current status and event history: 
{
  "id": "em_xxxxxxxxxxxxxx",
  "status": "delivered",
  "from": "you@yourdomain.com",
  "to": ["your-test-address@gmail.com"],
  "subject": "Integration Test",
  "events": [
    { "type": "queued", "timestamp": "2026-01-30T10:00:00Z" },
    { "type": "sent", "timestamp": "2026-01-30T10:00:01Z" },
    { "type": "delivered", "timestamp": "2026-01-30T10:00:02Z" }
  ]
}

​
Using Test Email Addresses

When you need to test your sending logic but don’t want to deliver emails to real inboxes, use these approaches:

​
Plus Addressing

Most email providers support plus addressing, which lets you create unlimited test aliases: 
yourname+test1@gmail.com
yourname+bounce-test@gmail.com
yourname+campaign-A@gmail.com
All of these deliver to yourname@gmail.com, but they appear as distinct recipients in Lettr, making it easy to track and filter test sends.

​
Dedicated Test Domain

For team testing, set up a subdomain specifically for test recipients:
  1. Register a subdomain like test.yourdomain.com
  2. Configure email receiving for that subdomain
  3. Use addresses like qa@test.yourdomain.com, staging@test.yourdomain.com
This keeps test email completely separate from production sending.

​
Testing Webhooks

Verify your webhook endpoint processes events correctly before relying on it in production.

​
Send Test Webhook Events

From the Lettr dashboard:
  1. Go to Webhooks and select your endpoint
  2. Click Send Test Event
  3. Choose the event type (delivered, bounced, opened, clicked, etc.)
  4. Check your server logs to confirm the event was received and processed

​
Local Development with Tunnels

Test webhooks against your local development server using a tunnel: 
# Start your local server
npm run dev  # or php artisan serve, etc.

# In another terminal, create a tunnel
ngrok http 3000
Copy the generated URL (e.g., https://abc123.ngrok.io) and set it as your webhook endpoint in the Lettr dashboard.
Remember to update your webhook URL back to your production endpoint before deploying. Tunnel URLs are temporary and will stop working when the tunnel session ends.
See Webhook Delivery Failures for debugging webhook issues and Webhook Testing for a detailed testing guide.

​
Verifying Domain and Authentication Setup

Before sending to real recipients, verify that your authentication is correctly configured.

​
DNS Verification Checklist

1

Check domain status in the dashboard

Go to the Domains page and verify all records show a green checkmark. If any record is pending or failed, follow the setup instructions for your DNS provider.
2

Send a test and inspect headers

Send a test email to your Gmail account. In Gmail, click the three-dot menu and select Show original. Verify:
Authentication-Results: mx.google.com;
  dkim=pass header.d=yourdomain.com;
  spf=pass;
  dmarc=pass header.from=yourdomain.com;
All three should show pass.
3

Verify DNS records with dig

Confirm your records are published correctly:
# DKIM record
dig TXT selector._domainkey.yourdomain.com +short

# DMARC record
dig TXT _dmarc.yourdomain.com +short

# SPF record (if applicable)
dig TXT yourdomain.com +short | grep spf

​
Pre-Production Checklist

Before switching from testing to production sending, work through this checklist:
Send a test email and verify dkim=pass, spf=pass, and dmarc=pass in the email headers. Do not proceed until all three pass. See Authentication Issues if any are failing.
Send test webhook events from the dashboard and confirm your endpoint handles them correctly. Verify signature verification is working. See Webhook Delivery Failures.
Test your email templates in Gmail, Outlook, and Apple Mail. Check both desktop and mobile rendering. See Email Content Rendering Issues.
Verify marketing emails include a visible unsubscribe link, a physical address, and that the List-Unsubscribe header is present. See Unsubscribe Best Practices.
Your integration should handle API errors (rate limits, validation errors, server errors) gracefully with appropriate retries. See Rate Limits and Errors and Retries.
Confirm your production environment has the correct API key, webhook secret, and any other configuration values. Do not use test or development keys in production.
If this is a new sending domain, prepare a warm-up schedule before sending at full volume. See IP and Domain Warm-Up.

​
Debugging Common Test Issues

IssueCauseFix
Test email not arrivingEmail went to spam folderCheck spam/junk folder; verify authentication passes
401 Unauthorized responseInvalid API keyVerify the key is correct and active in Settings > API Keys
422 Validation ErrorInvalid request bodyCheck the response body for specific field errors; verify from, to, subject, and html fields
Template variables not renderingMissing or incorrect variable syntaxVerify you’re passing the correct data object with matching variable names
Tracking links not workingCustom tracking domain not configuredSet up a tracking domain at Tracking Domains or use the default
Webhook test event not receivedEndpoint URL incorrect or server not runningVerify the URL in webhook settings and confirm your server is accessible from the internet

Sending Test Emails

Detailed guide to the test email feature.

Webhook Testing

Test your webhook integration end to end.

Authentication Issues

Fix API key and authentication problems.

Domain Verification

Resolve domain verification failures.