Real-Time Validation Results

If your sub-account has the Real-Time List Cleaning add-on, SendPost checks each recipient address before it sends the email. The Validation webhook event tells you the result for every email, so you know which addresses are good and don’t need to check them again.

Real-Time List Cleaning is an add-on. Contact support to turn it on for a sub-account. Without the add-on, no addresses are checked and no Validation events are sent.

Turn it on

Validation events go to your account-level webhooks, never to the per-email webhookEndpoint.

Dashboard: open Webhooks, edit or create a webhook, and tick Validation.
API: set validated: true when you create or update a webhook.

{
  "url": "https://example.com/webhooks/sendpost",
  "enabled": true,
  "validated": true
}

An update that leaves out validated keeps its current value. To stop Validation events, send "validated": false.

The results

Each Validation event has event.type set to 82 and event.validationStatus set to one of four words:

`validationStatus`	What it means	Is the email sent?
`valid`	The recipient’s mail server confirmed the mailbox, or SendPost has delivered to this address before.	Yes
`invalid`	The mailbox or domain doesn’t exist, or the address failed a check before the mailbox check (see below).	No
`catch all`	The domain accepts mail for any address, so the mailbox can’t be confirmed.	Yes
`unknown`	The mail server gave a temporary or inconclusive answer, for example a full mailbox or a temporary block.	Yes

The value catch all contains a space. Match the four words exactly as shown.

event.smtpCode and event.smtpDescription hold the mail server’s reply, for example 550 and 5.1.1 The email account that you tried to reach does not exist. A catch all result uses SendPost’s own code 111 with the description Catch all domain. Free mailbox providers such as Gmail, Outlook and Yahoo are never reported as catch all.

What happens to an invalid email

An email whose address is invalid is not sent, and you also receive an event that says so:

Rejected by the mailbox check: you receive an SMTP Dropped event (type 26), and the address is added to your suppression list.
Stopped before the mailbox check: if the domain is a known typo domain (for example gmial.com), the address already hard-bounced on SendPost, or it is on SendPost’s blocklist, the email is dropped straight away. You receive a Dropped event (type 1) and a Validation event with invalid, code 554 and the drop reason in smtpDescription.

Addresses on your own suppression list are dropped without a check, so they get a Dropped event only, with no Validation event.

Example payload

{
  "event": {
    "eventID": "c1af52bc-d705-4199-b15f-4d257cddb81b",
    "type": 82,
    "messageID": "ded956e9-4c9e-4117-9e97-5c56315c63af",
    "accountID": 100,
    "subAccountID": 50441,
    "from": "notifications@example.com",
    "to": "no.such.user@example.org",
    "submittedAt": 1792141788568613635,
    "smtpCode": 550,
    "smtpDescription": "5.1.1 The email account that you tried to reach does not exist.",
    "validationStatus": "invalid"
  },
  "emailMessage": {
    "messageID": "ded956e9-4c9e-4117-9e97-5c56315c63af",
    "from": { "email": "notifications@example.com", "name": "" },
    "to": { "email": "no.such.user@example.org", "name": "" },
    "headers": {}
  }
}

event.messageID is the messageId returned when you sent the email, so you can match the result to the email and its other events. A Validation event is normally sent once per email and usually arrives within seconds of the send, before any Delivered event. In rare cases it can arrive twice, so de-duplicate on messageID.

Choose which results you receive

By default a webhook with Validation on receives all four results. To receive only some of them, set eventSubOptions.validated when you create or update the webhook, listing all four keys. A result set to false, or left out, is not sent. In the dashboard, use the checkboxes under Filter validation results.

An update replaces all of eventSubOptions. If you also filter Dropped reasons with eventSubOptions.dropped, send both objects in the same update, or the one you leave out goes back to everything on.

{
  "url": "https://example.com/webhooks/sendpost",
  "validated": true,
  "eventSubOptions": {
    "validated": {
      "valid": false,
      "invalid": true,
      "catchAll": true,
      "unknown": true
    }
  }
}

Skip the check for one email

If you already know an address is good, skip the check for that email. It is then sent without a check and gets no Validation event. Use either option:

skipValidation: true in the body of Send Email or Send Email With Template.
The header X-Sendpost-Validate: false in headers. This also works over SMTP relay and in SDK versions that don’t have skipValidation yet.

{
  "from": { "email": "notifications@example.com" },
  "to": [{ "email": "customer@example.com" }],
  "subject": "Your receipt",
  "htmlBody": "<p>Thanks for your order.</p>",
  "skipValidation": true
}

Both options can only turn the check off. They can’t turn it on for a sub-account without the add-on.

Test your endpoint

In the dashboard, open a webhook, choose Validation as the test event and click Test. Your endpoint receives a type 82 event with validationStatus set to valid for test@example.com. Test events are always sent, whatever your Validation setting and filters are.

API Reference

Email

Domain

Stats

Suppression

IP

Message

IPPools

Stats (A)

Sub-Account

Webhook

Real-Time Validation Results

Turn it on

The results

What happens to an invalid email

Example payload

Choose which results you receive

Skip the check for one email

Test your endpoint

​Turn it on

​The results

​What happens to an invalid email

​Example payload

​Choose which results you receive

​Skip the check for one email

​Test your endpoint

Turn it on

The results

What happens to an invalid email

Example payload

Choose which results you receive

Skip the check for one email

Test your endpoint