Copy page

Emails

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, 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.

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

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:

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

Code
{
  "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:

Code
[
  {
    "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:

Code
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 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

Code
{
  "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 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.