Using a library
The easiest way to get started with our API is to use one of our libraries (choose from PHP, Ruby, Python, .NET or others). These libraries do all of the hard work for you. Once you've downloaded a library, all you'll need is an API key to get started. Otherwise, Akismet will never learn to adapt to your application's comments.
Custom integrations
If you choose to write your own integration, there are a few things that you'll want to keep in mind:
Development API keys
Please contact Anthony, via our support form, if you'd like access to a development API key. He will be happy to get you started and work with you during your testing and implementation. Even if you are using an available library but want to test our service before committing to a subscription, he can get you up and running.
Structuring your API calls
All calls to Akismet are POST requests much like a web form would send. The request variables should be constructed like a query string, key=value and multiple variables separated by ampersands. Don't forget to URL escape the values.
When making calls to Akismet, your key is used as a subdomain. So, if you had the key 123YourAPIKey you would make all API calls to 123YourAPIKey.rest.akismet.com.
There are three different types of calls to Akismet:
Testing your API calls
Akismet works by examining all the available information combined. It is not enough to provide just the content of a message; you need to provide as many independent pieces of information as you can in each call. So before you can test Akismet’s accuracy, you need to make sure you’re sending complete and correct information.
To simulate a positive (spam) result, make a comment-check API call with the comment_author set to viagra-test-123, and all other required fields populated with typical values. The Akismet API will always return a true response to a valid request with that value. If you receive anything else, something is wrong in your client, data, or communications.
To simulate a negative (not spam) result, make a comment-check API call with the user_role set to administrator, and all other required fields populated with typical values. The Akismet API will always return a false response. Any other response indicates a data or communication problem.
Also, make sure your client will handle an unexpected response. Don’t assume that the comment-check API will always return either true or false. An invalid request may result in an error response. Additional information will usually be available in HTTP headers in this case. And of course a connectivity problem may result in no response at all. It’s important not to misinterpret an invalid response as meaning spam or ham.
For automated testing, include the parameter is_test=1 in your tests. That will tell Akismet not to change its behaviour based on those API calls – they will have no training effect. That means your tests will be somewhat repeatable, in the sense that one test won’t influence subsequent calls.
Setting your user agent
If possible, your user agent string should always use the following format:
So, for the WordPress plugin this would look like:
We're here to help
If you ever get stuck or need need help troubleshooting something, please don't hesitate to contact us.
Key verification authenticates your key before calling the comment check, submit spam or submit ham methods.
This method is called with the following URL:
This is the one call that can be made without the API key subdomain.
Required parameters
PHP Example
// Call to verify key function
akismet_verify_key('123YourAPIKey', 'http://www.yourblogdomainname.com/');
// Authenticates your Akismet API key
function akismet_verify_key( $key, $blog ) {
$blog = urlencode($blog);
$request = 'key='. $key .'&blog='. $blog;
$host = $http_host = 'rest.akismet.com';
$path = '/1.1/verify-key';
$port = 80;
$akismet_ua = "WordPress/3.8.1 | Akismet/2.5.9";
$content_length = strlen( $request );
$http_request = "POST $path HTTP/1.0\r\n";
$http_request .= "Host: $host\r\n";
$http_request .= "Content-Type: application/x-www-form-urlencoded\r\n";
$http_request .= "Content-Length: {$content_length}\r\n";
$http_request .= "User-Agent: {$akismet_ua}\r\n";
$http_request .= "\r\n";
$http_request .= $request;
$response = '';
if( false != ( $fs = @fsockopen( $http_host, $port, $errno, $errstr, 10 ) ) ) {
fwrite( $fs, $http_request );
while ( !feof( $fs ) )
$response .= fgets( $fs, 1160 ); // One TCP-IP packet
fclose( $fs );
$response = explode( "\r\n\r\n", $response, 2 );
}
if ( 'valid' == $response[1] )
return true;
else
return false;
}
Success response example
The call returns "valid" if the key is valid.
Array
(
[0] => HTTP/1.1 200 OK
Server: nginx
Date: Mon, 24 Feb 2014 16:31:55 GMT
Content-Type: text/plain; charset=utf-8
Connection: close
X-akismet-server: 192.168.6.47
Content-length: 5
[1] => valid
)
Error response example
If the verify-key call returns "invalid", it usually includes an extra HTTP header with some debug information about what exactly was invalid about the call.
Array
(
[0] => HTTP/1.1 200 OK
Server: nginx
Date: Mon, 24 Feb 2014 16:34:54 GMT
Content-Type: text/plain; charset=utf-8
Connection: close
X-akismet-server: 192.168.6.48
X-akismet-debug-help: We were unable to parse your blog URI
Content-length: 7
[1] => invalid
)
We're here to help
If you ever get stuck or need need help troubleshooting something, please don't hesitate to contact us.
This call is for submitting comments that weren't marked as spam but should have been.
It is very important that the values you submit with this call match those of your comment-check calls as closely as possible. In order to learn from its mistakes, Akismet needs to match your missed spam and false positive reports to the original comment-check API calls made when the content was first posted. While it is normal for less information to be available for submit-spam and submit-ham calls (most comment systems and forums will not store all metadata), you should ensure that the values that you do send match those of the original content.
This method is called with the following URL:
Parameters
This call takes the same arguments as the comment check call.
Other server enviroment variables
In PHP there is an array of enviroment variables called $_SERVER which contains information about the web server itself as well as a key/value for every HTTP header sent with the request. This data is highly useful to Akismet. How the submited content interacts with the server can be very telling, so please include as much of it as possible.
PHP Example
// Call to comment check
$data = array('blog' => 'http://yourblogdomainname.com',
'user_ip' => '127.0.0.1',
'user_agent' => 'Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.2) Gecko/20100115 Firefox/3.6',
'referrer' => 'http://www.google.com',
'permalink' => 'http://yourblogdomainname.com/blog/post=1',
'comment_type' => 'comment',
'comment_author' => 'admin',
'comment_author_email' => 'test@test.com',
'comment_author_url' => 'http://www.CheckOutMyCoolSite.com',
'comment_content' => 'It means a lot that you would take the time to review our software. Thanks again.');
akismet_submit_spam( '123YourAPIKey', $data );
// Passes back true (it's spam) or false (it's ham)
function akismet_submit_spam( $key, $data ) {
$request = 'blog='. urlencode($data['blog']) .
'&user_ip='. urlencode($data['user_ip']) .
'&user_agent='. urlencode($data['user_agent']) .
'&referrer='. urlencode($data['referrer']) .
'&permalink='. urlencode($data['permalink']) .
'&comment_type='. urlencode($data['comment_type']) .
'&comment_author='. urlencode($data['comment_author']) .
'&comment_author_email='. urlencode($data['comment_author_email']) .
'&comment_author_url='. urlencode($data['comment_author_url']) .
'&comment_content='. urlencode($data['comment_content']);
$host = $http_host = $key.'.rest.akismet.com';
$path = '/1.1/submit-spam';
$port = 80;
$akismet_ua = "WordPress/3.8.1 | Akismet/2.5.9";
$content_length = strlen( $request );
$http_request = "POST $path HTTP/1.0\r\n";
$http_request .= "Host: $host\r\n";
$http_request .= "Content-Type: application/x-www-form-urlencoded\r\n";
$http_request .= "Content-Length: {$content_length}\r\n";
$http_request .= "User-Agent: {$akismet_ua}\r\n";
$http_request .= "\r\n";
$http_request .= $request;
$response = '';
if( false != ( $fs = @fsockopen( $http_host, $port, $errno, $errstr, 10 ) ) ) {
fwrite( $fs, $http_request );
while ( !feof( $fs ) )
$response .= fgets( $fs, 1160 ); // One TCP-IP packet
fclose( $fs );
$response = explode( "\r\n\r\n", $response, 2 );
}
if ( 'Thanks for making the web a better place.' == $response[1] )
return true;
else
return false;
}
This call returns a single response:
Array
(
[0] => HTTP/1.1 200 OK
Server: nginx
Date: Mon, 24 Feb 2014 20:41:15 GMT
Content-Type: text/html; charset=utf-8
Connection: close
Content-length: 41
[1] => Thanks for making the web a better place.
)
We're here to help
If you ever get stuck or need need help troubleshooting something, please don't hesitate to contact us.
This call is intended for the submission of false positives - items that were incorrectly classified as spam by Akismet. It takes identical arguments as comment check and submit spam.
Remember that, as explained in our submit-spam documentation, you should ensure that any values you're passing here match up with the original and corresponding comment-check call.
This method is called with the following URL:
Parameters
Other server enviroment variables
In PHP there is an array of enviroment variables called $_SERVER which contains information about the web server itself as well as a key/value for every HTTP header sent with the request. This data is highly useful to Akismet. How the submited content interacts with the server can be very telling, so please include as much of it as possible.
PHP Example
// Call to comment check
$data = array('blog' => 'http://yourblogdomainname.com',
'user_ip' => '127.0.0.1',
'user_agent' => 'Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.2) Gecko/20100115 Firefox/3.6',
'referrer' => 'http://www.google.com',
'permalink' => 'http://yourblogdomainname.com/blog/post=1',
'comment_type' => 'comment',
'comment_author' => 'admin',
'comment_author_email' => 'test@test.com',
'comment_author_url' => 'http://www.CheckOutMyCoolSite.com',
'comment_content' => 'It means a lot that you would take the time to review our software. Thanks again.');
akismet_submit_ham( '123YourAPIKey', $data );
// Passes back true (it's spam) or false (it's ham)
function akismet_submit_ham( $key, $data ) {
$request = 'blog='. urlencode($data['blog']) .
'&user_ip='. urlencode($data['user_ip']) .
'&user_agent='. urlencode($data['user_agent']) .
'&referrer='. urlencode($data['referrer']) .
'&permalink='. urlencode($data['permalink']) .
'&comment_type='. urlencode($data['comment_type']) .
'&comment_author='. urlencode($data['comment_author']) .
'&comment_author_email='. urlencode($data['comment_author_email']) .
'&comment_author_url='. urlencode($data['comment_author_url']) .
'&comment_content='. urlencode($data['comment_content']);
$host = $http_host = $key.'.rest.akismet.com';
$path = '/1.1/submit-ham';
$port = 80;
$akismet_ua = "WordPress/3.8.1 | Akismet/2.5.9";
$content_length = strlen( $request );
$http_request = "POST $path HTTP/1.0\r\n";
$http_request .= "Host: $host\r\n";
$http_request .= "Content-Type: application/x-www-form-urlencoded\r\n";
$http_request .= "Content-Length: {$content_length}\r\n";
$http_request .= "User-Agent: {$akismet_ua}\r\n";
$http_request .= "\r\n";
$http_request .= $request;
$response = '';
if( false != ( $fs = @fsockopen( $http_host, $port, $errno, $errstr, 10 ) ) ) {
fwrite( $fs, $http_request );
while ( !feof( $fs ) )
$response .= fgets( $fs, 1160 ); // One TCP-IP packet
fclose( $fs );
$response = explode( "\r\n\r\n", $response, 2 );
}
if ( 'Thanks for making the web a better place.' == $response[1] )
return true;
else
return false;
}
This call returns a single response:
Array
(
[0] => HTTP/1.1 200 OK
Server: nginx
Date: Mon, 24 Feb 2014 20:41:15 GMT
Content-Type: text/html; charset=utf-8
Connection: close
Content-length: 41
[1] => Thanks for making the web a better place.
)
We're here to help
If you ever get stuck or need need help troubleshooting something, please don't hesitate to contact us.
3. Comment check
This is the call you will make the most. It takes a number of arguments and characteristics about the submitted content and then returns a thumbs up or thumbs down. Performance can drop dramatically if you choose to exclude elements. The more genuine data you send, the greater the accuracy. We recommend erring on the side of too much data, as every bit of data is used as part of the Akismet signature.
This method is called with the following URL:
Parameters
The front page or home URL of the instance making the request. For a blog or wiki this would be the front page. Note: Must be a full URI, including http://.
IP address of the comment submitter.
User agent string of the web browser submitting the comment - typically the HTTP_USER_AGENT cgi variable. Not to be confused with the user agent of your Akismet library.
The content of the HTTP_REFERER header should be sent here.
The permanent location of the entry the comment was submitted to.
May be blank, comment, trackback, pingback, or a made up value like "registration". It's important to send an appropriate value, and this is further explained here.
Name submitted with the comment
Email address submitted with the comment
URL submitted with comment
The content that was submitted.
The UTC timestamp of the creation of the comment, in ISO 8601 format. May be omitted if the comment is sent to the API at the time it is created.
The UTC timestamp of the publication time for the post, page or thread on which the comment was posted.
Indicates the language(s) in use on the blog or site, in ISO 639-1 format, comma-separated. A site with articles in English and French might use "en, fr_ca".
The character encoding for the form values included in comment_* parameters, such as "UTF-8" or "ISO-8859-1".
Other server enviroment variables
In PHP there is an array of enviroment variables called $_SERVER which contains information about the web server itself as well as a key/value for every HTTP header sent with the request. This data is highly useful to Akismet. How the submited content interacts with the server can be very telling, so please include as much of it as possible.
PHP Example
// Call to comment check $data = array('blog' => 'http://yourblogdomainname.com', 'user_ip' => '127.0.0.1', 'user_agent' => 'Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.2) Gecko/20100115 Firefox/3.6', 'referrer' => 'http://www.google.com', 'permalink' => 'http://yourblogdomainname.com/blog/post=1', 'comment_type' => 'comment', 'comment_author' => 'admin', 'comment_author_email' => 'test@test.com', 'comment_author_url' => 'http://www.CheckOutMyCoolSite.com', 'comment_content' => 'It means a lot that you would take the time to review our software. Thanks again.'); akismet_comment_check( '123YourAPIKey', $data ); // Passes back true (it's spam) or false (it's ham) function akismet_comment_check( $key, $data ) { $request = 'blog='. urlencode($data['blog']) . '&user_ip='. urlencode($data['user_ip']) . '&user_agent='. urlencode($data['user_agent']) . '&referrer='. urlencode($data['referrer']) . '&permalink='. urlencode($data['permalink']) . '&comment_type='. urlencode($data['comment_type']) . '&comment_author='. urlencode($data['comment_author']) . '&comment_author_email='. urlencode($data['comment_author_email']) . '&comment_author_url='. urlencode($data['comment_author_url']) . '&comment_content='. urlencode($data['comment_content']); $host = $http_host = $key.'.rest.akismet.com'; $path = '/1.1/comment-check'; $port = 80; $akismet_ua = "WordPress/3.8.1 | Akismet/2.5.9"; $content_length = strlen( $request ); $http_request = "POST $path HTTP/1.0\r\n"; $http_request .= "Host: $host\r\n"; $http_request .= "Content-Type: application/x-www-form-urlencoded\r\n"; $http_request .= "Content-Length: {$content_length}\r\n"; $http_request .= "User-Agent: {$akismet_ua}\r\n"; $http_request .= "\r\n"; $http_request .= $request; $response = ''; if( false != ( $fs = @fsockopen( $http_host, $port, $errno, $errstr, 10 ) ) ) { fwrite( $fs, $http_request ); while ( !feof( $fs ) ) $response .= fgets( $fs, 1160 ); // One TCP-IP packet fclose( $fs ); $response = explode( "\r\n\r\n", $response, 2 ); } if ( 'true' == $response[1] ) return true; else return false; }This call returns either "true" (if this is spam) or "false" if it's not.
Spam response example
The call returns "true" if the comment is spam. If you are having trouble triggering a spam response you can send "viagra-test-123" as the author and it will trigger a true response, always.
Array ( [0] => HTTP/1.1 200 OK Server: nginx Date: Mon, 24 Feb 2014 20:17:08 GMT Content-Type: text/plain; charset=utf-8 Connection: close X-akismet-server: 192.168.7.7 Content-length: 4 [1] => true )Ham response example
The call returns "false" if the comment is ham.
Array ( [0] => HTTP/1.1 200 OK Server: nginx Date: Mon, 24 Feb 2014 20:17:08 GMT Content-Type: text/plain; charset=utf-8 Connection: close X-akismet-server: 192.168.7.7 Content-length: 4 [1] => false )Error response example
If the call returns neither "true" nor "false" an error message will be returned
Array ( [0] => HTTP/1.1 200 OK Server: nginx Date: Mon, 24 Feb 2014 16:34:54 GMT Content-Type: text/plain; charset=utf-8 Connection: close X-akismet-server: 192.168.6.48 X-akismet-debug-help: We were unable to parse your blog URI Content-length: 7 [1] => invalid )Testing your data
It is important to test Akismet with a significant amount real, live data in order to draw any conclusions on accuracy. Akismet works by comparing content to genuine spam activity happening right now (and this is based on more than just the content itself), so artificially generating spam comments is not a viable approach.
We're here to help
If you ever get stuck or need need help troubleshooting something, please don't hesitate to contact us.