> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Delivery Issues

> Work through a step-by-step checklist to diagnose and fix common email delivery problems in Lettr, from domain status to bounces

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

***

## Quick Diagnostic Checklist

<Steps>
  <Step title="Check your domain status">
    Open the [Domains page](https://app.lettr.com/domains) 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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## Common Issues

<AccordionGroup>
  <Accordion title="Domain Not Verified">
    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](https://app.lettr.com/domains) 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:

    ```bash theme={null}
    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:

    ```bash theme={null}
    curl https://app.lettr.com/api/domains \
      -H "Authorization: Bearer lttr_xxxxxxxxxxxx"
    ```

    <Note>
      DNS changes can take up to 48 hours to propagate, though most resolve within minutes.
    </Note>
  </Accordion>

  <Accordion title="Recipient Suppressed">
    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.

    <Warning>
      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.
    </Warning>

    See [Bounce Suppressions](/learn/suppressions/bounces) for more detail on how Lettr handles suppression rules.
  </Accordion>

  <Accordion title="Spam Filters Blocking">
    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](/knowledge-base/troubleshooting/spam-placement) for a full guide on diagnosing and fixing spam folder placement.
  </Accordion>

  <Accordion title="Rate Limited">
    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](/knowledge-base/troubleshooting/rate-limits) for details on current limits and strategies for handling them.
  </Accordion>

  <Accordion title="Invalid From Address">
    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 Code            | HTTP Status | Meaning                                               |
    | --------------------- | ----------- | ----------------------------------------------------- |
    | `validation_error`    | 422         | The `from` field is missing or malformed.             |
    | `invalid_domain`      | 400         | The domain in the `from` address is not recognized.   |
    | `unconfigured_domain` | 400         | The 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.
  </Accordion>
</AccordionGroup>

***

## 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:

```bash theme={null}
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 Code   | Meaning                                                      | Action                                                                                                                                  |
| ----------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `550 5.1.1` | Mailbox does not exist.                                      | Remove the address from your list. This is a hard bounce and the recipient is automatically suppressed.                                 |
| `550 5.7.1` | Message rejected by policy (spam, authentication, or block). | Check your SPF/DKIM/DMARC records and review your email content for spam triggers.                                                      |
| `452 4.2.2` | Mailbox full.                                                | This is a soft bounce. Lettr will retry automatically. If it persists, the recipient may have abandoned the mailbox.                    |
| `421 4.7.0` | Temporary 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:

```javascript theme={null}
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:

```bash theme={null}
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](mailto:support@lettr.com)**. Include the email request ID (returned in the API response when you sent the email) so the team can investigate quickly.

***

## Related Topics

<CardGroup cols={2}>
  <Card title="Spam Placement" icon="shield-exclamation" href="/knowledge-base/troubleshooting/spam-placement">
    Diagnose why emails land in the spam folder instead of the inbox.
  </Card>

  <Card title="Bounce Diagnosis" icon="rotate-exclamation" href="/knowledge-base/troubleshooting/bounce-diagnosis">
    Understand bounce types, codes, and how Lettr processes them.
  </Card>

  <Card title="Bounce Suppressions" icon="ban" href="/learn/suppressions/bounces">
    Learn how Lettr automatically suppresses addresses after bounces.
  </Card>

  <Card title="Domains" icon="globe" href="/learn/domains/introduction">
    Set up and verify your sending domains.
  </Card>
</CardGroup>