API Documentation

Postmark’s spam API is a RESTfull interface to the Spam filter tool SpamAssassin.

This can be used to pre or post process email content when it is used in your application. For instance, if you process incoming emails from your users you can first run it through the API to filter out junk and avoid clutter in your database and application. Keep in mind: This is free to use and may be updated, removed or changed at any time.

For a detailed explanation of the report generated, as well as the test definitions, please visit the SpamAssassin test repository.

Pre-built Libraries

• Perl WWW by Ido Perlmuter
• CFML wrapper by Randy Merrill
• Ruby by Brad Pauly
• Ruby by Krasimir Angelov
• Python by Tesorio.
• C# by Sasha Moak
• Kohana PHP by Luke Lanchester.
• riverline-spamassassin by Romain Cambien.

Usage

As with Postmark, the interface is a simple matter of sending a POST request to the API endpoint, currently located at https://spamcheck.postmarkapp.com/filter. An example call from the command line may look like this:

curl -X POST "https://spamcheck.postmarkapp.com/filter"
-H "Accept: application/json"
-H "Content-Type: application/json"
-v
-d '{"email":"raw dump of email", "options":"short"}'

The syntax is similar to the existing Postmark API and JSON parameters. The latter are as follows:

{
  'email': ,   // The raw dump of the email to be filtered, including all headers.
  'options': , // Default "long". Must either be "long" for a full report of processing rules, or "short" for a score request.
}

In the event of an error, the following output will be returned:

{
  'success':false,  // Failure on the spamassassin processing side will be present in the report and will not affect this value.
  'message':string, // If success is False, this will contain the error message. Note that this is an application error, and not a web server error. Web server errors are the default standard HTTP messages.
}

In the event of success, a structured subset of this will be returned:

{
  'success':true,
  'report':, // Only present if options=long. This will contain a detailed SpamAssassin report.
  'score':,  // This will contain the SpamAssassin score.
  'rules':,  // Array of objects that list the matched SpamAssassin rules.
}

You may send any number of these API calls in sequence, but be aware that each takes several seconds to process by SpamAssassin.