Getting Started
1. Get a Developer Key
You first need to sign up for a Developer Key. This will give you access to our API and will allow us to monitor its results to make sure things are running as smoothly as possible.
If you are not creating a custom integration, do not register a Developer Key, as Akismet will not function as expected.
Get a Developer Key
2. Select Integration Type
Plugins & Libraries
WordPress
Content Management Systems
Forums
E-Commerce
Other
Libraries
Building your Application
- To interact properly with the Akismet API, your application should have a way for users to submit missed spam and false positives, in addition to making comment checks.
- The more data you send with each comment check, the better chance Akismet has of avoiding missed spam and false positives.
Development API keys
If you’d like access to a development API key, please join our developer program. Even if you are using an available library but want to test our service before committing to a subscription, we 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 encode 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 https://123YourAPIKey.rest.akismet.com.
There are three different types of calls to Akismet:
- Key verification will verify whether or not a valid API key is being used. This is especially useful if you will have multiple users with their own Akismet subscriptions using your application.
- Comment check is used to ask Akismet whether or not a given post, comment, profile, etc. is spam.
- Submit Spam and Submit Ham are follow-ups to let Akismet know when it got something wrong (missed spam and false positives). These are very important, and you shouldn’t develop using the Akismet API without a facility to include reporting missed spam and false positives.
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 or comment_author_email set to akismet-guaranteed-spam@example.com. Populate all other required fields with typical values. The Akismet API will always return a true response to a valid request with one of those values. 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. 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:
Application Name/Version | Plugin Name/Version
The Akismet WordPress plugin’s user agent string would look like:
WordPress/4.4.1 | Akismet/3.1.7
Key verification
Key verification authenticates your key before calling the comment-check, submit-spam, or submit-ham methods for the first time. This is the first call that you should make to Akismet and is especially useful if you will have multiple users with their own Akismet subscriptions using your application.
Note that you do not need to call this method before every call to comment-check, submit-spam, or submit-ham; you should only make this request to confirm that an API key is valid before storing it locally.
This method is called via a POST request to the following URL:
https://rest.akismet.com/1.1/verify-key
This is the one call that can be made without the API key subdomain. The API key should be included as the key POST parameter.
Required parameters
key (required)The
API key being verified for use with our
API endpoint.
blog (required)
The front page or home URL of the instance making the request. For a blog, site, or wiki this would be the front page. Note: Must be a full URI, including http://.
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 = 443;
$akismet_ua = "WordPress/4.4.1 | Akismet/3.1.7";
$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( 'ssl://' . $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
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-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 help troubleshooting something, please don’t hesitate to contact us.
Submit spam (missed spam)
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:
https://your-api-key.rest.akismet.com/1.1/submit-spam
This call takes the same arguments as the comment check call.
Parameters
blog (required)
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://.
user_ip (required)
IP address of the comment submitter.
user_agent (required)
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.
referrer (note spelling)
The content of the HTTP_REFERER header should be sent here.
permalink
The full permanent URL of the entry the comment was submitted to.
comment_type
A string that describes the type of content being sent. Examples:
comment: A blog comment.forum-post: A top-level forum post.reply: A reply to a top-level forum post.blog-post: A blog post.contact-form: A contact form or feedback form submission.signup: A new user account.message: A message sent between just a few users.
You may send a value not listed above if none of them accurately describe your content. This is further explained
here.
comment_author
Name submitted with the comment.
comment_author_email
Email address submitted with the comment.
comment_author_url
URL submitted with comment.
comment_content
The content that was submitted.
comment_date_gmt
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.
comment_post_modified_gmt
The UTC timestamp of the publication time for the post, page or thread on which the comment was posted.
blog_lang
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”.
blog_charset
The character encoding for the form values included in comment_* parameters, such as “UTF-8” or “ISO-8859-1”.
user_role
The user role of the user who submitted the comment. This is an optional parameter. If you set it to “administrator”, Akismet will always return false.
is_test
This is an optional parameter. You can use it when submitting test queries to Akismet.
recheck_reason
If you are sending content to Akismet to be rechecked, such as a post that has been edited or old pending comments that you'd like to recheck, include the parameter recheck_reason with a string describing why the content is being rechecked. For example, recheck_reason=edit.
Other server environmental variables
In PHP, there is an array of environmental variables called $_SERVER that 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 submitted 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 = 443;
$akismet_ua = "WordPress/4.4.1 | Akismet/3.1.7";
$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( 'ssl://' . $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 help troubleshooting something, please don’t hesitate to contact us.
Submit ham (false positives)
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:
https://your-api-key.rest.akismet.com/1.1/submit-ham
This call takes the same arguments as the comment check call.
Parameters
blog (required)
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://.
user_ip (required)
IP address of the comment submitter.
user_agent (required)
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.
referrer (note spelling)
The content of the HTTP_REFERER header should be sent here.
permalink
The full permanent URL of the entry the comment was submitted to.
comment_type
A string that describes the type of content being sent. Examples:
comment: A blog comment.forum-post: A top-level forum post.reply: A reply to a top-level forum post.blog-post: A blog post.contact-form: A contact form or feedback form submission.signup: A new user account.message: A message sent between just a few users.
You may send a value not listed above if none of them accurately describe your content. This is further explained
here.
comment_author
Name submitted with the comment.
comment_author_email
Email address submitted with the comment.
comment_author_url
URL submitted with comment.
comment_content
The content that was submitted.
comment_date_gmt
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.
comment_post_modified_gmt
The UTC timestamp of the publication time for the post, page or thread on which the comment was posted.
blog_lang
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”.
blog_charset
The character encoding for the form values included in comment_* parameters, such as “UTF-8” or “ISO-8859-1”.
user_role
The user role of the user who submitted the comment. This is an optional parameter. If you set it to “administrator”, Akismet will always return false.
is_test
This is an optional parameter. You can use it when submitting test queries to Akismet.
recheck_reason
If you are sending content to Akismet to be rechecked, such as a post that has been edited or old pending comments that you'd like to recheck, include the parameter recheck_reason with a string describing why the content is being rechecked. For example, recheck_reason=edit.
Other server environmental variables
In PHP, there is an array of environmental variables called $_SERVER that 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 submitted 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 = 443;
$akismet_ua = "WordPress/4.4.1 | Akismet/3.1.7";
$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( 'ssl://' . $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 help troubleshooting something, please don’t hesitate to contact us.
Response Error Codes
An API response may include an error code in the X-akismet-alert-code header. It is always accompanied by a X-akismet-alert-msg header containing a message describing the error that can be shown to the end user, but the list below includes all of the currently active error codes for reference.
10001: Your site is using an expired Yahoo! Small Business API key.10003: You must upgrade your Personal subscription to continue using Akismet.10005: Your Akismet API key may be in use by someone else.10006: Your subscription has been suspended due to improper use.10007: Your Akismet API key is being used on more sites than is allowed.10008: Your Akismet API key is being used on more sites than is allowed.10009: Your subscription has been suspended due to overuse.10010: Your subscription has been suspended due to inappropriate use.10011: Your subscription needs to be upgraded due to high usage.10402: Your API key was suspended for non-payment.10403: The owner of your API key has revoked your site's access to the key.10404: Your site was not found in the list of sites allowed to use the API key you used.30001: Your Personal subscription needs to be upgraded based on your usage.
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 data points. The more data you send Akismet about each comment, the greater the accuracy. We recommend erring on the side of including too much data.
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 full permanent URL of the entry the comment was submitted to.
A string that describes the type of content being sent. Examples:
You may send a value not listed above if none of them accurately describe your content. This is further explained here.comment: A blog comment.forum-post: A top-level forum post.reply: A reply to a top-level forum post.blog-post: A blog post.contact-form: A contact form or feedback form submission.signup: A new user account.message: A message sent between just a few users.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”.
The user role of the user who submitted the comment. This is an optional parameter. If you set it to “administrator”, Akismet will always return false.
This is an optional parameter. You can use it when submitting test queries to Akismet.
If you are sending content to Akismet to be rechecked, such as a post that has been edited or old pending comments that you'd like to recheck, include the parameter recheck_reason with a string describing why the content is being rechecked. For example, recheck_reason=edit.
Other server environmental variables
In PHP, there is an array of environmental variables called $_SERVER that 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 submitted 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 = 443; $akismet_ua = "WordPress/4.4.1 | Akismet/3.1.7"; $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( 'ssl://' . $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 or “akismet-guaranteed-spam@example.com” as the author email. Either value will always trigger a “true” response.
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 Content-length: 4 [1] => true )A spam response may also include the X-akismet-pro-tip header, like so:
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-pro-tip: discard Content-length: 4 [1] => true )If the X-akismet-pro-tip header is set to discard, then Akismet has determined that the comment is blatant spam, and you can safely discard it without saving it in any spam queue. Read more about this feature in this Akismet blog post.
Ham response example
The call returns “false” if the comment is ham. If you are having trouble triggering a ham response, you can set “user_role” to “administrator” and set the “is_test” parameter to “true”, and it will always trigger a “false” response.
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 Content-length: 4 [1] => false )Error response example
If the call returns neither true nor false, the X-akismet-debug-help header will provide context for any error that has occurred. Note that the X-akismet-debug-help header will not always be sent if a response does not return false or true.
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-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 of 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 help troubleshooting something, please don’t hesitate to contact us.