Best Practices

Delivering email reliably requires more than a working API integration. Your sender reputation, list quality, content, and authentication setup all affect whether emails reach the inbox or land in spam. This page consolidates the most impactful practices for maintaining high deliverability and building robust email integrations.

Sender Reputation

Your sender reputation is a score that email providers assign to your domain and IP based on your sending history. A strong reputation means emails reach the inbox; a poor one means they get filtered to spam or rejected entirely.

Warm Up New Domains

Email providers are suspicious of domains that suddenly start sending high volumes. Ramp up gradually over several weeks so providers can observe your sending patterns and build trust:

Week	Daily Volume
1	50-100
2	200-500
3	500-1,000
4	1,000-5,000
5+	Scale as needed

Sending high volumes immediately from a new domain can trigger spam filters and damage your reputation.

Monitor Key Metrics

Track these metrics to maintain good deliverability:

Metric	Target	Action if Exceeded
Bounce rate	< 2%	Clean your lists
Spam complaint rate	< 0.1%	Review content, add unsubscribe
Open rate	> 15%	Improve subject lines, sender name

List Hygiene

Sending to invalid or unengaged addresses is the fastest way to damage your reputation. Maintaining a clean recipient list reduces bounces, complaints, and wasted sends.

Validate Email Addresses

Filter out obviously invalid addresses before they reach the API. Basic format validation catches typos and malformed entries:

// Validate before adding to your list
function isValidEmail(email) {
  const re = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return re.test(email);
}

// Remove invalid addresses before sending
const validRecipients = recipients.filter(isValidEmail);

Use Double Opt-In

Confirm subscriptions to ensure valid, engaged recipients:

// Step 1: Send confirmation email
await lettr.emails.send({
  from: 'noreply@example.com',
  to: [newSubscriber.email],
  subject: 'Confirm your subscription',
  template_slug: 'subscription-confirmation',
  substitution_data: {
    confirmation_url: `https://example.com/confirm?token=${token}`
  }
});

// Step 2: Only add to list after confirmation

Handle Bounces Promptly

When an email hard-bounces, the address is permanently invalid. Continuing to send to it hurts your reputation. Set up a webhook handler to remove hard-bounced addresses from your lists immediately:

app.post('/webhooks/lettr', (req, res) => {
  const event = req.body;

  if (event.type === 'message.bounce') {
    const { to, bounceType } = event.data;

    if (bounceType === 'hard') {
      // Remove from all lists immediately
      removeFromAllLists(to);
    }
  }

  res.sendStatus(200);
});

Content Best Practices

The content of your emails affects both deliverability and engagement. Spam filters analyze subject lines, HTML structure, link quality, and text-to-image ratios when deciding whether to deliver your email to the inbox.

Include Unsubscribe Links

Unsubscribe links are legally required by CAN-SPAM and GDPR for marketing emails, and Google and Yahoo now require List-Unsubscribe headers for bulk senders. Including a clear unsubscribe mechanism also improves deliverability because recipients who can easily opt out are less likely to report your email as spam:

<p style="font-size: 12px; color: #666;">
  You're receiving this because you signed up at example.com.
  <a href="{{unsubscribe_url}}">Unsubscribe</a> |
  <a href="{{preferences_url}}">Manage preferences</a>
</p>

Use Clear Sender Information

Recipients are more likely to open emails from a recognizable sender. Use a consistent from_name that matches your brand, and set a reply_to address that reaches a real person or team:

await lettr.emails.send({
  from: 'updates@yourcompany.com',
  from_name: 'Your Company',  // Clear, recognizable name
  reply_to: 'support@yourcompany.com',
  // ...
});

Optimize Subject Lines

Subject lines determine whether recipients open your email. Keep them under 50 characters so they display fully on mobile devices, avoid all-caps words and spam trigger phrases (FREE, URGENT, ACT NOW) that filters flag, and personalize with the recipient’s name or relevant details when possible:

// Good
subject: 'Your order #12345 has shipped'

// Avoid
subject: 'FREE OFFER!!! ACT NOW!!!'

Technical Best Practices

