Getting Started

Send transactional emails through Lettr’s SMTP relay server. If your application already uses SMTP or you’re migrating from another email provider, you can switch to Lettr without changing your code — just update your SMTP credentials. Using Cursor? Jump straight in using this prompt

Why Use SMTP?

SMTP is a good choice when:

Legacy applications — Your application already uses SMTP and changing to an HTTP API would require significant refactoring
Framework built-ins — Your framework has built-in mail functions that expect SMTP credentials (WordPress, Django, Rails, etc.)
Third-party integrations — You’re connecting a CMS, CRM, or other tool that only supports SMTP configuration
Gradual migration — You’re migrating from another email provider and want to minimize code changes

If you’re building a new application or have flexibility in your stack, consider using the HTTP API or one of our SDKs instead. The API offers better error handling, request tracking, and doesn’t require maintaining a persistent connection.

Prerequisites

Before you begin, make sure you have:

API Key

Create an API key in the Lettr dashboard

Verified Domain

Add and verify your sending domain

SMTP Credentials

Use the following settings to connect to Lettr’s SMTP server:

Setting	Value
Host	`smtp.lettr.com`
Port	`465` (recommended), `2465`, `25`, `587`, `2587`
Username	`lettr`
Password	Your API key (starts with `lttr_`)

Your SMTP password is your Lettr API key. Never commit this to version control or share it publicly. Store it in environment variables or a secrets manager.

The username is always the literal string lettr — the same for every account, not your email address. Your account is identified by the API key you send as the password.

Sender Address

The address in your message’s From: header must belong to a verified sending domain. Lettr validates that header address, not the SMTP envelope sender your client uses in MAIL FROM. Most libraries set both from the same value, but if you configure them separately, the From: header is the one that has to match. If the address isn’t on a verified domain, authentication still succeeds and the message is rejected afterwards, at the point your client sends the message body.

To test your SMTP setup before your domain is verified, use a sandbox API key as the password. Sandbox keys work over SMTP exactly like they do with the API: the domain requirement is waived, and every message is redirected to your own inbox instead of the real recipients.

Ports & Security

The port you choose determines the security protocol for your SMTP connection:

Type	Ports	Security
SMTPS	`465`, `2465`	Implicit TLS — establishes a secure connection immediately
STARTTLS	`25`, `587`, `2587`	Explicit TLS — starts unencrypted, then upgrades to a secure connection

We recommend using port 465 with implicit TLS for the best security and compatibility. Port 587 with STARTTLS is also widely supported.

If you’re behind a restrictive firewall, port 2465 and 2587 are alternate ports that often work when standard ports are blocked.

Quick Test with swaks

Verify your SMTP connection using swaks (Swiss Army Knife for SMTP):

swaks --to recipient@example.com \
  --from sender@yourdomain.com \
  --server smtp.lettr.com:465 \
  --auth LOGIN \
  --auth-user lettr \
  --auth-password "lttr_your_api_key_here" \
  --tlsc \
  --header "Subject: Hello from Lettr" \
  --body "This is a test email sent via SMTP."

If the connection succeeds, you’ll see output showing the SMTP conversation and a confirmation that the message was accepted.

swaks is available via package managers: brew install swaks (macOS), apt-get install swaks (Ubuntu/Debian), or download from jetmore.org/john/code/swaks.

BCC Is Not Private Over SMTP

Do not use BCC when sending over SMTP. Recipients you add with BCC are visible to everyone else on the message.BCC addresses are not carried in the message headers — your client passes them in the SMTP envelope, alongside the To and Cc addresses. Lettr’s SMTP relay reads recipients from that envelope and cannot tell which ones were meant to be blind, so every address is delivered as a regular To recipient.

To keep recipients hidden from one another, send a separate message to each one. If you’re sending the same content to many people, the HTTP API handles BCC correctly and supports batch sending with per-recipient personalization.

Limits

Limit	Value
Max recipients per message	50 (combined to, cc, bcc)
Max message size (including attachments)	50 MB
Failed authentication attempts	5 per 5 minutes, then a 15-minute block

The recipient limit matches the HTTP API. Exceeding it returns 452 Too many recipients.

Framework Integration Guides

Choose your framework or library for specific setup instructions:

Laravel

Configure Laravel’s mail system with SMTP

PHPMailer

