Pre-flight for HTML email.

Premailer API Beta

Premailer is now available via an API, so you can tie it in to your own apps.

This is a preview release and may change over the next little while. All feedback is most welcome and can be sent to 'code' at

We're still working out the best model for this API going forward. Ideally we'd like to run it by donation. In the longterm, if ever we decide to discontinue the service we will give 30 days notice and post the complete source code for the web interface at that time. Hopefully that makes your future planning a little easier.

Marcus Bointon kindly put together a PHP wrapper class for the Premailer API to get things started.

Sending a request

The Premailer API is accessed via an HTTP POST to

One of either the url or html fields must be provided. All other fields are optional.

Request fields
Field Data type Description Values
url string URL of the source file
html string Raw HTML source
base_url string Base URL for converting relative links
line_length int Length of lines in the plain text version Default is 65
link_query_string string Query string appended to links
preserve_styles boolean Whether to preserve any link rel=stylesheet and style elements true (default)
remove_ids string Remove IDs from the HTML document? true
false (default)
remove_classes string Remove classes from the HTML document? true
false (default)
remove_comments string Remove comments from the HTML document? true
false (default)

Receiving the response

Premailer serves the response as JSON data with the application/json mime type encoded as UTF-8.

The result will have a status code of 201, 400, 403 or 500.

The response includes links to the generated HTML and plain text files. The URL of the resulting HTML file is also set in the Location: header. These links are valid for two hours (specified in the Expires header).

Response fields
Field Data type Description Values
status int Response code 201 on success
400 on missing source file
500 on error
message string Response message
version string The API version 0.1
documents object/hash
documents['html'] string URL to processed HTML results
documents['txt'] string URL to processed plain-text results
options object/hash Echoed configuration options used by Premailer for this request

Example of a Premailer JSON response

HTTP/1.1 201 Created
Content-Type: application/json;charset=utf-8
Cache-Control: private, max-age=7200
Expires: Wed, 07 Sep 2011 23:15:04 GMT

      "version": "0.1",
      "status": 201,
      "message": "Created",
      "options": {
          "adapter": "hpricot",
          "line_length": 60,
          "preserve_styles": true,
          "remove_ids": true,
          "remove_classes": false,
          "remove_comments": false
      "documents": {
          "html": "",
          "txt": ""