NAV Navbar
shell
  • What is Apility.io
  • How to use the API
  • IP Check
  • Domain Check
  • Email Check
  • Geo IP look up
  • Objects
  • Errors
  • What is Apility.io

    Apility.io can be defined as Threat Intelligence SaaS for developers and product companies that want to know in realtime if their existing or potential users have been classified as 'abusers' by one or more of these lists.

    Automatic extraction processes extracts all the information in realtime, keeping the most up to date data available, saving yourself the hassle of extract and update regularly all these lists and the data.

    We have several language bindings! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    This example API documentation page was created with Slate. Feel free to edit it and submit pull requests if you want to improve this documentation.

    What does Apility.io offer?

    Apility.io offers an extremely simple and minimalistic REST style API to access in realtime to these lists and do the following simple question about the resource?

    Is this IP, domain or email stored in any blacklist?

    The answers to this question can be:

    A bad resource implies some kind of action from developers' side. A clean resource does not need any action from their side.

    What resources are listed?

    There are several different type of resources that will grow in time:

    What blacklists are in use?

    Blacklists change on a daily basis. Please follow the links in the main page.

    Where are the API endpoints servers deployed?

    There are multiple servers deployed worldwide in different Cloud Providers, scaling up and down automatically to handle peaks and valleys usage. If you don't care about using a non secure connection then the api can be reached at

    But if you care about non using a secured connection you can use SSL-terminated endpoints at:

    When you perform a request to this endpoint, thanks to the magic of DNS Anycast and latency-based resolution you will be served with the closest server available.

    How to use the API

    Design principles

    The access to the API has been developed to be simple, minimalistic and fast. We have followed the Keep it Simple (KISS) approach, with several different ways to access the data.

    To use the API you will need a API Key or Token that you will pass along your request. You need to sign up to get it, and yes, there is a free plan you can use as long as you want.

    API is restricted by this API Key. Each subscription plan is limited to a number of API requests per day. If you exceed that limit in a 24 hour period the service will return a 429 HTTP status code. If you need to make more requests you should consider a paid plan with more quota. You can know in real time the quota consumed daily from the Dashboard.

    Authentication

    To authorize with a header parameter, use this code:

    # With shell, you can just pass the correct header with each request
    curl "https://api.apility.net"
      -H "X-Auth-Token: UUID"
    

    To authorize with a query string parameter, use this code:

    # With shell, you can just pass the correct header with each request
    curl "https://api.apility.net/?token=UUID"
    

    Make sure to replace UUID with your API key.

    Apility.io uses API keys to allow access to the API. You need to sign up to get an API Key.

    Apility.io expects for the API Key to be included in all API requests made. It can be included as a header or as a query string parameter.

    X-Auth-Token: UUID

    Simple Model: GET requests and HTTP response codes

    Example: Is IP 1.2.3.4 in any blacklist?

    We will use curl from the command line.

    $ curl -I -X GET api.apility.net/badip/1.2.3.4 -H "X-Auth-Token: UUID"
    

    The response is:

    HTTP/1.1 200 OK
    CONTENT-TYPE: text/plain; charset=utf-8
    CONTENT-LENGTH: 7
    DATE: Tue, 21 Jun 2016 08:52:14 GMT
    SERVER: Python/3.5 aiohttp/0.21.6
    

    The HTTP 200 (OK) code means the IP 1.2.3.4 belongs to any blacklist.

    Example: Is IP 8.8.8.8 in any blacklist?

    We will use curl from the command line.

    $ curl -I -X GET api.apility.net/badip/8.8.8.8 -H "X-Auth-Token: UUID"
    

    The response is:

    HTTP/1.1 404 Not Found
    CONTENT-TYPE: text/plain; charset=utf-8
    CONTENT-LENGTH: 18
    DATE: Sun, 26 Jun 2016 15:41:40 GMT
    SERVER: Python/3.5 aiohttp/0.21.6
    

    The HTTP 404 (Not Found) code means the IP 8.8.8.8 does not belong to any blacklist (8.8.8.8 is a public DNS by Google, which makes a lot of sense to not be in any blacklist of abusers...)

    The easiest way to use the API get advantage of GET requests and responses with standard HTTP codes. In this model, a HTTP 200 (OK) response code means that the value passed in the request belongs to any lists and therefore is a bad resource. If the answer is a HTTP 404 (Not found) code that means it does not belong to any lists and therefore is a clean resource.

    Developers just need to check the status code returned in the response. If code is 200 (OK), then the resource was found in any list and it's a bad resource. If the code is 404 (Not found), the resource was not found in any list.

    Advanced Model: GET requests, JSON and HTTP response codes

    Example: Is domain gmail.com in any blacklist?

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET https://api.apility.net/baddomain/gmail.com
    

    The response is:

    {  
       "type":"baddomain",
       "response":{  
          "domain":{  
             "mx":[  
                "alt4.gmail-smtp-in.l.google.com",
                "alt2.gmail-smtp-in.l.google.com",
                "gmail-smtp-in.l.google.com",
                "alt1.gmail-smtp-in.l.google.com",
                "alt3.gmail-smtp-in.l.google.com"
             ],
             "ns":[  
                "ns3.google.com.",
                "ns4.google.com.",
                "ns1.google.com.",
                "ns2.google.com."
             ],
             "blacklist_mx":[ ],
             "blacklist_ns":[ ],
             "blacklist":[  
                "FREEMAIL"
             ],
             "score":-1
          },
          "score":-1,
          "source_ip":{  
             "score":0,
             "geo":{},
             "is_quarantined":false,
             "blacklist":[ ]
          },
          "ip":{  
             "score":0,
             "geo":{  
                "country":"US",
                "continent":"NA",
                "hostname":"mad06s25-in-f5.1e100.net.",
                "city":"Mountain View",
                "as":{  
                   "country":"US",
                   "asn":"15169",
                   "name":"GOOGLE - Google Inc."
                },
                "region":"California",
                "postal":"94043",
                "address":"216.58.201.133",
                "longitude":-122.0574,
                "latitude":37.419200000000004
             },
             "is_quarantined":false,
             "blacklist":[ ]
          }
       }
    }
    

    Gmail is in the blackist FREEMAIL. It contains a catalog of Free Email services worldwide. You can remove FREEMAIL from the blacklists from the dashboard if you don't want to restrict access to Free Email services.

    This model follows the approach of the simple model, but allows to know the blacklists the requested resource is. This model still follow that if the response is an HTTP code 200 (OK) means that the value passed in the request is part of the lists and therefore is a bad resource. But this answer returns a set of list names the resource belongs to.

    And if the answer is an HTTP 404 (Not found) code means that the value cannot be found in the lists and therefore is a clean resource.

    To use Advanced Model, the developer needs to add to the header of the requests the application/json response Accept:

    Developers will need to parse and analyze the JSON object returned in their applications.

    JSONP support

    Example: Is email marketing@apility.io in any blacklist?

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail/marketing@apility.io?callback=myfunction"
    

    The response is:

    myfunction(
    {"error":
        { "message": "Resource not found",
          "status": 404
        }
    });
    

    The marketing email from Apility.io is not in any blacklist, and the error comes as a JSON payload inside a function call as JSONP needs.

    Example: Is domain mailinator.com in any blacklist?

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain/mailinator.com?callback=myfunction"
    

    The response is:

    myfunction(
    {"blacklists": ["IVOLO-DED", "DEA"]}
    );
    

    Mailinator is a very well known Disposible Email Address provider, and the response returns as a JSON payload inside a function call as JSONP needs.

    JSONP (JSON with Padding or JSON-P) is a technique used by web developers to overcome the cross-domain restrictions imposed by browsers' same-origin policy that limits access to resources retrieved from origins other than the one the page was served by. Read more details in the wikipedia

    The developer does not need to add to the header of the requests the application/json response Accept, it will be added implicit when the parameter callback is passed:

    With JSONP requests some client side libraries can't manage HTTP codes properly, so the error responses are returned as JSON payload as follows:

    CORS restrictions

    Cross-Origin Resource Sharing (CORS) is a mechanism that uses additional HTTP headers to let a user agent gain permission to access selected resources from a server on a different origin (domain) than the site currently in use. A user agent makes a cross-origin HTTP request when it requests a resource from a different domain, protocol, or port than the one from which the current document originated.

    Paid plans can configure the allowed referers site to prevent unauthorized use and quota theft. Key restriction lets you specify which web sites, IP addresses, or apps can use this key. You can test this feature during the 30 days trail period.

    IP Address restrictions

    Paid plans can restrict the source IP of the requests to prevent unauthorized use and quota theft. You can test this feature during the 30 days trail period.

    IP Check

    Apility.io tracks multiple abuse blacklists and consolidates them in a single database you can look up with our minimalist API.

    Check if an IP belongs to any abusers' blacklist

    $ curl -I -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/badip/<IP>"
    

    The response can be:

    HTTP/1.1 200 OK
    CONTENT-TYPE: text/plain; charset=utf-8
    CONTENT-LENGTH: 7
    DATE: X
    SERVER: Python/3.5 aiohttp/0.21.6
    

    or

    HTTP/1.1 404 Not Found
    CONTENT-TYPE: text/plain; charset=utf-8
    CONTENT-LENGTH: 18
    DATE: X
    SERVER: Python/3.5 aiohttp/0.21.6
    

    This endpoint returns if the IP belongs to any list with the HTTP status code in the response.

    HTTP Request

    GET https://api.apility.net/badip/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP The IP to look up in the system.

    Response

    The response can be a 200 or 404 HTTP code if everything is ok:

    Get all abusers' blacklist an IP belongs to

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/badip/<IP>"
    

    The response can be:

    {
        "blacklists": ["STOPFORUMSPAM-180", "STOPFORUMSPAM-30", "STOPFORUMSPAM-7", "STOPFORUMSPAM-365", "STOPFORUMSPAM-90"]
    }
    

    or

    Resource Not found
    

    If a developer wants to know what blacklists contain the IP passed as argument, she needs to pass to curl an extra argument with information about the Content type as application/json:

    HTTP Request

    GET https://api.apility.net/badip/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept Yes application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP The IP to look up in the system.

    Response

    The status code of the response can be a 200 or 404 HTTP code if everything is ok, but it will also return the following JSON structure if status code is 200:

    Parameter Description
    blacklists Array with a list with the Identifiers of each blacklist.

    Get all abusers' blacklist a set of IP belong to (Bulk request)

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/badip_batch/<IP1>,<IP2>...<IPn>"
    

    The response can be:

    {
        "badip_batch": [
            {
                "ip": "8.8.8.8",
                "blacklists": []
            },
            {
                "ip": "212.231.122.12",
                "blacklists": []
            },
            {
                "ip": "1.2.3.4",
                "blacklists": ["STOPFORUMSPAM-180", "STOPFORUMSPAM-30", "STOPFORUMSPAM-7", "STOPFORUMSPAM-365", "STOPFORUMSPAM-90"]
            }
        ]
    }
    

    A developer can save time and rate-limit restrictions if she passes a list of comma separated IP in the QueryString. She will get the blacklists for each IP in the response. If the IP is not well formed it will return nothing for that IP, but will perform the lookup for the rest of the valid IP:

    HTTP Request

    GET https://api.apility.net/badip_batch/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept No application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP1,IP2,...IPn The comma separated list of IP to look up in the system.

    Response

    The status code of the response can be a 200 if everything is ok, but it will also return the following JSON structure:

    Parameter Description
    response Array with a list with the blacklists for each IP.

    Domain Check

    Domain check implements an algorithm that assigns a score to the domain based on several checks done by the system:

    By default if some of these tests success, a -1 score is added to the overall score of the domain. So an overall score of -3 means the chances of being a bad domain are higher than -1.

    Check if a domain scores a negative or neutral score.

    Check a "clean" domain

    $ curl -I -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain/google.com"
    

    The response:

    HTTP/1.1 404 Not Found
    Server: nginx/1.10.3 (Ubuntu)
    Date: Fri, 24 Nov 2017 13:59:42 GMT
    Content-Type: text/plain; charset=utf-8
    Content-Length: 18
    Connection: keep-alive
    

    Check a "bad" domain

    $ curl -I -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain/mailinator.com"
    
    HTTP/1.1 200 OK
    Server: nginx/1.10.3 (Ubuntu)
    Date: Fri, 24 Nov 2017 14:00:50 GMT
    Content-Type: text/plain; charset=utf-8
    Content-Length: 7
    Connection: keep-alive
    Strict-Transport-Security: max-age=63072000; includeSubdomains
    X-Frame-Options: DENY
    X-Content-Type-Options: nosniff
    

    This endpoint returns in the HTTP status code of the response if the domain has a neutral or a negative score. A negative score means that the domain has been classified as 'bad' by the algorithm.

    HTTP Request

    GET https://api.apility.net/baddomain/<DOMAIN>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    DOMAIN The Domain name to look up in the system.

    Response

    The response can be a 200 or 404 HTTP code if everything is ok:

    Get individual scores of a domain

    Get all information from a "clean" domain

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain/google.com"
    

    The response can be:

    {
       "response":{
          "domain":{
             "score":0,
             "blacklist_ns":[],
             "mx":[
                "alt2.aspmx.l.google.com",
                "alt1.aspmx.l.google.com",
                "aspmx.l.google.com",
                "alt4.aspmx.l.google.com",
                "alt3.aspmx.l.google.com"
             ],
             "blacklist_mx":[],
             "blacklist":[],
             "ns":[
                "ns2.google.com.",
                "ns3.google.com.",
                "ns1.google.com.",
                "ns4.google.com."
             ]
          },
          "score":0,
          "ip":{
             "score":0,
             "is_quarantined":false,
             "address":"74.125.133.102",
             "blacklist":[]
          },
          "source_ip":{
             "score":0,
             "is_quarantined":false,
             "address":"2.137.249.73",
             "blacklist":[]
          }
       },
       "type":"baddomain"
    }
    

    Get all information from a "bad" domain

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain/mailinator.com"
    

    The response can be:

    {
       "response":{
          "domain":{
             "score":-1,
             "blacklist_ns":[
    
             ],
             "mx":[
                "mail2.mailinator.com",
                "mail.mailinator.com"
             ],
             "blacklist_mx":[
    
             ],
             "blacklist":[
                "IVOLO-DED",
                "DEA"
             ],
             "ns":[
                "betty.ns.cloudflare.com.",
                "james.ns.cloudflare.com."
             ]
          },
          "score":-1,
          "ip":{
             "score":0,
             "is_quarantined":false,
             "address":"104.25.198.31",
             "blacklist":[
    
             ]
          },
          "source_ip":{
             "score":0,
             "is_quarantined":false,
             "address":"2.137.249.73",
             "blacklist":[
    
             ]
          }
       },
       "type":"baddomain"
    }
    

    This endpoint returns a full JSON structure with individual details about the score of the different domains and IP analyzed by the algorithm. The request always returns the status code 200 (HTTP OK) no matter if the domain is bad or clean.

    HTTP Request

    GET https://api.apility.net/baddomain/<DOMAIN>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept Yes application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    DOMAIN The Domain name to look up in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing the 'Domain' object.
    type String describing the response type: baddomain

    Get all the scores of a set of domains (Bulk request)

    Get all information from a set of domain

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/baddomain_batch/google.com,moocher.io,apility.io,mailinator.com"
    

    The response can be:

    {
        "baddomain_batch": [
            {
                "domain": "apility.io",
                "scoring": {
                    "score": 0,
                    "source_ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "127.0.0.1"
                    },
                    "domain": {
                        "score": 0,
                        "blacklist_ns": [],
                        "ns": [
                            "alex.ns.cloudflare.com.",
                            "pam.ns.cloudflare.com."
                        ],
                        "mx": [
                            "aspmx.l.google.com",
                            "aspmx2.googlemail.com",
                            "aspmx3.googlemail.com",
                            "alt1.aspmx.l.google.com",
                            "alt2.aspmx.l.google.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": []
                    },
                    "ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "104.31.76.225"
                    }
                }
            },
            {
                "domain": "moocher.io",
                "scoring": {
                    "score": 0,
                    "source_ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "127.0.0.1"
                    },
                    "domain": {
                        "score": 0,
                        "blacklist_ns": [],
                        "ns": [
                            "alex.ns.cloudflare.com.",
                            "pam.ns.cloudflare.com."
                        ],
                        "mx": [
                            "aspmx.l.google.com",
                            "alt2.aspmx.l.google.com",
                            "alt4.aspmx.l.google.com",
                            "alt1.aspmx.l.google.com",
                            "alt3.aspmx.l.google.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": []
                    },
                    "ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "104.18.45.187"
                    }
                }
            },
            {
                "domain": "gmail.com",
                "scoring": {
                    "score": -1,
                    "source_ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "127.0.0.1"
                    },
                    "domain": {
                        "score": -1,
                        "blacklist_ns": [],
                        "ns": [
                            "ns4.google.com.",
                            "ns1.google.com.",
                            "ns2.google.com.",
                            "ns3.google.com."
                        ],
                        "mx": [
                            "alt3.gmail-smtp-in.l.google.com",
                            "alt4.gmail-smtp-in.l.google.com",
                            "alt2.gmail-smtp-in.l.google.com",
                            "gmail-smtp-in.l.google.com",
                            "alt1.gmail-smtp-in.l.google.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": [
                            "FREEMAIL"
                        ]
                    },
                    "ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "216.58.214.165"
                    }
                }
            },
            {
                "domain": "mailinator.com",
                "scoring": {
                    "score": -1,
                    "source_ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "127.0.0.1"
                    },
                    "domain": {
                        "score": -1,
                        "blacklist_ns": [],
                        "ns": [
                            "betty.ns.cloudflare.com.",
                            "james.ns.cloudflare.com."
                        ],
                        "mx": [
                            "mail2.mailinator.com",
                            "mail.mailinator.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": [
                            "MARTENSON-DED",
                            "DEA",
                            "IVOLO-DED"
                        ]
                    },
                    "ip": {
                        "score": 0,
                        "blacklist": [],
                        "is_quarantined": false,
                        "address": "104.25.198.31"
                    }
                }
            }
        ]
    }
    

    A developer can save time and rate-limit restrictions if she passes a list of comma separated domains in the QueryString. She will get the scoring and full JSON structure for each domain in the response. If the domain is not well formed it will return nothing for that domain, but will perform the lookup for the rest of the valid domains:

    HTTP Request

    GET https://api.apility.net/baddomain_batch/<DOMAIN1>,<DOMAIN2>,...,<DOMAINn>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept No application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    DOMAIN1,DOMAIN2,...,DOMAINn The list of Domain names to lookup in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing a list of JSON structures with the domain name and a 'Domain' object.

    Email Check

    Email check implements an algorithm as a superset of the used for the domain analysis that assigns a score to the email based on several checks done by the system:

    By default if some of these tests success, a -1 score is added to the overall score of the email. So an overall score of -3 means the chances of being a bad email are higher than -1.

    Check if an email scores a negative or neutral score.

    Check a "clean" email

    $ curl -I -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail/support@apility.io"
    

    The response:

    HTTP/1.1 404 Not Found
    Server: nginx/1.10.3 (Ubuntu)
    Date: Fri, 24 Nov 2017 15:42:53 GMT
    Content-Type: text/plain; charset=utf-8
    Content-Length: 18
    Connection: keep-alive
    

    Check a "bad" email

    $ curl -I -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail/test@mailinator.com"
    
    HTTP/1.1 200 OK
    Server: nginx/1.10.3 (Ubuntu)
    Date: Fri, 24 Nov 2017 15:43:55 GMT
    Content-Type: application/json; charset=utf-8
    Content-Length: 809
    Connection: keep-alive
    Strict-Transport-Security: max-age=63072000; includeSubdomains
    X-Frame-Options: DENY
    X-Content-Type-Options: nosniff
    

    This endpoint returns in the HTTP status code of the response if the email has a neutral or a negative score. A negative score means that the email has been classified as 'bad' by the algorithm.

    HTTP Request

    GET https://api.apility.net/bademail/<EMAIL>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    EMAIL The Email name to look up in the system.

    Response

    The response can be a 200 or 404 HTTP code if everything is ok:

    Get individual scores of an email

    Get all information from a "clean" email

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail/ceo@apility.io"
    

    The response can be:

    {
       "response":{
          "score":0,
          "address":{
             "score":0,
             "is_role":false,
             "is_well_formed":true
          },
          "ip":{
             "score":0,
             "is_quarantined":false,
             "address":"52.218.49.2",
             "blacklist":[
    
             ]
          },
          "smtp":{
             "exist_mx":true,
             "score":0,
             "exist_address":false,
             "exist_catchall":false
          },
          "freemail":{
             "score":0,
             "is_freemail":false
          },
          "domain":{
             "score":0,
             "blacklist_ns":[
    
             ],
             "mx":[
                "aspmx.l.google.com",
                "aspmx2.googlemail.com",
                "aspmx3.googlemail.com",
                "alt1.aspmx.l.google.com",
                "alt2.aspmx.l.google.com"
             ],
             "blacklist_mx":[
    
             ],
             "blacklist":[
    
             ],
             "ns":[
                "ns-1395.awsdns-46.org.",
                "ns-1635.awsdns-12.co.uk.",
                "ns-213.awsdns-26.com.",
                "ns-614.awsdns-12.net."
             ]
          },
          "email":{
             "score":0,
             "blacklist":[
    
             ]
          },
          "source_ip":{
             "score":0,
             "is_quarantined":false,
             "address":"2.137.249.73",
             "blacklist":[
    
             ]
          },
          "disposable":{
             "score":0,
             "is_disposable":false
          }
       },
       "type":"bademail"
    }
    

    Get all information from a "bad" email

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail/test@mailinator.com"
    

    The response can be:

    {
       "response":{
          "score":-3,
          "address":{
             "score":0,
             "is_role":false,
             "is_well_formed":true
          },
          "ip":{
             "score":0,
             "is_quarantined":false,
             "address":"104.25.199.31",
             "blacklist":[
    
             ]
          },
          "smtp":{
             "exist_mx":true,
             "score":0,
             "exist_address":false,
             "exist_catchall":false
          },
          "freemail":{
             "score":0,
             "is_freemail":false
          },
          "domain":{
             "score":-1,
             "blacklist_ns":[
    
             ],
             "mx":[
                "mail2.mailinator.com",
                "mail.mailinator.com"
             ],
             "blacklist_mx":[
    
             ],
             "blacklist":[
                "IVOLO-DED",
                "DEA"
             ],
             "ns":[
                "betty.ns.cloudflare.com.",
                "james.ns.cloudflare.com."
             ]
          },
          "email":{
             "score":-1,
             "blacklist":[
                "STOPFORUMSPAM-90",
                "STOPFORUMSPAM-180",
                "STOPFORUMSPAM-365"
             ]
          },
          "source_ip":{
             "score":0,
             "is_quarantined":false,
             "address":"2.137.249.73",
             "blacklist":[
    
             ]
          },
          "disposable":{
             "score":-1,
             "is_disposable":true
          }
       },
       "type":"bademail"
    }
    

    This endpoint returns a full JSON structure with individual details about the score of the different domains, IP, SMTP and other parameters analyzed by the algorithm. The request always returns the status code 200 (HTTP OK) no matter if the domain is bad or clean.

    HTTP Request

    GET https://api.apility.net/bademail/<EMAIL>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept Yes application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    EMAIL The Email name to look up in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing the 'Email' object.
    type String describing the response type: baddomain

    Get all the scores of a set of emails (Bulk requests)

    Get all information from a set of emails

    $ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/bademail_batch/test@moocher.io,test@apility.io,test@mailinator.com"
    

    The response can be:

    {
        "bademail_batch": [
            {
                "email": "test@moocher.io",
                "scoring": {
                    "score": 0,
                    "smtp": {
                        "score": 0,
                        "exist_address": false,
                        "exist_mx": true,
                        "exist_catchall": false
                    },
                    "domain": {
                        "score": 0,
                        "blacklist_ns": [],
                        "ns": [
                            "alex.ns.cloudflare.com.",
                            "pam.ns.cloudflare.com."
                        ],
                        "mx": [
                            "aspmx.l.google.com",
                            "alt2.aspmx.l.google.com",
                            "alt4.aspmx.l.google.com",
                            "alt1.aspmx.l.google.com",
                            "alt3.aspmx.l.google.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": []
                    },
                    "freemail": {
                        "score": 0,
                        "is_freemail": false
                    },
                    "ip": {
                        "score": 0,
                        "address": "104.18.44.187",
                        "is_quarantined": false,
                        "blacklist": []
                    },
                    "source_ip": {
                        "score": 0,
                        "address": "127.0.0.1",
                        "is_quarantined": false,
                        "blacklist": []
                    },
                    "disposable": {
                        "score": 0,
                        "is_disposable": false
                    },
                    "email": {
                        "score": 0,
                        "blacklist": []
                    },
                    "address": {
                        "score": 0,
                        "is_role": false,
                        "is_well_formed": true
                    }
                }
            },
            {
                "email": "test@apility.io",
                "scoring": {
                    "score": 0,
                    "smtp": {
                        "score": 0,
                        "exist_address": false,
                        "exist_mx": true,
                        "exist_catchall": false
                    },
                    "domain": {
                        "score": 0,
                        "blacklist_ns": [],
                        "ns": [
                            "alex.ns.cloudflare.com.",
                            "pam.ns.cloudflare.com."
                        ],
                        "mx": [
                            "aspmx.l.google.com",
                            "aspmx2.googlemail.com",
                            "aspmx3.googlemail.com",
                            "alt1.aspmx.l.google.com",
                            "alt2.aspmx.l.google.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": []
                    },
                    "freemail": {
                        "score": 0,
                        "is_freemail": false
                    },
                    "ip": {
                        "score": 0,
                        "address": "104.31.77.225",
                        "is_quarantined": false,
                        "blacklist": []
                    },
                    "source_ip": {
                        "score": 0,
                        "address": "127.0.0.1",
                        "is_quarantined": false,
                        "blacklist": []
                    },
                    "disposable": {
                        "score": 0,
                        "is_disposable": false
                    },
                    "email": {
                        "score": 0,
                        "blacklist": []
                    },
                    "address": {
                        "score": 0,
                        "is_role": false,
                        "is_well_formed": true
                    }
                }
            },
            {
                "email": "test@mailinator.com",
                "scoring": {
                    "score": -2,
                    "smtp": {
                        "score": 1,
                        "exist_address": true,
                        "exist_mx": true,
                        "exist_catchall": false
                    },
                    "domain": {
                        "score": -1,
                        "blacklist_ns": [],
                        "ns": [
                            "betty.ns.cloudflare.com.",
                            "james.ns.cloudflare.com."
                        ],
                        "mx": [
                            "mail2.mailinator.com",
                            "mail.mailinator.com"
                        ],
                        "blacklist_mx": [],
                        "blacklist": [
                            "MARTENSON-DED",
                            "DEA",
                            "IVOLO-DED"
                        ]
                    },
                    "freemail": {
                        "score": 0,
                        "is_freemail": false
                    },
                    "ip": {
                        "score": 0,
                        "address": "104.25.198.31",
                        "is_quarantined": false,
                        "blacklist": []
                    },
                    "source_ip": {
                        "score": 0,
                        "address": "127.0.0.1",
                        "is_quarantined": false,
                        "blacklist": []
                    },
                    "disposable": {
                        "score": -1,
                        "is_disposable": true
                    },
                    "email": {
                        "score": -1,
                        "blacklist": [
                            "STOPFORUMSPAM-365",
                            "STOPFORUMSPAM-180"
                        ]
                    },
                    "address": {
                        "score": 0,
                        "is_role": false,
                        "is_well_formed": true
                    }
                }
            }
        ]
    }
    

    A developer can save time and rate-limit restrictions if she passes a list of comma separated Emails in the QueryString. She will get the scoring and full JSON structure for each Email in the response. If the Email is not well formed it will return nothing for that email, but will perform the lookup for the rest of the valid emails:

    HTTP Request

    GET https://api.apility.net/bademail_batch/<EMAIL1>,<EMAIL2>,...,<EMAILn>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept No application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    EMAIL1,EMAIL2,...,EMAILn The list of Emails to lookup in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing a list of JSON structures with the email address and the 'Email' object.

    Geo IP look up

    The Geo IP service cannot be classified as blacklists as the lists above, but are really helpful to analyze an IP and create a profile of your users. Just like blacklists they can be accessed with our simple API and they are rate limited the same way. So if you get 429 error (Too many requests) please consider upgrading to a paid plan.

    This service returns the geo location of any IP with relevant information like:

    This API request will always return a JSON structure with the information and a 200 HTTP code if the IP can be found in the database. If not, then it will return a 404 HTTP code as usual.

    Get IP geo location.

    Get the geo location data of an IP:

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/geoip/9.9.9.9"
    

    The response can be:

    {
       "ip":{
          "longitude":2.3387000000000002,
          "postal":"",
          "hostname":"dns.quad9.net",
          "as":{
             "networks":"['9.9.9.0/24', '149.112.112.0/24', '149.112.149.0/24']",
             "asn":"19281",
             "name":"QUAD9-AS-1 - Quad9",
             "country":"US"
          },
          "latitude":48.8582,
          "country":"FR",
          "region":"",
          "address":"9.9.9.9",
          "continent":"EU",
          "city":""
       }
    }
    

    This endpoint returns a JSON structure with individual details about the geographical location of the IP, and information about the Autonomous System and its networks. The request always returns the status code 200 (HTTP OK) if the IP exists. If the IP is malformed it will return a 400 (HTTP Bad Request) code.

    HTTP Request

    GET https://api.apility.net/geoip/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept Yes application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP The IP to geo locate in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    ip JSON structure containing the 'geoip' object.

    Get geo location of a set of IP (Bulk Request).

    Get the geo location data of a set of IP:

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/geoip_batch212.231.122.12,8.8.8.8,9.9.9.9"
    

    The response can be:

    {
        "geoip_batch": [
            {
                "geoip": {
                    "longitude": -3.684,
                    "country": "ES",
                    "postal": "",
                    "region": "",
                    "city": "",
                    "as": {
                        "country": "ES",
                        "asn": "15704",
                        "networks": [
                            "31.222.80.0/20",
                            "46.6.0.0/18",
                            ...
                            "213.195.96.0/19"
                        ],
                        "name": "AS15704",
                        "ip": "212.231.122.12"
                    },
                    "continent": "EU",
                    "hostname": "",
                    "address": "212.231.122.12",
                    "latitude": 40.4172
                },
                "ip": "212.231.122.12"
            },
            {
                "geoip": {
                    "longitude": -97.822,
                    "country": "US",
                    "postal": "",
                    "region": "",
                    "city": "",
                    "as": {
                        "country": "US",
                        "asn": "15169",
                        "networks": [
                            "8.8.4.0/24",
                            "8.8.8.0/24",
                            ...
                            "216.252.222.0/24"
                        ],
                        "name": "GOOGLE - Google LLC",
                        "ip": "8.8.8.8"
                    },
                    "continent": "NA",
                    "hostname": "google-public-dns-a.google.com",
                    "address": "8.8.8.8",
                    "latitude": 37.751
                },
                "ip": "8.8.8.8"
            },
            {
                "geoip": {
                    "longitude": 2.3387000000000002,
                    "country": "FR",
                    "postal": "",
                    "region": "",
                    "city": "",
                    "as": {
                        "networks": [
                            "9.9.9.0/24",
                            "149.112.112.0/24",
                            "149.112.149.0/24"
                        ],
                        "asn": "19281",
                        "country": "US",
                        "name": "QUAD9-AS-1 - Quad9",
                        "ip": "9.9.9.9"
                    },
                    "continent": "EU",
                    "hostname": "dns.quad9.net",
                    "address": "9.9.9.9",
                    "latitude": 48.8582
                },
                "ip": "9.9.9.9"
            }
        ]
    }```
    
    A developer can save time and rate-limit restrictions if she passes a list of comma separated IP in the QueryString. She will get the information inside a JSON structure for each IP in the response. If the IP is not well formed it will return nothing for that IP, but will perform the lookup for the rest of the valid IP addresses:
    
    
    
    <aside class="success">
    You always have to pass the API key. You can pass it as a header parameter or a query string parameter.
    </aside>
    
    ### HTTP Request
    
    `GET https://api.apility.net/geoip_batch/<IP1>,<IP2>,...,<IPn>`
    
    ### Header Parameters
    
    Parameter    | Mandatory | Description
    ------------ | --------- | -----------
    X-Auth-Token | No | API Key of the owner.
    Accept | No | application/json
    
    ### QueryString Parameters
    
    Parameter    | Mandatory | Description
    ------------ | --------- | -----------
    token | No | API Key of the owner.
    callback | No | Function to invoke when using JSONP model.
    
    ### URL Parameters
    
    Parameter | Description
    --------- | -----------
    IP1,IP2,...,IPn        | The list  of IP to geo locate in the system.
    
    ### Response
    
    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:
    
    Parameter | Description
    --------- | -----------
    response  | JSON structure containing a JSON structure with the IP to geo locate and its '[geoip](#geoip)' object.
    
    
    <aside class="warning">
    The maximum number of IP to geo locate per bulk request is 100. The service will return a 400 error code (Bad Request) for arrays larger than 100.
    </aside>
    
    # Autonomous System look up
    
    The Autonomous System look up services cannot be classified as __blacklists__ too, but are really helpful to deep analyze an IP and create a profile of your users. Just like blacklists they can be accessed with our simple API and they are rate limited the same way. So if you get 429 error (Too many requests) please consider upgrading to a paid plan.
    
    This service returns the Autonomous System information of an IP or ASN:
    
    * ASN
    * Country
    * Name
    * Networks
    
    This API request will always return a JSON structure with the information and a 200 HTTP code if the IP or AS number can be found in the system. If not, then it will return a 404 HTTP code as usual.
    
    
    ## Get the AS information from an IP.
    
    > Get the AS data of an IP:
    
    ```shell
    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/as/ip/9.9.9.9"
    

    The response can be:

    {
       "as":{
          "networks":"['9.9.9.0/24', '149.112.112.0/24', '149.112.149.0/24']",
          "asn":"19281",
          "name":"QUAD9-AS-1 - Quad9",
          "country":"US"
       }
    }
    

    This endpoint returns a JSON structure with details about the Autonomous System that owns the IP, and information about its networks. The request always returns the status code 200 (HTTP OK) if the IP exists. If the IP is malformed it will return a 400 (HTTP Bad Request) code.

    HTTP Request

    GET https://api.apility.net/as/ip/<IP>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept Yes application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP The IP to look up the AS in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    as JSON structure containing the ''as'' object.

    Get the AS information from a set of IP (Bulk Request).

    Get the AS data of a set of IP addresses:

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/as_batch/ip/212.231.122.12,8.8.8.8,9.9.9.9"
    

    The response can be:

    {
        "response": [
            {
                "as": {
                    "country": "ES",
                    "asn": "15704",
                    "networks": [
                        "31.222.80.0/20",
                        "46.6.0.0/18",
                        ...
                        "213.195.96.0/19"
                    ],
                    "name": "AS15704"
                },
                "ip": "212.231.122.12"
            },
            {
                "as": {
                    "country": "US",
                    "asn": "15169",
                    "networks": [
                        "8.8.4.0/24",
                        "8.8.8.0/24",
                        ...
                        "216.252.222.0/24"
                    ],
                    "name": "GOOGLE - Google LLC"
                },
                "ip": "8.8.8.8"
            },
            {
                "as": {
                    "networks": [
                        "9.9.9.0/24",
                        "149.112.112.0/24",
                        "149.112.149.0/24"
                    ],
                    "asn": "19281",
                    "country": "US",
                    "name": "QUAD9-AS-1 - Quad9"
                },
                "ip": "9.9.9.9"
            }
        ]
    }}
    

    A developer can save time and rate-limit restrictions if she passes a list of comma separated IP in the QueryString. She will get the information inside a JSON structure for each IP in the response. If the IP is not well formed it will return nothing for that IP, but will perform the lookup for the rest of the valid IP addresses:

    HTTP Request

    GET https://api.apility.net/as_batch/ip/<IP1>,<IP2>,...,<IPn>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept No application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    IP1,IP2,...,IPn The list of IP addresses to lookup the AS in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing a JSON structure with the IP adddress and its ''as'' object.

    Get the AS information from its number.

    Get the AS data from its number:

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/as/num/19281"
    

    The response can be:

    {
       "as":{
          "networks":"['9.9.9.0/24', '149.112.112.0/24', '149.112.149.0/24']",
          "asn":"19281",
          "name":"QUAD9-AS-1 - Quad9",
          "country":"US"
       }
    }
    

    This endpoint returns a JSON structure with details about the Autonomous System with the number, and information about its networks. The request always returns the status code 200 (HTTP OK) if the IP exists. If the IP is malformed it will return a 400 (HTTP Bad Request) code.

    HTTP Request

    GET https://api.apility.net/as/num/<NUMBER>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept Yes application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    NUMBER The Number of the AS to look up in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    as JSON structure containing the 'as' object.

    Get the AS information from a set of AS numbers (Bulk Request).

    Get the AS data from a set of AS numbers:

    $ curl -H "X-Auth-Token: UUID" -X GET "https://api.apility.net/as_batch/num/15704,3352,15169"
    

    The response can be:

    {
        "response": [
            {
                "asn": "15704",
                "as": {
                    "country": "ES",
                    "asn": "15704",
                    "networks": [
                        "31.222.80.0/20",
                        "46.6.0.0/18",
                        ...
                        "213.195.96.0/19"
                    ],
                    "name": "AS15704"
                }
            },
            {
                "asn": "3352",
                "as": {
                    "country": "ES",
                    "asn": "3352",
                    "networks": [
                        "2.136.0.0/16",
                        "2.137.0.0/16",
                        ...
                        "217.127.0.0/16"
                    ],
                    "name": "TELEFONICA_DE_ESPANA"
                }
            },
            {
                "asn": "15169",
                "as": {
                    "country": "US",
                    "asn": "15169",
                    "networks": [
                        "8.8.4.0/24",
                        "8.8.8.0/24",
                        ...
                        "216.252.222.0/24"
                    ],
                    "name": "GOOGLE - Google LLC"
                }
            }
        ]
    }
    

    A developer can save time and rate-limit restrictions if she passes a list of comma separated AS numbers in the QueryString. She will get the information inside a JSON structure for each AS number in the response. If the AS Number is not a correct number or the AS does not exist it will return nothing for it, but will perform the lookup for the rest of the valid AS numbers:

    HTTP Request

    GET https://api.apility.net/as_batch/num/<NUM1>,<NUM2>,...,<NUMn>

    Header Parameters

    Parameter Mandatory Description
    X-Auth-Token No API Key of the owner.
    Accept No application/json

    QueryString Parameters

    Parameter Mandatory Description
    token No API Key of the owner.
    callback No Function to invoke when using JSONP model.

    URL Parameters

    Parameter Description
    NUMBER The Number of the AS to look up in the system.

    Response

    The status code of the response is 200 (HTTP OK) if everything was ok, but it will also return the following JSON:

    Parameter Description
    response JSON structure containing a list of JSON structures with the AS number and its 'as' object.

    Objects

    domain

    The domain object contains the information used in the scoring algorithm.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positivo means it's a 'clean' domain.
    domain JSON structure containing the 'domainname score' object as result of the analysis of the domains.
    ip JSON structure containing the 'ip score' object as result of the analysis of the IP of the domain.
    source_ip JSON structure containing the 'ip score' object as result of the analysis of the IP origin of the request.

    email

    The email object contains the information used in the scoring algorithm.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positive means it's a 'clean' domain.
    domain JSON structure containing the 'domainname score' object as result of the analysis of the domains.
    ip JSON structure containing the 'ip score' object as result of the analysis of the IP of the domain.
    source_ip JSON structure containing the 'ip score' object as result of the analysis of the IP origin of the request.
    address JSON structure containing the 'address score' object as result of the analysis of the email.
    smtp JSON structure containing the 'smtp score' object as result of the analysis of the email service.
    freemail JSON structure containing the 'freemail score' object as result of the analysis of the email provider.
    email JSON structure containing the 'email-blacklist score' object as result of the look up in the email blacklists.
    disposable JSON structure containing the 'disposable score' object as result of the analysis of the email provider.

    geoip

    The geoip object contains the information used in Geolocation of an IP.

    Parameter Description
    longitude Longitude where the IP has been found
    latitude Latitude where the IP has been found
    hostname Name of the host resolved from the IP
    address IPv4 or IPv6 address of the request
    continent 2 letter code of the continent
    country ISO 3166-1 Country code
    region Name of the region
    city Name of the city
    postal Postal code or Zip code
    as JSON structure containing the 'as' object.

    as

    The AS object contains the information of Autonmous System

    Parameter Description
    asn AS number
    name name of the AS
    country ISO 3166-1 Country code
    networks Array with the lists of networks of the AS

    domainname score

    The domainname score contains the information of testing different subdomains of the main root domain: NS records, MX records and domain blacklists.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positive means it's a 'clean' domain.
    blacklist_ns Array containing the blacklists where the NS domains were found.
    blacklist_mx Array containing the blacklists where the MX domains were found.
    blacklist Array containing the blacklists where the domain was found.
    mx Array with the hosts found in the MX records.
    ns Array with the hosts found in the NS records.

    ip score

    The ip score contains the information of looking up the IP in the blacklists.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' IP. Neutral or positive means it's a 'clean' IP.
    blacklist Array containing the blacklists where the IP was found.
    is_quarantined If the IP has been added by the user to the quarantine lists.
    address IPv4 or IPv6 resolved.

    address score

    The address score contains the information of checking the format of the email.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' email. Neutral or positive means it's a 'clean' email.
    is_role The email has the format of a role-based-address. It's not common to allow registration with role-based-addresses.
    is_well_formed The email is compliant or not with the standards and could cause issues in some systems.

    smtp score

    The smtp score contains the information obtained after testing the remote inbox where the email is hosted.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' email. Neutral or positive means it's a 'clean' email.
    exist_mx The SMTP service is reachable using the hosts in the MX records.
    exist_address The SMTP service recognizes the email address.
    exist_catchall The SMTP service implements a catch-all email feature.

    freemail score

    The freemail score contains the information of looking up the domain in the lists of Free Email Service Providers.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positive means it's a 'clean' domain.
    is_freemail The domain has been found in any Free Email Service Provider list.

    disposable score

    The disposable score contains the information of looking up the domain in the lists of Disposable Email Addresses Providers.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positive means it's a 'clean' domain.
    is_disposable The domain has been found in any Disposable Email Address Providers list.

    email score

    The email score contains the information of looking up the email in the blacklists.

    Parameter Description
    score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' email. Neutral or positive means it's a 'clean' email.
    blacklist Array containing the blacklists where the email was found.

    Errors

    Apility.io uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is probably using parameters with bad format. Check the error details.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- Your API key does not have enough permissions to perform the action requested.
    404 Not Found -- If using Simple Model, then it means the resource is not in any blacklist (and this is good).
    405 Method Not Allowed -- All endpoints only allow GET verbs.
    429 Too Many Requests -- You have ran out of quota. Please consider upgrading your plan.
    500 Internal Server Error -- We had a problem with our server. Please report to our suppor team.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.