📘

Access to our APIs is evaluated on a case-by-case basis. To find out if your use case is one that we support feel free to get in touch with the details of your project. [email protected].

Why the Instant API?

The Instant API is ideal for integration within email editing tools that have an iterative workflow which can be enhanced with real, rather than approximated, previews.

Our Instant API is the easiest and fastest way to get super speedy email client screenshots into your service. In fact, it's what Litmus uses to power its email client previews within Builder. If you haven't checked that out already, we'd recommend giving it a try to see the API in action.

The Instant API in action in Litmus BuilderThe Instant API in action in Litmus Builder

In our editor, a user makes a change to their email and saves. The screenshots on the right automatically refresh within seconds.

How does it work?

When a user makes a change to their email, or tests it for the first time, you create a new Instant test by creating a POST request with details of the email. There's no need to send an email to us, simply POST the HTML and other details, along with a list of the email clients you'd like us to screenshot. We'll return a unique email id (email_guid) to you.

And that's it! To show the screenshots to the user, all you need to do is set the src attribute of an img:

<img alt="Outlook 2003"
     src="https://instant-api.litmus.com/v1/emails/{email_guid}/previews/OL2003/full"/>

Litmus will handle the rest. For more granular control, you can specify fallback images to show in case there was a problem or timeout, or request the image server-side. We've covered all those specifics and more below, but even with the simplest implementation, we're sure you'll be thrilled with the ease of integration and the reliable performance.

How fast is fast?

Pretty damn fast. Where previews have traditionally taken many minutes to complete, Litmus' previews return within seconds without any accuracy cost—it’s still real screenshots of real email clients. In the table below, we’ve included a sample of average completion times seen when using the Instant API. In all cases, you should expect previews to return in around 10 seconds or less.

Typically, creating an Instant Preview test will take 600ms to generate an email_guid. If your images are larger or take longer to download, you may see this step take a little longer.

Email ClientAverage speed via the Instant API
Outlooks3s - 7s
iPhones & iPads7s
Android & Gmail apps7s - 10s
Gmail & Google Apps5s - 8s
Yahoo, AOL & Outlook.com5s - 11s
Apple Mails5s
Lotus Notes6s

Overview

Previews can be obtained in only two steps:

  1. POST an email
    Describe its content and attributes in JSON. In response, the API will provide you with an email_guid

  2. GET each preview required
    Specify the email_guid and the desired client

The GET request does not require authentication, so it can be used directly as the source for an image within an end user’s browser.

Requiring that the email source is POSTed via HTTP, rather than waiting on email delivery, is one of the methods used to obtain the fast responses.

📘

To capture the most reflective previews, please ensure that the email source provided has been through any transformation that would be applied by the Email Service Provider before being sent on to the mail transfer agent.

Base URI

The base URI of the API is https://instant-api.litmus.com/v1

SSL/TLS

All API endpoints are only available via HTTPS.

Content types

By default all data is sent and received as application/json, exceptions to this are marked in the documentation.

CORS, JSONP

Neither CORS nor JSONP are currently supported. If you have a use case that would benefit from either, please let us know.

Authentication

The Instant API support authentication with either:

  • HTTP Basic Authentication - use an API key to make calls on behalf of your own account; or:
  • OAuth Bearer tokens - act on behalf of Litmus users with usage against their account

HTTP Basic Authentication

For each Instant API application, you’ll be issued an API key. The API key should be provided in the Auth Basic username field. The password field can be left blank.

For the cURL examples shown below, either export your key to the API_KEY environment variable, eg

$ export API_KEY="XeyNuXp_NdVtTREH1iaJ78vjFqlBGQfaJOur"

or replace $API_KEY in each example with your key directly. Note that the trailing colon will hint cURL to send the required empty password, rather than prompting you for it.

OAuth Bearer Tokens

OAuth is useful when you wish to access the API on behalf of Litmus users, typically when you want to bring Litmus features to your own web application, but leverage the Litmus subscriptions that your users may already have.

Obtaining tokens requires implementing the OAuth2 flow within your application which involves sending each end user to litmus.com to authorize you to act on their behalf after which they're returned. See our guide on implementing the OAuth2 flow for detailed integration details.

