Using Akismet on contact forms

Akismet was originally built to filter spam out of blog comments, but it can do the same for contact forms. If you’re building a contact form that you want to integrate with Akismet, follow the directions below.

First, read the documentation for the comment-check API endpoint, and then apply the following parameter modifications for your implementation:

permalink: Use the URL of the contact form.

comment_type: Use contact_form

comment_author: If your contact form has a field that is the full name of the person filling out the form, use that here.

comment_author_email: If your contact form has a single field for the user’s email address, use that here.

comment_author_url: If your form has a single field for the user to enter their URL, use that here.

For every other field in your form that is free text typed by the user, send each as its own parameter formatted like contact_form_field_fieldname, where fieldname is a normalized version of the field label. For example, if you have a field named “Phone Number” for which the user enters 1234567, then send contact_form_field_phone_number=1234567. A field named “Where did you hear about us?” would be named contact_form_field_where_did_you_hear_about_us.

If one of the parameters doesn’t apply to your form, omit it entirely rather than sending a blank value. For example, if there is no email field, don’t send the parameter comment_author_email at all.

Important: Do not include any content in your request that was not freely typed by the user. For example, selections from dropdowns and the labels of checked checkboxes should be omitted from the Akismet request.

Missed Spam and False Positives

It’s important that your contact form support sending reports to Akismet of missed spam and false positives. Your implementation should save the request that was originally sent to the comment-check endpoint so that it can be reused for this purpose.

When a submission is marked as spam, re-send the original comment-check request, but send it to the submit-spam endpoint.

When a submission is marked as a false positive, re-send the original comment-check request, but send it to the submit-ham endpoint.

Before You Launch

Before you release your contact form’s Akismet integration, walk through the follow checklist:

☐ My contact form allows the user to specify their Akismet API key (if the key is not pre-defined).

☐ My contact form verifies that a user-supplied API key is valid when it’s entered, and only then.

☐ My contact form includes the recommended metadata in Akismet requests like IP address, user agent, referrer, and permalink.

☐ My contact form includes all fields where the user typed a value, sent as contact_form_field_[fieldname]

☐ My contact form does not send fields to Akismet that do not contain a user-typed value.

☐ My contact form supports marking submissions as missed spam.

☐ My contact form supports marking submissions as false positives.

If all of these apply, congratulations! Your integration is ready to launch.