Skip to main content
When emails are not reaching your recipients, work through the steps below to identify and fix the issue.

​
Quick Diagnostic Checklist

1

Check your domain status

Open the Domains page in the Lettr dashboard. Your sending domain must show a status of approved and all DNS records must be valid. If anything shows pending, unverified, or invalid, resolve that first.
2

Check the suppression list

Navigate to Suppressions in the dashboard and search for the recipient address. If the address appears on the list, it was suppressed due to a previous bounce or complaint and Lettr will not attempt delivery.
3

Check the email status

Go to Emails in the dashboard and locate the specific message. The status and any error details will tell you whether the email was accepted, bounced, or failed to send.
4

Review bounce messages

If the email bounced, expand the event details in the dashboard to see the SMTP response code and message returned by the recipient server. These codes are explained further below.

​
Common Issues

Lettr requires a verified sending domain before it will transmit any email. If your domain status is pending or DNS records show unverified / invalid, emails will fail with an unconfigured_domain or invalid_domain error.To fix this:
  1. Open the Domains page in the dashboard.
  2. Click on the domain in question and review the required DNS records (SPF, DKIM, DMARC).
  3. Add or correct the records with your DNS provider.
  4. Click Verify in the dashboard, or trigger verification via the API:
curl -X POST https://app.lettr.com/api/domains/yourdomain.com/verify \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"
You can also check the current domain status:
curl https://app.lettr.com/api/domains \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"
DNS changes can take up to 48 hours to propagate, though most resolve within minutes.
If a recipient previously hard-bounced or filed a spam complaint, Lettr automatically adds them to your suppression list. Any future sends to that address will be silently blocked.Suppressions are managed entirely through the dashboard — there is no API endpoint for suppressions. Navigate to Suppressions, search for the address, and remove it if you believe the issue has been resolved.
Repeatedly sending to addresses that have hard-bounced damages your sender reputation. Only remove a suppression if you have confirmed the mailbox is valid again.
See Bounce Suppressions for more detail on how Lettr handles suppression rules.
If your email is delivered but lands in the spam folder, the problem is not a Lettr delivery failure — it is a placement issue driven by content, authentication, or reputation.See Troubleshooting Spam Placement for a full guide on diagnosing and fixing spam folder placement.
If you are sending a high volume of emails in a short period, you may encounter rate limiting. Lettr returns an HTTP 429 status when the limit is reached.See Rate Limits for details on current limits and strategies for handling them.
The from address in your API request must use a domain that is verified in your Lettr account. If it does not, the API will reject the request.Possible error codes:
Error CodeHTTP StatusMeaning
validation_error422The from field is missing or malformed.
invalid_domain400The domain in the from address is not recognized.
unconfigured_domain400The domain exists but DNS is not properly configured.
Make sure your from address matches a domain with approved status and valid DNS in the dashboard.

​
Checking Email Status

The fastest way to check the status of a specific email is through the Emails section of the Lettr dashboard, where you can search by recipient, subject, or request ID. You can also retrieve an email by its ID through the API: 
curl https://app.lettr.com/api/emails/{id} \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"
The response will include the current delivery status and any error information associated with the message.

​
Reading Bounce Messages

When a recipient server rejects an email, it returns an SMTP status code. Lettr surfaces these codes in the dashboard and through the email.bounced webhook event. Here are the most common codes and what to do about them:
SMTP CodeMeaningAction
550 5.1.1Mailbox does not exist.Remove the address from your list. This is a hard bounce and the recipient is automatically suppressed.
550 5.7.1Message rejected by policy (spam, authentication, or block).Check your SPF/DKIM/DMARC records and review your email content for spam triggers.
452 4.2.2Mailbox full.This is a soft bounce. Lettr will retry automatically. If it persists, the recipient may have abandoned the mailbox.
421 4.7.0Temporary rate limit from the recipient server.No action needed. Lettr will retry delivery. If the problem persists across many recipients at the same domain, slow your sending rate.
You can handle bounces programmatically using webhooks. The email.bounced event includes the bounce type and SMTP details: 
const express = require("express");
const app = express();

app.use(express.json());

app.post("/webhooks/lettr", (req, res) => {
  const { type, data } = req.body;

  if (type === "email.bounced") {
    console.log(`Bounce for ${data.to}`);
    console.log(`Type: ${data.bounceType}`);       // "hard" or "soft"
    console.log(`Category: ${data.bounceCategory}`);
    console.log(`Code: ${data.bounceCode}`);
    console.log(`Message: ${data.message}`);

    if (data.bounceType === "hard") {
      // Remove address from your mailing list
    }
  }

  res.sendStatus(200);
});

app.listen(3000);

​
Testing Deliverability

Send a test email to an address you control to confirm your setup is working end to end: 
curl -X POST https://app.lettr.com/api/emails \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "test@yourdomain.com",
    "to": "you@example.com",
    "subject": "Lettr delivery test",
    "html": "<p>If you can read this, delivery is working.</p>"
  }'
Check your inbox (and spam folder). If the email arrives, your domain and authentication are configured correctly. If it does not, work through the diagnostic checklist above.

​
Still Having Issues?

If you have worked through the steps above and emails are still not being delivered, contact the Lettr support team at support@lettr.com. Include the email request ID (returned in the API response when you sent the email) so the team can investigate quickly.

Spam Placement

Diagnose why emails land in the spam folder instead of the inbox.

Bounce Diagnosis

Understand bounce types, codes, and how Lettr processes them.

Bounce Suppressions

Learn how Lettr automatically suppresses addresses after bounces.

Domains

Set up and verify your sending domains.