akismet

A Ruby client for the Akismet API.

Getting Started

Installation

gem install akismet

Documentation

This README provides an overview of akismet. Full documentation is available at rubydoc.info.

API Key

Sign up at akismet.com and retrieve your API key from your account page.

Usage

Basics

Set your API key and app URL (a URL representing your app):

Akismet.api_key = '<your API key>'
Akismet.app_url = 'http://example.com'

Then check whether a comment is spam ...

# request is a Rack::Request
is_spam = Akismet.spam?(request.ip, request.user_agent, text: 'Poppycock!')

... file a spam report ...

Akismet.spam request.ip, request.user_agent, text: 'I earn $2,000 a week ...'

... or flag a false positive ("ham" is not-spam):

Akismet.ham request.ip, request.user_agent, text: '"Viagra" derives from the Sanskrit ...'

Accuracy

To maximize the accuracy of the filter, submit as many of the documented parameters as possible. Also submit environment variables related to the comment as a hash in the env parameter (Akismet suggests these variables):

vars = %w{
  HTTP_ACCEPT
  HTTP_ACCEPT_ENCODING
  # ...
}

params = {
  type: 'comment',
  text: 'A new life awaits you in the Off-World colonies.',
  created_at: DateTime.now,
  author: 'Eldon',
  author_email: 'eldont@aol.com',
  author_url: 'http://geocities.com/eldont',
  post_url: 'http://example.com/posts/1',
  post_modified_at: DateTime.new(2015, 1, 1),
  referrer: request.referrer,
  env: request.env.slice(*vars) # slice courtesy of Active Support
}

is_spam = Akismet.spam?(request.ip, request.user_agent, params)

Blatant Spam

Akismet flags blatant spam that should be deleted without review. This feature is exposed via Akismet.check:

is_spam, is_blatant = Akismet.check(request.ip, request.user_agent, text: 'Buy everything ... now!')

Reusing Connections

Akismet.spam? and friends create a new TCP connection each time you call them. If you have many comments to check or report, use Akismet.open to reuse a single connection:

Akismet.open do |client|
  for comment in comments
    is_spam = client.spam?(comment.ip, comment.user_agent, text: comment.text)
  end
end

Akismet::Client

In the example above, the object yielded to the block is an Akismet::Client. Akismet::Client underlies the Akismet class methods. Use it on its own to manually open and close connections or override the global API key:

begin
  client = Akismet::Client.new('api-key-2', 'http://example2.com')
  client.open
  client.spam request.ip, request.user_agent, text: 'Bank error in your favor!'
ensure
  client.close
end

Tests

1. Set the environment variable AKISMET_API_KEY to your API key
2. rake

Contributing

Please submit issues and pull requests to jonahb/akismet on GitHub.