Getting Started

Lettr’s HTTP API sends an email in a single stateless request, which is the shape serverless platforms want. This guide covers the generic fetch call that works on AWS Lambda, Vercel, Cloudflare Workers, and any other function runtime, plus the retry and idempotency handling a production function needs. Using Cursor? Jump straight in using this prompt

Why HTTP instead of SMTP

Serverless functions are short-lived and stateless, and SMTP needs a persistent TCP connection with a multi-step handshake. A single HTTP request completes in milliseconds, holds no connection open between invocations, and needs no queue or database on the function side. Delivery retries to the recipient’s mail server happen inside Lettr, so the function returns as soon as the API accepts the message.

Prerequisites

API Key

Create an API key in the Lettr dashboard

Verified Domain

Add and verify your sending domain

Choose your platform

AWS Lambda

Send emails from AWS Lambda functions

Vercel Functions

Integrate with Vercel serverless functions

Cloudflare Workers

Send emails from Cloudflare Workers

Generic example

On any platform, a send is one POST to the emails endpoint. The request ID lives under data.data in the JSON body:

export async function handler(event) {
  const response = await fetch('https://app.lettr.com/api/emails', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.LETTR_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      from: 'you@yourdomain.com',
      to: ['recipient@example.com'],
      subject: 'Hello from Lettr',
      html: '<p>Sent from a serverless function!</p>',
    }),
  });

  const data = await response.json();

  if (!response.ok) {
    throw new Error(`Email sending failed: ${data.message}`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({
      message: 'Email sent',
      requestId: data.data.request_id,
    }),
  };
}

Store the API key in environment variables or the platform’s secrets manager, never in the function source.

Complete example with retries and idempotency

Serverless platforms retry failed invocations, and a function that times out mid-request cannot tell whether Lettr accepted the email. The Idempotency-Key header makes both cases safe. Reusing the same key and payload within 24 hours returns the original result instead of sending a second email, so the key has to be stable across retries and across invocations. Derive it from the business event, not from the attempt:

const idempotencyKey = `order-confirmation-${orderId}`;

The helper below retries network failures, unreadable success bodies, server errors, rate limits, and an in-progress idempotent request. Validation errors and other client errors are thrown before the retry path, so they fail immediately. Between attempts it honours Retry-After when present and otherwise sleeps a random interval under a capped exponential ceiling, so many clients recovering from the same outage do not retry in lockstep:

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Retry-After carries seconds or an HTTP date. Without it, back off exponentially with full jitter.
function retryDelay(attempt, retryAfter) {
  if (retryAfter) {
    const seconds = Number(retryAfter);
    const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(retryAfter) - Date.now();
    if (ms > 0) return ms;
  }
  const capMs = Math.min(30_000, 1_000 * 2 ** attempt);
  return Math.random() * capMs;
}

async function sendEmail({ to, subject, html, idempotencyKey }) {
  const payload = {
    from: process.env.FROM_EMAIL || 'noreply@yourdomain.com',
    to: Array.isArray(to) ? to : [to],
    subject,
    html,
  };
  const maxAttempts = 3;
  const body = JSON.stringify(payload);
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    let response = null;
    try {
      response = await fetch('https://app.lettr.com/api/emails', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.LETTR_API_KEY}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey,
        },
        body,
        signal: AbortSignal.timeout(30_000),
      });
    } catch (error) {
      // Network failure or timeout. The same key makes the retry safe either way.
      lastError = error;
    }

    let retryAfter = null;
    if (response) {
      // Gateway errors can carry a non-JSON body. Decide from the status either way.
      const data = (await response.json().catch(() => null)) ?? {};

      if (response.ok && data.data?.request_id) {
        if (response.headers.get('Idempotency-Replayed') === 'true') {
          console.log(`Replayed earlier send. Request ID: ${data.data.request_id}`);
        } else {
          console.log(`Email sent. Request ID: ${data.data.request_id}`);
        }
        return data;
      }

      if (response.ok) {
        // A 2xx with a truncated or malformed body. The same key replays the original result.
        lastError = new Error('Success response could not be parsed');
      } else {
        const retryable =
          response.status >= 500 ||
          response.status === 429 ||
          data.error_code === 'idempotency_in_progress';

        if (!retryable) {
          // 422 validation_error, 409 idempotency_key_conflict, 4xx in general
          throw new Error(`${data.error_code}: ${data.message}`);
        }

        lastError = new Error(`${response.status} ${data.error_code}: ${data.message}`);
        retryAfter = response.headers.get('Retry-After');
      }
    }

    if (attempt < maxAttempts) {
      console.error(`Attempt ${attempt} failed:`, lastError.message);
      await sleep(retryDelay(attempt, retryAfter));
    }
  }

  throw new Error(`Failed to send email after ${maxAttempts} attempts: ${lastError.message}`);
}

