Email Intelligence - Get started

This page includes general requirements and service details for this product, as well as instructions on how to use all of its actions.

Looking for insights reason codes? Check out Email Intelligence - Insights reason code mappings.

Reference page

• Submit an email address to evaluate

General requirements

• Authentication: Basic (easiest to implement) or Digest
• Endpoint: https://detect.telesign.com/intelligence/email
• Encoding: Accepts only UTF-8 unicode characters as inputs.
• Accepts: application/x-www-form-urlencoded
• Responds With: application/json
• Required Headers: Content-Type - application/x-www-form-urlencoded

Understanding a risk recommendation for an email address

Email Intelligence provides a risk recommendation that you can use in combination with other elements to decide whether to allow, flag, or block an email address, or take any other measures such as additional verifications that you deem appropriate. risk.score is a measure of the transaction risk involved with conducting an online business transaction at the current time for the given email address. The scale ranges from zero to 1000, with a higher value indicating a higher risk.

The other details related to risk that are returned with risk.score are:

• risk.level: The risk level is an assessment of the level of transaction risk involved with conducting business at the current time for the email address.
• risk.recommendation: The risk recommendation is advice on the general course of action to follow for handling this transaction (to either proceed with the transaction, to proceed with caution, or to not proceed at all).

Insights

Insights is an option available in Email Intelligence that provides different details related to the risk presented by the email address. See Email Intelligence - Insights reason code mappings for more detail about each available insight.

Risk recommendation scale

Use this scale below to interpret the risk recommendation provided to you when you make a request.

Actions

Request a transaction risk recommendation for an email address

Reference Page: Submit an email address to evaluate

Use this action to obtain a transaction risk recommendation for a specified email address.

The reference page includes full details for each request parameter and response property.

Try it

If you have been granted access and credentials for Email Intelligence, you can try a test request by using the Submit an email address to evaluate endpoint. You can also get a code snippet for the request.

🚧

CAUTION:

Using your account credentials in the API Explorer to request a risk recommendation results in your account being charged for the transaction.

Examples

Valid request

POST /intelligence/email HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic pPF9MAXw9ssP0rkk8sbWf18Fny5Vgqi4F1owcHADr8LXk8PMWIvWqeg419NNXmBtMkaTJi3U5IOhOrNOY1ZXdBv3pLZxn08Rah8mMTGv623wYqmmNRcI5adDVnYbm1ejt2E4JCiMmOFahwcNcy844cpz8dTEWMVo1XthlYf=
Host: detect.telesign.com
phone_number=15555551212
account_lifecycle_event=create
originating_ip=203.0.113.45
email_address= [email protected]!

Valid response

{ 
  "reference_id": "CFMJ6FTL09O22UE1KC5NBD7ZMWKTMJB8", 
  "external_id": "CustomExternalID7349", 
  "status": { 
    "code": 300, 
    "description": "Transaction successfully completed", 
    "updated_on": "2025-01-06T21:25:03.420503Z" 
  },    
  "email_address_details": { 
	"original": { 
	  "email_address": "[email protected]!", 
	  "is_valid": false 
	}, 
	"cleansed": { 
	  "email_address": "[email protected]", 
	  "is_valid": true, 
          "username": "userr1",
	  "domain": "gmail.com" 
	}, 
	"cleansing_details": { 
	  "is_modified": true, 
	  "gibberish_probability": 0.29, 
	  "tag": "telesign" 
	}, 
	"domain_details": {   
	  "general info": { 
		"registered_domain": "gmail.com", 
		"tld": "com", 
		"tld_type": "general", 
		"is_disposable": true 
	  },		 
        }, 
  },
  "intelligence_details": { 
	"risk": { 
	  "level": "high", 
	  "recommendation": "block", 
          "score": 959 
	}, 
	"insights": { 
	  "category": [ 
             10032 
	   ], 
	  "phone_number": { 
	    "activity": [ 
	        20101, 
	    ], 
	    "static": [ 
		40005, 
		40011 
	    ] 
	  }, 
	  "ip_address": { 
	    "activity": [ 
	    ], 
	    "static": [ 
		50015
	    ] 
	  }, 
	  "email_address": { 
	    "activity": [ 
		60005, 
		60006 
	    ], 
	    "static": [ 
		60011 
	    ], 
	    "domain": [ 
		60013 
	    ] 
          } 
	}
  } 
} 

Invalid request

POST /intelligence/email HTTP/1.1  
Content-Type: application/x-www-form-urlencoded  
Authorization: Basic pPF9MAXw9ssP0rkk8sbWf18Fny5Vgqi4F1owcHADr8LXk8PMWIvWqeg419NNXmBtMkaTJi3U5IOhOrNOY1ZXdBv3pLZxn08Rah8mMTGv623wYqmmNRcI5adDVnYbm1ejt2E4JCiMmOFahwcNcy844cpz8dTEWMVo1XthlYf=  
Host: detect.telesign.com  
phone_number=15555551212  
account_lifecycle_event=create  
originating_ip=203.0.113.45  
email_address= 

Invalid response

{ 
 "reference_id": "866F5C70C1C800049030080E2C75D803", 
 "status": { 
    "code": 11000, 
    "description": "Invalid value for parameter email_address.", 
    "updated_on": "2026-01-19T16:35:07.515432Z" 
 }, 
 "external_id": null 
}