RBL Checks via the RBLTracker API

The RBLTracker API now includes the ability to perform a one-off RBL check, similar to the Manual Check feature in the RBLTracker Portal, via the API. This API feature can be used to build your own real-time RBL lookup page, or to perform one-off RBL checks as needed, rather than having them run on a timed basis.

One thing that is a little different with this feature, is that the RBL check process is performed in an asynchronous fashion, meaning that the results of the check are not returned immediately. Instead, a background RBL check process is started, and you can poll for live updates, or provide a call-back URL which will be posted to once the check completes.

The reason for the asynchronous handling, is that the RBL check process may take some time to process, depending on the number of RBLs being checked, and the current state of the RBL providers.

Starting a Manual Check

To start a Manual Check via the API, simply make an HTTP POST request to /api/check/start, passing the host you would like to check, and the API will return the ID of this check. You may also pass an optional callback URL that RBLTracker will POST the check results to once the check completes. If you do not require real-time updates from the check, passing a callback URL is an easy way to ingest the RBL check results, without having to poll on a repeated basis:

$ curl https://rbltracker.com/api/check/start.json \
    -u 'your_account_sid:your_auth_token' \
    -d host='10.10.10.11' \
    -d callback='https://your.website.com/callback.php'

The host value may be either a single IP address (RBL), a domain name or host name (URIBL), or a host ID of an existing host already configured on your RBLTracker account. The result is a JSON (or XML by specifying start.xml rather than start.json) object with the new event ID referencing this RBL check process.

{
 "status_code": 200,
 "status_message": "Check status retrieved successfully.",
 "data": {
   "status": "completed",
   "checked_count": 72,
   "listed": 1,
   "listed_count": 3
 },
 "version": "3.6"
}

Polling for Status Updates

Once you’ve started a check request, you can optionally poll the API for real-time updates for this RBL check by making an HTTP GET request to /api/check/status, passing the event ID returned by /api/check/start

$ curl -G https://rbltracker.com/api/check/status/{id}.json \
 -u 'your_account_sid:your_auth_token'

The result is a JSON object with the current check status:

{
 "status_code": 200,
 "status_message": "Check status retreived successfully.",
 "data": {
   "status": "completed",
   "checked_count": 72,
   "listed": 1,
   "listed_count": 3
 },
 "version": "3.6"
}

This data will update in real-time as the RBL check is processed in the background.

Using the Callback URL

Alternatively, you may pass a callback URL to the /api/check/start function, and RBLTracker will make a HTTP POST request to this URL, passing the check details as a JSON object, once the RBL check completes.

The JSON object will look something like this:

{
 "event_id": "4ff27529b33c83ffa8c79a7426d40daf087181baaaac75e029b6fd878a3df199",
 "host": "10.10.10.11",
 "host_id": "HT763a9f42aab587702f26b00fc9cfa194",
 "host_name": "10.10.10.11",
 "listed": 1,
 "listed_count": 3,
 "listed_details": [{
   "details": "Listed",
   "host": "bl.mailspike.net",
   "id": "RB9842d3e0e9d85ac414ec0c7aeb9c0870",
   "website": "http:\/\/mailspike.net\/"
 }, {
   "details": "See http:\/\/www.anti-spam.org.cn\/rbl_search.action?ip=10.10.10.11",
   "host": "cbl.anti-spam.org.cn",
   "id": "RB1d12095594757b2e8dbe35083d83e95e",
   "website": "http:\/\/www.anti-spam.org.cn\/CBL"
 }, {
   "details": "Spam Received: http:\/\/www.sorbs.net\/lookup.shtml?10.10.10.11",
   "host": "spam.dnsbl.sorbs.net",
   "id": "RB4eacfc2b82b15bbadb2097d75cafb66e",
   "website": "http:\/\/www.sorbs.net\/"
 }]
}

You can use this posted data to update the host details in your database or provisioning system.

The Manual Check feature is currently available directly via the API, as well as via the PHP or Node.js SDK