Building your application

If you choose to write your own integration, there are a few things that you’ll want to keep in mind:

  1. 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.
  2. The more data you send with each comment check, the better chance Akismet has of avoiding missed spam and false positives.

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.

Types of API calls

There are three different types of calls to Akismet:

  1. 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.
  2. Comment check is used to ask Akismet whether or not a given post, comment, profile, etc. is spam.
  3. 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 akismet-guaranteed-spam 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