Test Emails

Before sending emails to real recipients, you should verify that your templates render correctly, merge tags resolve to the expected values, and links point to the right destinations. Test emails let you send a real email through the full delivery pipeline — including template rendering and merge tag substitution — to your own inbox, without affecting your analytics or engagement metrics.

Two Ways to Test

Lettr gives you two complementary testing tools:

Test emails (this page) — real sends from your verified domain to addresses you choose, with tracking disabled and analytics excluded. Best for reviewing rendering across email clients and sharing previews with your team.
Sandbox API keys — a separate key type (lttr_sandbox_ prefix) that redirects every email to your own inbox regardless of the recipients in the request, sends from a pre-verified sandbox domain, and has no billing impact. Best for local development, CI pipelines, and testing before your domain is verified.

Sandbox keys support the same sending features as live keys — HTML, plain text, and AMP content, attachments, template sends with substitution_data, tags, metadata, and scheduled emails — so your test requests exercise the exact payloads you’ll use in production.

Send a Test Email

You can send test emails from the Lettr dashboard or via the regular send API. Test emails use the same rendering pipeline as production sends, so what you see in your inbox is exactly what your recipients will receive:

await lettr.emails.send({
  from: 'you@yourdomain.com',
  to: ['developer@example.com'],
  subject: 'Welcome to Acme',
  template_slug: 'welcome-email',
  substitution_data: {
    name: 'Test User',
    company: 'Acme Inc'
  }
});

Test with Custom HTML

Test custom HTML content without using a template:

await lettr.emails.send({
  from: 'you@yourdomain.com',
  to: ['developer@example.com'],
  subject: 'Test Email',
  html: '<h1>Testing</h1><p>This is a test email with {{name}}.</p>',
  substitution_data: {
    name: 'Preview Name'
  }
});

Multiple Test Recipients

When reviewing a template as a team, send the test to multiple recipients at once — developers, designers, and QA engineers can each verify the email in their preferred email client:

await lettr.emails.send({
  from: 'you@yourdomain.com',
  to: [
    'developer@example.com',
    'designer@example.com',
    'qa@example.com'
  ],
  subject: 'Order Confirmation Test',
  template_slug: 'order-confirmation',
  substitution_data: {
    order_id: 'TEST-12345',
    customer_name: 'Test Customer',
    total: '$99.99'
  }
});

Test Different Variables

Templates often contain conditional blocks that display different content based on the data provided. Test with both minimal and complete data sets to verify that conditionals, loops, and default values all render as expected:

// Test with minimal data
await lettr.emails.send({
  from: 'you@yourdomain.com',
  to: ['developer@example.com'],
  subject: 'Welcome',
  template_slug: 'welcome-email',
  substitution_data: {
    name: 'User'
  }
});

// Test with full data
await lettr.emails.send({
  from: 'you@yourdomain.com',
  to: ['developer@example.com'],
  subject: 'Welcome',
  template_slug: 'welcome-email',
  substitution_data: {
    name: 'John Smith',
    company: 'Acme Corporation',
    role: 'Administrator',
    features: ['Dashboard', 'Reports', 'API Access']
  }
});

Test Email Characteristics

Test emails behave differently from production sends in a few important ways:

Feature	Behavior
Tracking	Disabled by default
Analytics	Not counted in statistics
Webhooks	Events still fire (for testing webhooks)
Rate limits	Subject to normal rate limits

Testing in the Dashboard

The Lettr dashboard provides a visual test email feature:

Open your template in the editor
Click “Send Test Email”
Enter test recipient addresses
Optionally provide test variable data
Click “Send”

Use the dashboard preview to see how your email renders before sending test emails.

Best Practices

Test Across Email Clients

Rendering varies significantly between clients. Send test emails to Gmail (web and mobile), Outlook (Windows uses Word’s rendering engine, which handles CSS differently), Apple Mail, and at least one mobile client. Check layout, images, fonts, and button styling on each.

Test Edge Cases

Templates may break with unexpected data. Test with missing optional variables (to verify defaults), very long strings (to check truncation and wrapping), special characters and Unicode (to catch encoding issues), and empty arrays (to verify loop blocks render cleanly when there’s no data).

Test Links

Click every link in the test email to verify it resolves to the correct destination. Pay particular attention to merge tag links (e.g., {{tracking_url}}), unsubscribe links, and tracking-wrapped URLs. Broken links in transactional emails erode user trust.

Test Plain Text Version

If you include a plain text version, review it for readability. Confirm that links are displayed as full URLs, formatting is clear without HTML markup, and the content matches the HTML version. Some recipients and accessibility tools display only the text version.

Use Realistic Data

Synthetic data like “Test User” and “$0.00” can mask formatting issues. Test with data that resembles production values — real name lengths, actual currency amounts, realistic order item counts — to catch problems like truncated fields, misaligned columns, or overflowing containers.

Staging Environment

For automated integration tests or CI pipelines, the simplest option is a sandbox API key: configure your staging environment with a sandbox key instead of a live one, and every email is automatically contained — recipients are overridden to the key owner’s inbox, so no code changes are needed and nothing can reach customers. Alternatively, you can keep a live key and redirect recipients yourself:

const isProduction = process.env.NODE_ENV === 'production';

await lettr.emails.send({
  from: 'you@example.com',
  to: isProduction
    ? [realRecipient]
    : ['staging-inbox@example.com'],
  subject: 'Order Confirmation',
  template_slug: 'order-confirmation',
  substitution_data: orderData
});

Documentation

Quickstart

Learn

Integrations

Resources

Two Ways to Test

Send a Test Email

Test with Custom HTML

Multiple Test Recipients

Test Different Variables

Test Email Characteristics

Testing in the Dashboard

Best Practices

Staging Environment

​Two Ways to Test

​Send a Test Email

​Test with Custom HTML

​Multiple Test Recipients

​Test Different Variables

​Test Email Characteristics

​Testing in the Dashboard

​Best Practices

​Staging Environment

Two Ways to Test

Send a Test Email

Test with Custom HTML

Multiple Test Recipients

Test Different Variables

Test Email Characteristics

Testing in the Dashboard

Best Practices

Staging Environment