Postmark

← Back to home

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
  • CFML wrapper by Seb Duggan
  • CodeIgniter library by Oli Wood
  • Ruby by Krasimir Angelov
  • C# by Scott 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 http://spamcheck.postmarkapp.com/filter. An example call from the command line may look like this:

    curl -X POST "http://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': , // 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.
    }

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