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:

https://rest.akismet.com/1.1/comment-check

Important: All parameters should be sent via the POST method, form-encoded (Content-Type: application/x-www-form-urlencoded).

Parameters

api_key (required)
Your Akismet API key. You can find this on your account dashboard at https://akismet.com/account/

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:// or https://.

user_ip (required)
IP address of the comment submitter.

user_agent
User agent string of the web browser submitting the comment – typically the HTTP_USER_AGENT 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.

comment_author
Name submitted with the comment.

comment_author_email
Email address submitted with the comment.

comment_author_url
URL submitted with comment. Only send a URL that was manually entered by the user, not an automatically generated URL like the user’s profile URL on your site.

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 for comment-check requests 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, comma-separated. You may send ISO 639-1 language codes such as en or fr, or locale identifiers such as en_US, en-US, or fr_CA. Akismet normalizes locale identifiers to their primary language.

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.

honeypot_field_name
If you use a honeypot field in your implementation, include the name of the field in your request as well as the value of that field. For example, if you have a honeypot field that looks like <input type=”text” name=”hidden_honeypot_field” style=”display: none;” />, then you should include two extra parameters in your request: honeypot_field_name=hidden_honeypot_field and hidden_honeypot_field=[the value of the input].

comment_context
The comment_context parameter provides context for the environment in which the comment was posted: a list of tags or categories applied to the parent blog post or the site on which the comment was posted.

Specify comment_context using PHP-style array parameter notation: comment_context[]=cooking&comment_context[]=recipes&comment_context[]=bbq Note that any tags or categories should be taken from the parent post or environment; they should not be supplied by the commenters themselves.

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.

Example request

curl

Each -d adds a form field to the POST body. Use --data-urlencode for free-text values with spaces or punctuation so curl encodes them for you. The -i flag prints the response headers so you can see any Akismet headers.

curl -i https://rest.akismet.com/1.1/comment-check \
  -d api_key=YOUR_API_KEY \
  -d blog=https://example.com \
  -d user_ip=203.0.113.42 \
  -d referrer=https://www.google.com/ \
  -d permalink=https://example.com/blog/hello-world/ \
  -d comment_type=comment \
  -d comment_author_email=wapuu@example.com \
  -d blog_lang=en \
  -d is_test=true \
  --data-urlencode "user_agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5)" \
  --data-urlencode "comment_author=Wapuu" \
  --data-urlencode "comment_content=Thanks for the write-up, this fixed my problem."

PHP SDK

For PHP applications outside WordPress, use the official Akismet PHP SDK (PHP 8.1+). It encodes the request, turns the response headers into methods on the result, and throws an exception (all implementing AkismetException) instead of returning an error body. WordPress sites should use the Akismet plugin instead.

composer require automattic/akismet-sdk guzzlehttp/guzzle

<?php
use Automattic\Akismet\Akismet;
use Automattic\Akismet\DTO\Content;
use Automattic\Akismet\Enum\ContentType;

$akismet = Akismet::create(
    apiKey: 'YOUR_API_KEY',
    site: 'https://example.com'
);

try {
    $content = new Content(
        userIp: $_SERVER['REMOTE_ADDR'],
        userAgent: $_SERVER['HTTP_USER_AGENT'] ?? null,
        referrer: $_SERVER['HTTP_REFERER'] ?? null,
        permalink: 'https://example.com/blog/hello-world/',
        type: ContentType::Comment,
        authorName: $_POST['author'] ?? null,
        authorEmail: $_POST['email'] ?? null,
        body: $_POST['comment'] ?? null,
        blogLang: 'en',
    );

    $result = $akismet->check($content);
    if ($result->shouldDiscard()) {
        // Blatant spam (X-akismet-pro-tip: discard) - safe to drop without storing.
    } elseif ($result->isSpam()) {
        // Spam - hold in your spam queue for review.
    } elseif ($result->shouldRecheck()) {
        // X-akismet-recheck-after: check again in $result->recheckAfter seconds
        // with the same Content plus recheckReason: 'recheck'.
    }
} catch (AkismetException $e) {
    // No verdict. Fail open and check it again later.
}

ContentType covers the standard comment_type values. For a custom type, pass a plain string instead, for example type: 'product-review'. The SDK sends it unchanged.

Responses

The response body is plain text: true if the content is spam, false if it isn’t, or something else if there was a problem with the request. Akismet may also send headers that tell you what to do next.

Response headers

Spam

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-akismet-pro-tip: discard

true

The X-akismet-pro-tip header is only present when Akismet is confident the content can be discarded; many spam responses won’t include it.

Not spam

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-akismet-recheck-after: 900

false

In this example, the client should resend the same request in 900 seconds (15 minutes) with recheck_reason=recheck. Most responses won’t include this header.

Error

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-akismet-debug-help: We were unable to parse your blog URI

invalid

Errors still return HTTP 200, so check the body rather than the status code. Treat anything other than true or false as an error.

Testing your data

To check your integration handles each response:

• Spam: send akismet-guaranteed-spam as comment_author, or akismet-guaranteed-spam@example.com as comment_author_email. Either always returns true.
• Not spam: set user_role=administrator and is_test=true. This always returns false.

To judge accuracy, test Akismet with a significant amount of real, live data. 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.