Building a reliable email integration means handling failures gracefully, avoiding duplicate sends, and minimizing unnecessary API calls.

Implement Idempotency

Network failures and retries can cause the same email to be sent more than once. Use a database flag or distributed cache to track whether an email has already been sent for a given business event before calling the API:

async function sendOnce(emailData, idempotencyKey) {
  // Check local database or cache
  const alreadySent = await cache.get(idempotencyKey);
  if (alreadySent) {
    return { alreadySent: true, request_id: alreadySent };
  }

  const response = await lettr.emails.send({
    ...emailData,
    metadata: { ...emailData.metadata, idempotency_key: idempotencyKey }
  });

  // Record the send
  await cache.set(idempotencyKey, response.data.request_id, { ttl: 86400 });
  return response;
}

Use Webhooks Instead of Polling

Polling the API for delivery status wastes rate limit budget and introduces latency. Webhooks push events to your server the moment they occur, giving you real-time updates without any polling:

// Use webhooks for real-time delivery updates
app.post('/webhooks/lettr', (req, res) => {
  if (req.body.type === 'message.delivery') {
    updateDeliveryStatus(req.body.data);
  }
  res.sendStatus(200);
});

Handle Errors Gracefully

Distinguish between errors that should be retried (rate limits, server errors) and errors that indicate a problem with your request (validation, authentication). Use a job queue with exponential backoff for retryable errors:

try {
  await lettr.emails.send(emailData);
} catch (error) {
  if (error.status === 429) {
    // Queue for retry
    await queue.add('send-email', emailData, {
      delay: error.retryAfter * 1000
    });
  } else if (error.status === 422) {
    // Log validation error, don't retry
    logger.error('Invalid email data', { error: error.errors });
  } else {
    // Retry server errors
    await queue.add('send-email', emailData, {
      attempts: 3,
      backoff: { type: 'exponential', delay: 1000 }
    });
  }
}

Authentication Setup

Domain authentication is the foundation of good deliverability. Without SPF, DKIM, and DMARC, email providers have no way to verify that you’re authorized to send on behalf of your domain, and your emails are far more likely to be filtered or rejected.

Complete Domain Authentication

Set up all four authentication records for the strongest deliverability:

SPF Record

Authorizes Lettr to send on your behalf

DKIM Signing

Cryptographically signs your emails

DMARC Policy

Protects against spoofing

Custom Tracking Domain

Improves deliverability for tracked links

Domain Setup Guide

Complete guide to domain authentication

Checklist

Before First Send

For Each Send

Ongoing Maintenance

Email Usage & Quotas Inbound Introduction

Documentation

Quickstart

Learn

Integrations

Resources

Best Practices

Sender Reputation

Warm Up New Domains

Monitor Key Metrics

List Hygiene

Validate Email Addresses

Use Double Opt-In

Handle Bounces Promptly

Content Best Practices

Include Unsubscribe Links

Use Clear Sender Information

Optimize Subject Lines

Technical Best Practices

Implement Idempotency

Use Webhooks Instead of Polling

Handle Errors Gracefully

Authentication Setup

Complete Domain Authentication

Domain Setup Guide

Checklist

​Sender Reputation

​Warm Up New Domains

​Monitor Key Metrics

​List Hygiene

​Validate Email Addresses

​Use Double Opt-In

​Handle Bounces Promptly

​Content Best Practices

​Include Unsubscribe Links

​Use Clear Sender Information

​Optimize Subject Lines

​Technical Best Practices

​Implement Idempotency

​Use Webhooks Instead of Polling

​Handle Errors Gracefully

​Authentication Setup

​Complete Domain Authentication

Domain Setup Guide

​Checklist

Sender Reputation

Warm Up New Domains

Monitor Key Metrics

List Hygiene

Validate Email Addresses

Use Double Opt-In

Handle Bounces Promptly

Content Best Practices

Include Unsubscribe Links

Use Clear Sender Information

Optimize Subject Lines

Technical Best Practices

Implement Idempotency

Use Webhooks Instead of Polling

Handle Errors Gracefully

Authentication Setup

Complete Domain Authentication

Checklist