To authorize an API request with a Bearer token, provide an HTTP Authorization header of Bearer $TOKEN (replacing $TOKEN appropriately), eg

$ curl -X "POST" "https://instant-api.litmus.com/v1/emails" \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e"\
       -d "{\"plain_text\":\"Hello World\"}" -v

> POST /v1/emails HTTP/1.1
> Host: instant-api.litmus.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e
> Content-Length: 28
>

< HTTP/1.1 200 OK
< Server: nginx
< Date: Tue, 21 Jun 2016 20:10:06 GMT
< Content-Type: application/json;charset=utf-8
< Content-Length: 58
< Connection: keep-alive
< Strict-Transport-Security: max-age=3600; includeSubdomains; preload
< X-Frame-Options: DENY
< X-Content-Type-Options: nosniff
<

{
  "email_guid": "113bdfdf-6d54-4cbe-8d38-dd66157e1751"
}

Lifetimes

Emails

Uploaded emails are available to request new captures against for up to 48 hours. After this time, attempting to capture a new preview may yield a 404 Not Found when using the corresponding email_guid.

If access to unrequested previews is likely outside the 48 hour window, you can:

  • Pre-request previews if you know expected capture configurations; or:
  • Repost the email and obtain a fresh email_guid then capture a new preview using this

Previews

The image data following a successful capture will be available for 180 days. However, the storage location during this time may change. Once time has passed since a capture, a request to either the Instant API previews endpoint or a litmuscdn URL returned by the API will handle these changes in location gracefully—they will return a 404 Not Found when a capture is no longer available. Later requests to other locations, like the result of the redirection when the initial capture was made, may result in failure when a capture is still available.

If access to previews is likely outside the 180 day window, you can:

  • Download the previews when first captured and host them elsewhere

Example

To make our example less verbose, first download an example HTML email encoded in to the html_text property of a JSON object:

$ wget https://litmus.com/partners/api/documentation/instant/html-test-email.json

Next describe an email, providing your application's API key. This step is intended to be conducted server to server. Do not share the API key with your end users.

$ curl -X "POST" "https://instant-api.litmus.com/v1/emails" \
       -H "Content-Type: application/json" \
       -u "$API_KEY:" \
       -d @html-test-email.json -v
> POST /v1/emails HTTP/1.1
> Authorization: Basic XXXXXXXXXXXXXXXXXXXXXX
> User-Agent: curl/7.37.1
> Host: instant-api.litmus.com
> Accept: */*
> Content-Type: application/json
> Content-Length: 59740
> Expect: 100-continue
>
< HTTP/1.1 100 Continue
< HTTP/1.1 200 OK
< Server: nginx
< Date: Fri, 12 Jun 2015 16:58:38 GMT
< Content-Type: application/json
< Content-Length: 58
< Connection: keep-alive
< Strict-Transport-Security: max-age=3600;
<
{
  "email_guid": "87bf47f2-600e-40eb-8ccb-c9649f17644d"
}

Then simply construct a GET request for each capture you require, using the email_guid you just received and a code for the client you want (OL2015 in this example):

$ curl -X "GET" "https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full" -v
> GET /v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full HTTP/1.1
> User-Agent: curl/7.37.1
> Host: instant-api.litmus.com
> Accept: */*
>
< HTTP/1.1 301 Moved Permanently
< Server: nginx
< Date: Fri, 12 Jun 2015 17:37:40 GMT
< Content-Type: application/json
< Content-Length: 0
< Connection: keep-alive
< Location: https://ol2015.capture.litmuscdn.com/87bf47f2-600e-40eb-8ccb-c9649f17644d/results/ol2015-vertical-allowed.png
< Strict-Transport-Security: max-age=3600;
<

Behind the scenes a lot of work is going on between the GET being received and the response being provided—the capture of the preview is only initiated once the first request for it is received. While capture is occurring the HTTP connection remains open, once complete the response is sent and then the connection closed. Typically this will take around 6 seconds.

The GET URL can be embedded directly in an HTML image tag:

<html>
<body>
  <img src="https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full">
</body>