Tag API

Overview

Tagging is used to score specific emails, emaildomains, domains, names, IPs, TLDs, CIDRs, and device fingerprints as good, bad, or to skip scoring. Items tagged as Bad will add negative scoring to the risk area, Good tags add positive scoring, and Do Not Score will set the item score to zero. Good and Bad scoring is incremental to standard area scoring. Tags can be managed in the Customer Portal or by using this Tag API.

To illustrate how tagging works, if you vet IP = 10.1.1.1, the vet will hit "Private or no geo IP" risk and score -10 for IP area. Adding tags of:

Bad will add -130 to the IP score area, and the IP will now score -140
Good will add +130 to the IP scoring area, and the IP will now score +120
Do Not Score will set the IP scoring to 0

API Calls

Adding, updating, and removing tags is done using the FEED API POST.

The API uses Content-Type: application/x-www-form-urlencoded

The API requires HTTPS POST when adding, removing, or updating data. Reports can be either POST or GET.

Add, Update, and Delete Tags

Use the function tag/set followed by required type and value pair(s) with a single required reason

type ip  email  emaildomain  domain  phone  name  fingerprint  tld  cidr  countrycode  (one required)
reason good  bad  do not score  delete  (one required)

For example, to tag IP 127.0.0.2 as bad:

$ curl -X POST -H Content-Type:application/x-www-form-urlencoded -d 'ip=127.0.0.2&reason=bad' https://feed-api.e-hawk.net/apikey/tag/set/

TLD tags will test against both emaildomain and domain. If you add 'xxx' as a TLD, the we will tag test@example.xxx and www.example.xxx.

Required and Special Formats:
- TLD send xxx for .xxx
- CIDR supports /24 to /31 only. Send as x.x.x.0/24
- countrycode are the two letter lowercase country codes (ISO codes)

The API also supports sending multiple items and types in a single call. For example to add good tags for two IPs and a domain, you just make the items an array using brackets [] after the type name:

$ curl -X POST -H Content-Type:application/x-www-form-urlencoded -d 'ip[]=1.1.1.1&ip[]=1.1.1.2&domain=e-hawk.net&reason=good'  https://feed-api.e-hawk.net/apikey/tag/set/

Each call can have only one reason, but you can send up to 50 items per call.

Tag Reports

Use the function tag/list followed by a required type and optional reason

type ip  email  emaildomain  domain  phone  name  fingerprint  tld  cidr  countrycode  (one required)
reason good  bad  do not score  (optional)

For example, to get a list of all IPs that are tagged Bad, Do a GET (report calls can be either POST or GET):

https://feed-api.e-hawk.net/apikey/tag/list/?type=ip&reason=bad

The report is returned in JSON format with a maximum of 500 items.

  • response string
    • items array
    • type array
      • value string
      • tag string
  • status number
{"response":{"items":{"ip":{"10.0.1.2":"bad","127.0.0.1":"bad"}}},"status":200}
Status Codes
Status Response
200 OK (no errors)
404 A valid type is required
502 Unknown reason
{"response":"A valid type is required","status":404}