Skip to main content
Unlayer Docs

Deliverability & settings

Send only mail your recipients expect. Unlayer automatically suppresses addresses that hard-bounce or generate a spam complaint. This protection cannot be disabled.

Project email settings​

Read the current configuration:

curl https://api.unlayer.com/v3/emails/settings \
  -H "Authorization: Bearer unlayer_sk_xxx"

Update any subset of fields with PATCH:

curl -X PATCH https://api.unlayer.com/v3/emails/settings \
  -H "Authorization: Bearer unlayer_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "defaultFromName": "Acme" }'

Settings reference​

FieldTypeNotes
defaultFromNamestringDefault sender display name (max 255).

defaultFromName and display names in from cannot contain carriage returns, line feeds, <, >, ", or \. Invalid names return 400.

Suppression list​

Future sends to a suppressed address are rejected with 400 before they are queued. Hard bounces and complaints are always added automatically; you can also manage entries manually.

List suppressed addresses​

Console Settings → Suppression List includes Load more suppressions when additional entries are available.

Cursor-paginated (limit 1–200):

curl "https://api.unlayer.com/v3/emails/suppressions?limit=100" \
  -H "Authorization: Bearer unlayer_sk_xxx"
{
  "data": [
    {
      "email": "bounced@example.com",
      "reason": "hard_bounce",
      "createdAt": "2026-06-18T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

reason is one of hard_bounce, complaint, or manual.

Hard-bounce suppressions expire automatically after 90 days unless you remove them earlier. Complaint suppressions do not expire automatically and cannot be removed through the API. Manually added suppressions remain until you remove them.

Check one address​

curl "https://api.unlayer.com/v3/emails/suppressions/check?email=user@example.com" \
  -H "Authorization: Bearer unlayer_sk_xxx"

Add an address manually​

curl -X POST https://api.unlayer.com/v3/emails/suppressions \
  -H "Authorization: Bearer unlayer_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com", "reason": "manual" }'

Remove an address​

So it can receive mail again:

curl -X DELETE "https://api.unlayer.com/v3/emails/suppressions?email=user@example.com" \
  -H "Authorization: Bearer unlayer_sk_xxx"

Only manual and hard_bounce entries can be removed. Complaint suppressions are protected and return 403 Forbidden; a recipient's spam complaint must be honored.

Suppressions are scoped per project.

Sender reputation​

Suppression helps reduce repeat bounces and complaints, but it does not guarantee inbox placement. Send relevant messages to recipients who expect them, and monitor your bounce and complaint rates through webhooks and statistics.