# TLS

Transport Layer Security (TLS) encrypts an email while it travels between mail servers. Lettermint lets you choose whether TLS is preferred or required for outbound delivery on each transactional and broadcast route.

This policy controls the connection from Lettermint to the recipient's mail server. It does not change how your application connects to the Lettermint API or [SMTP relay](/guides/send-email-with-smtp), and it does not provide end-to-end encryption after the receiving server accepts the email.

## TLS policies

| Policy | Delivery behavior | Tradeoff |
| --- | --- | --- |
| **Opportunistic** | Lettermint attempts TLS and can deliver without it when the receiving server does not support TLS. | Best compatibility and the default for new and existing routes. |
| **Enforced** | Lettermint requires a successful TLS connection and never falls back to unencrypted delivery. | Stronger transport requirements, but delivery fails when the receiving server cannot satisfy them. |

Use **Opportunistic** when reaching as many valid recipient servers as possible is the priority. Use **Enforced** when a message must not be delivered without transport encryption, such as account-security or other sensitive transactional email.

:::warning
Enforced TLS can reduce deliverability to mail servers with missing or invalid TLS support. Choose it only when failing the delivery is preferable to sending without TLS.
:::

## Configuration and precedence

The TLS policy can be configured at the route level and overridden for an individual email. Lettermint resolves the policy in this order:

1. A per-email Sending API setting or SMTP header
2. The selected transactional or broadcast route's TLS setting
3. **Opportunistic** when neither is configured

A per-email `opportunistic` override can therefore allow unencrypted fallback for one email sent through an enforced route. Likewise, `enforced` can protect one email without changing an opportunistic route.

### Dashboard

1. Open your project and go to **Routes**
2. Select a transactional or broadcast route
3. Open **Settings** and choose **Opportunistic** or **Enforced** under **TLS**
4. Save your changes

<Frame>
  ![Transactional route settings with TLS set to Enforced](/docs/images/routes/route-settings.png)
</Frame>

Inbound routes do not have an outbound TLS policy because they receive rather than deliver email.

### Team API

Update the default policy for a route through the Team API:

```bash
curl -X PUT "https://api.lettermint.co/v1/routes/{routeId}" \
  -H "Authorization: Bearer $LETTERMINT_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "tls": "enforced"
    }
  }'
```

Set `settings.tls` to `opportunistic` to restore unencrypted fallback for the route.

### Sending API

Use `settings.tls` to override the selected route for one email:

```json
{
  "from": "sender@yourdomain.com",
  "to": ["recipient@example.com"],
  "subject": "Security alert",
  "text": "A new device signed in to your account.",
  "settings": {
    "tls": "enforced"
  }
}
```

For batch sends, each item has its own policy:

```json
[
  {
    "from": "sender@yourdomain.com",
    "to": ["first@example.com"],
    "subject": "Security alert",
    "text": "A new device signed in to your account.",
    "settings": {
      "tls": "enforced"
    }
  },
  {
    "from": "sender@yourdomain.com",
    "to": ["second@example.com"],
    "subject": "Monthly update",
    "text": "Here is your monthly update.",
    "settings": {
      "tls": "opportunistic"
    }
  }
]
```

Omit `settings.tls` to use the route policy.

### SMTP

Add `X-LM-Override-TLS` to override the selected route for one SMTP message:

```text
X-LM-Override-TLS: enforced
```

The accepted values are `enforced` and `opportunistic`, case-insensitively. Surrounding whitespace is ignored. Lettermint rejects invalid values or duplicate `X-LM-Override-TLS` fields and removes the control header before delivery.

## Failures and retries

When **Enforced** is active, Lettermint fails the delivery if the recipient's mail server cannot establish an acceptable TLS session. This includes cases such as not offering STARTTLS, permanently rejecting it, or presenting an invalid or incompatible TLS configuration. Lettermint does not retry these deterministic policy failures without TLS.

A terminal enforced-TLS failure emits a [`message.failed`](/platform/webhooks/events#messagefailed) webhook with:

- `response.status_code` set to `550`
- `reason_code` set to `enforced_tls_failed`
- `reason` containing a human-readable description of the TLS failure

```json
{
  "event": "message.failed",
  "data": {
    "message_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "recipient": "user@example.com",
    "reason": "5.7.10 Encryption needed: recipient did not offer STARTTLS",
    "reason_code": "enforced_tls_failed",
    "response": {
      "status_code": 550
    }
  }
}
```

Temporary network, connection, or TLS errors continue through the normal retry process and can emit `message.soft_bounced` events. They become final failures only if the usual delivery retry window expires.

## Troubleshooting

If an enforced delivery fails:

1. Open the message in [Email Activity](/platform/emails/activity) and review its delivery events
2. Check `reason_code` in your `message.failed` webhook handler
3. Confirm that the recipient domain's mail servers currently offer a valid TLS connection
4. If unencrypted fallback is acceptable for that message, resend with an `opportunistic` override or change the route policy

Do not automatically resend sensitive email with a weaker policy unless that behavior is explicitly allowed by your security requirements.