Send emails with PHPMailer

Supabase

Send Supabase Auth emails through Lettr

Troubleshooting

Authentication Failed

If you see “Authentication failed” or “535 Authentication credentials invalid”:

Verify your API key is correct and starts with lttr_
Check that the username is exactly lettr (lowercase) — not your email address
Ensure your API key hasn’t been revoked in the dashboard
If the key is restricted to specific IP addresses, confirm the machine you’re sending from is on that list. This returns 535 Access denied. Your IP address is not allowed.

Temporarily Blocked After Failed Attempts

Five failed authentication attempts within five minutes will block your IP address for 15 minutes. While blocked, connections are refused with:

421 Too many authentication failures, try again later

The block applies to your IP address across every port, so switching ports won’t restore access — wait for it to expire. A successful login clears the counter, so fix the credential before retrying.

Connection Timeout

If the connection times out:

Check your firewall isn’t blocking outbound connections on the SMTP port
Try alternate ports (2465 or 2587)
Verify smtp.lettr.com resolves correctly: nslookup smtp.lettr.com

Many cloud providers and residential ISPs block outbound port 25 by default. Use 465 instead.

Authentication Works but the Message Is Rejected

If your client connects and logs in, then fails when sending the message body, the credentials are fine and the message itself was refused. Common causes:

The From: address isn’t on a verified sending domain. Note that Lettr checks the From: header, not the envelope sender
The message exceeds 50 recipients (452 Too many recipients) or 50 MB
Your account has reached its sending quota

Errors at this stage return 451 with the reason from the API. Sends are recorded in the dashboard alongside API sends, so check there for the full error.

TLS/SSL Errors

If you see TLS or SSL handshake errors:

Ensure you’re using the correct encryption setting for your port (implicit TLS for 465, STARTTLS for 587)
Update your TLS/SSL libraries if you’re using older versions
Some older SMTP clients may not support modern TLS versions — consider upgrading or using the HTTP API instead

SMTP vs API

Here’s a quick comparison to help you decide:

Feature	SMTP	HTTP API
Setup complexity	Low — standard SMTP config	Medium — requires SDK or HTTP client
Error handling	Limited — SMTP status codes only	Rich — detailed JSON error responses
Request tracking	No request ID returned	Returns `request_id` for tracking
Attachments	Standard MIME encoding	Base64 in JSON payload
BCC	Not private — BCC recipients are visible	Kept private
Templates	Not supported	Full template support
Metadata	Not supported	Custom metadata supported
Webhooks	Not supported	Full event tracking
Performance	Slower — persistent connection overhead	Faster — single HTTP request

Both SMTP and the HTTP API deliver emails with the same reliability and deliverability. The choice depends on your application’s needs and existing infrastructure.

What’s Next

Laravel SMTP Setup

Configure Laravel to send via SMTP

PHPMailer Setup

Use PHPMailer with Lettr SMTP

Supabase Setup

Send Supabase Auth emails through Lettr

API Reference

Explore the HTTP API alternative

WordPress

Send WordPress emails through Lettr

Integrations

Stripe, Supabase, and more

Documentation

Quickstart

Learn

Integrations

Resources

Getting Started

Why Use SMTP?

Prerequisites

API Key

Verified Domain

SMTP Credentials

Sender Address

Ports & Security

Quick Test with swaks

BCC Is Not Private Over SMTP

Limits

Framework Integration Guides

Laravel

PHPMailer

Supabase

Troubleshooting

SMTP vs API

What’s Next

Laravel SMTP Setup

PHPMailer Setup

Supabase Setup

API Reference

WordPress

Integrations

​Why Use SMTP?

​Prerequisites

API Key

Verified Domain

​SMTP Credentials

​Sender Address

​Ports & Security

​Quick Test with swaks

​BCC Is Not Private Over SMTP

​Limits

​Framework Integration Guides

Laravel

PHPMailer

Supabase

​Troubleshooting

​SMTP vs API

​What’s Next

Laravel SMTP Setup

PHPMailer Setup

Supabase Setup

API Reference

WordPress

Integrations

Why Use SMTP?

Prerequisites

SMTP Credentials

Sender Address

Ports & Security

Quick Test with swaks

BCC Is Not Private Over SMTP

Limits

Framework Integration Guides

Troubleshooting

SMTP vs API

What’s Next