Recipient Validation

Recipient Validation is an easy, efficient way to verify that email addresses are valid before you send. It runs addresses through a series of checks that catch many common problems, including syntax issues and non-existent mailboxes.

Learn more about the different response fields and read how to integrate Recipient Validation into your forms.

Validation Object

Each validation will respond with the following result.

Example

{
    "results": {
        "valid": false,
        "result": "undeliverable",
        "reason": "Invalid Domain",
        "is_role": false,
        "is_disposable": false,
        "delivery_confidence": 0
        "is_free": false
    }
}

Attributes

valid boolean

Whether or not the recipient domain (mx and a record check) and syntax of the email address is valid.

result enum

Overall status of this email address. Use this field to decide if you want to reject an email address.

Possible Values: valid, neutral, risky, undeliverable, typo

delivery_confidence number

Number 0-100 representing SparkPost’s confidence that the email address can be delivered to.

reason enum

The reason the result value was given. If the result is not undeliverable then no reason is given.

Possible Values: Invalid Syntax, Invalid Domain, Invalid Recipient

is_role boolean

Whether the email address is role-based

is_disposable boolean

Whether the email address is disposable

is_free boolean

Whether the email address is from a free email provider

did_you_mean string

The corrected email address if there is a typo in the provided address

Request

GET /api/v1/recipient-validation/single/some@ddress.com

Response

  {
      "results": {
          "result": "valid",
          "valid": true,
          "is_role": false,
          "is_disposable": false,
          "delivery_confidence": 85
          "is_free": true
      }
  }

  {
      "results": {
          "result": "undeliverable",
          "valid": false,
          "reason": "Invalid Domain"
           "is_role": false,
          "is_disposable": false,
          "delivery_confidence": 0,
          "is_free": false
      }
  }

{
  "results": {
    "result": "undeliverable",
    "valid": false,
    "reason": "Invalid Recipient",
    "is_role": false,
    "is_disposable": false,
    "delivery_confidence": 0,
    "is_free": false
  }
}

{
  "results": {
    "result": "risky",
    "valid": true,
    "is_role": false,
    "is_disposable": false,
    "delivery_confidence": 42,
    "is_free": false
  }
}

  {
      "results": {
          "result": "neutral",
          "valid": true,
          "is_role": false,
          "is_disposable": false,
          "is_free": false,
          "delivery_confidence": 51,
      }
  }

  {
      "results": {
          "result": "typo",
          "valid": false,
          "reason": "Invalid Domain",
          "is_role": false,
          "is_disposable": false,
          "is_free": false,
          "did_you_mean": recommendedemailaddress@goes.here,
          "delivery_confidence": 0,
      }
  }

Email Address Validation

GET/api/v1/recipient-validation/single/{address}

Parameters

address string required

Validate a single email address. The response will contain whether the address is valid, neutral, risky, undeliverable or typo along with additional metadata about the address. If the email address is undeliverable, a reason will also be provided. Use UTF-8 encoding for special characters like /.