export async function handler(event) {
  const { orderId, email } = JSON.parse(event.body);

  try {
    await sendEmail({
      to: email,
      subject: `Order #${orderId} confirmed`,
      html: `<h1>Thanks for your order!</h1><p>Order #${orderId} is confirmed.</p>`,
      idempotencyKey: `order-confirmation-${orderId}`,
    });

    return { statusCode: 200, body: JSON.stringify({ success: true }) };
  } catch (error) {
    console.error('Email sending failed:', error);
    return { statusCode: 500, body: JSON.stringify({ error: error.message }) };
  }
}

The response table for idempotent requests, key format rules, and the 24-hour retention window are in the Idempotency guide.

Using the Lettr SDK

On platforms with npm support, the Node.js SDK wraps the same call:

import { Lettr } from 'lettr';

const lettr = new Lettr(process.env.LETTR_API_KEY);

export async function handler(event) {
  try {
    const result = await lettr.emails.send({
      from: 'you@yourdomain.com',
      to: ['recipient@example.com'],
      subject: 'Hello from Lettr',
      html: '<p>Sent from a serverless function!</p>',
    });

    return {
      statusCode: 200,
      body: JSON.stringify({ requestId: result.request_id }),
    };
  } catch (error) {
    console.error('Failed to send email:', error);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: error.message }),
    };
  }
}

The platform guides cover SDK installation and configuration:

Environment variables

Every platform supports environment variables. The examples above read these two:

LETTR_API_KEY=lttr_your_api_key_here
FROM_EMAIL=noreply@yourdomain.com

AWS Lambda: AWS Secrets Manager or Lambda environment variables
Vercel: the dashboard or vercel env add
Cloudflare Workers: wrangler secret put

Never commit API keys to version control.

Serverless-specific practices

Function timeout. A send call normally completes in under a second, but the retry loop above caps each request at 30 seconds and waits through several backoff intervals. Set the function timeout to cover the worst case rather than the happy path:

export const config = {
  maxDuration: 30, // Vercel
};

Bundle size. Cold starts scale with the amount of code loaded, so the built-in fetch beats an HTTP client dependency:

// Built-in, no dependencies
const response = await fetch(url, options);

// Adds bundle size for no gain here
const axios = require('axios');
await axios.post(url, data);

Request IDs. Log data.data.request_id on every send. It is the handle for the message in webhooks and the Events API.

Common patterns

Event-triggered emails

A function that reacts to an application event (signup, purchase) picks the content by event type. The idempotency key combines the event type with the entity so a redelivered event does not send twice:

export async function handler(event) {
  const { userId, email, action } = JSON.parse(event.body);

  const templates = {
    signup: {
      subject: 'Welcome to our app!',
      html: `<h1>Welcome!</h1><p>Thanks for signing up.</p>`,
    },
    purchase: {
      subject: 'Order confirmed',
      html: `<h1>Thanks for your order!</h1>`,
    },
  };

  const template = templates[action];

  await sendEmail({
    to: email,
    subject: template.subject,
    html: template.html,
    idempotencyKey: `${action}-${userId}`,
  });

  return { statusCode: 200 };
}

Batch processing

One invocation can fan out several sends in parallel. Each recipient gets its own key so a partial failure and re-run only sends to the recipients that did not go through:

export async function handler(event) {
  const { batchId, recipients } = JSON.parse(event.body);

  const results = await Promise.allSettled(
    recipients.map((recipient) =>
      sendEmail({
        to: recipient.email,
        subject: 'Batch email',
        html: `<p>Hello ${recipient.name}!</p>`,
        idempotencyKey: `batch-${batchId}-${recipient.id}`,
      })
    )
  );

  const successful = results.filter((r) => r.status === 'fulfilled').length;
  const failed = results.filter((r) => r.status === 'rejected').length;

  return {
    statusCode: 200,
    body: JSON.stringify({ successful, failed }),
  };
}

For sending to many recipients (100+), use batch sending with a single API call, or process in smaller chunks to stay inside the function timeout.

What’s next

Idempotency

Key rules, replay behaviour, and the 24-hour retention window

Errors & Retries

Which responses are safe to retry

API Reference

Complete API documentation

Documentation

Quickstart

Learn

Integrations

Resources

Getting Started

Why HTTP instead of SMTP

Prerequisites

API Key

Verified Domain

Choose your platform

AWS Lambda

Vercel Functions

Cloudflare Workers

Generic example

Complete example with retries and idempotency

Using the Lettr SDK

Environment variables

Serverless-specific practices

Common patterns

Event-triggered emails

Batch processing

What’s next

Idempotency

Errors & Retries

API Reference

​Why HTTP instead of SMTP

​Prerequisites

API Key

Verified Domain

​Choose your platform

AWS Lambda

Vercel Functions

Cloudflare Workers

​Generic example

​Complete example with retries and idempotency

​Using the Lettr SDK

​Environment variables

​Serverless-specific practices

​Common patterns

​Event-triggered emails

​Batch processing

​What’s next

Idempotency

Errors & Retries

API Reference

Why HTTP instead of SMTP

Prerequisites

Choose your platform

Generic example

Complete example with retries and idempotency

Using the Lettr SDK

Environment variables

Serverless-specific practices

Common patterns

Event-triggered emails

Batch processing

What’s next