Legacy Previews API

📘

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].

Core Functionality

For all Email Previews tests you will follow the same basic process:

1. Create: Create a new test and get a unique test guid.
2. Send: Send in your email, HTML, or URL.
3. Verify: Verify that we have received your test and are processing it.
4. Process Results: Once you receive your results via polling or callbacks you can provide them to your end user.

Additional Functionality

In addition to the core functionality of the Litmus API, there are a few other functions you can perform. These supplemental functions are especially helpful for email designers to ensure everything is working as planned:

• Link Check: Your email may include links to external sources or back to your company's homepage. To ensure that your links are working Litmus will check them for you.

• Code Analysis: The Code Analysis feature provides a compatibility report for your email’s HTML/CSS within several email clients.

• Spam Testing: Include Litmus' spam seed addresses in your Email Previews test to receive valuable information about your email.

Integration Assistance

There are few additional areas of resources to look at when building your integration with the Litmus API:

• Polling: To request information from Litmus.
• Callbacks: To receive information from Litmus as soon as your EmailTests have completed.
• Index: An explanation of some of the most important attributes in the API.
• Generating and Using User GUIDs: If you are offering unlimited testing to your users, we need to identify the unique users of your application. See the guide for more information.
• See the API Documentation at work: Visit https://previews-api.litmus.com/

SSL/TLS

All API endpoints are only available via HTTPS, using TLS 1.2 or greater.

Start Your Test

Start a Litmus email test by sending a POST request to https://previews-api.litmus.com/api/v1/EmailTests

You can customize the request by requesting whatever TestingApplications you want. If you want to test all TestingApplications simply send an empty EmailTest object. To retrieve all TestingApplications follow the steps listed here for GET TestingApplications.

An example of creating an email preview for all TestingApplications looks like this:

Shell

curl https://previews-api.litmus.com/api/v1/EmailTests \
  -u username:password \
  -X POST \
  -H "Content-type: application/json" \
  -d '{}'

An example of creating an email preview for only one TestingApplications for Outlook 2010 ("ol2010") looks like this:

Shell

curl https://previews-api.litmus.com/api/v1/EmailTests \
  -u username:password \
  -X POST \
  -H "Content-type: application/json" \
  -d '{"TestingApplications": [
    { "ApplicationName": "OL2010" }
  ]
}'

Here is an example of a response from Litmus:

JSON

{
  "TestingApplications": [
    {
      "State": "pending",
      "WindowImageContentBlocking": "s3.amazonaws.com",
      "FullpageImageThumb": "s3.amazonaws.com",
      "BusinessOrPopular": true,
      "WindowImageThumbNoContentBlocking": "s3.amazonaws.com",
      "Completed": false,
      "FullpageImage": "s3.amazonaws.com",
      "FoundInSpam": false,
      "SupportsSpamScoring": null,
      "Status": 0,
      "WindowImageNoContentBlocking": "s3.amazonaws.com",
      "PlatformName": "Windows",
      "AverageTimeToProcess": 38,
      "SpamHeaders": [],
      "WindowImageThumb": "s3.amazonaws.com",
      "RenderedHtmlUrl": null,
      "PlatformLongName": "Microsoft Windows",
      "FullpageImageThumbContentBlocking": "s3.amazonaws.com",
      "WindowImage": "s3.amazonaws.com",
      "FullpageImageContentBlocking": "s3.amazonaws.com",
      "SupportsContentBlocking": true,
      "ApplicationName": "OL2010",
      "FullpageImageThumbNoContentBlocking": "s3.amazonaws.com",
      "SpamScore": 0.0,
      "DesktopClient": true,
      "WindowImageThumbContentBlocking": "s3.amazonaws.com",
      "Id": your-result-id-here,
      "ResultType": 0,
      "FullpageImageNoContentBlocking": "s3.amazonaws.com",
      "ApplicationLongName": "Outlook 2010"
    }
  ],
  "State": "waiting",
  "InboxGuid": your-inbox-guid-here,
  "Id": your-test-set-id-here,
  "Source": "https://s3.amazonaws.com/sitevista/",
  "Subject": "",
  "Html": "https://html.litmus.com/email/?url=/sitevista/",
  "ZipFile": "http://zip.litmus.com/resellers/?guid="your-guid-here,
  "TestType": 0,
  "Sandbox": false,
  "UserGuid": null,
  "Error": false,
  "ErrorMessage": null
}

Send Us Your Email

The response you will receive contains some important information, including theInboxGuid. The InboxGuid is a unique identifier for this test. You will use the InboxGuid to create and send an email to [e-mail]. When we receive your email at that unique email address we will know to associate it with the test you created.

Note: The email address [e-mail] must appear in the email headers in the To:, CC:, or BCC: field in order for us to associate that message with your test.

The second piece of important information is the Id. The Id is the unique integer for this test or result that you will use to poll for results or match a callback to.

Head back up above to see the a sample of InboxGuid and Id from a sample Litmus response.

Verify Your Test

At this point you will need to ensure that your email has been received and is being processed.

Make a GET request to https://previews-api.litmus.com/api/v1/EmailTests/{id} where {id} = the Id from the Litmus response you received from your POST request.

Here is an example of the GET request:

Shell

curl -u username:password https://previews-api.litmus.com/api/v1/EmailTests/{id}

Your response should look similar to the response you received from your POST request.

Check the State field. There are 4 possible States:

1. waiting: Litmus is still waiting to receive your email. Your test isn't running.
2. processing: Litmus has received your email and is in the process of running your test.
3. complete: Litmus has completed your test. Your images are ready.
4. error: Something went wrong. You will have to retest for this client.

Note:####

If you receive a waiting State for several minutes it is safe to resend your email. If your test never leaves the waiting State it is possible that:

1. Your message never made it to your unique InboxGuid email address. Contact support at [email protected] and/or contact your email service provider.
2. Your email service is providing placeholder data in the To:, CC:, and BCC: fields. We cannot associate your email with your unique InboxGuid if [e-mail] doesn't appear in the email headers. Contact your email service provider for additional assistance.

Process Results

Each of the results contained within emailTest.Results can be used to display capture images to your users. There are a few things to check before attempting to use the image URLs in EmailTests results:

Has the result completed?

If you verified that your result's Completed property is true, it is safe to use the result to find its images (covered below).

Is the result a type with captures?

If result's ResultType property is email, it will have capture images. If it's spam, it won't.

If the answer to the above questions is "yes," then you can move onto deciding which properties contain the capture images you want.

Choosing the right images

If your result's SupportsContentBlocking property is true, you should use the following properties:

Shell

WindowImageNoContentBlocking
WindowImageContentBlocking
FullpageImageNoContentBlocking
FullpageImageContentBlocking

Shell

WindowImageNoContentBlockingThumb
WindowImageContentBlockingThumb
FullpageImageNoContentBlockingThumb
FullpageImageContentBlockingThumb

If SupportsContentBlocking is false, you should use the following properties:

Shell

WindowImage
FullpageImage

Shell

WindowImageThumb
FullpageImageThumb

Link Check

The Litmus Link Check tool will make sure links in your HTML are valid. This is ideal for email designers who need to ensure everything is perfect before clicking "Send."

Create a LinkTest by sending a POST request that includes your email's HTML to our API:

Shell

curl https://previews-api.litmus.com/api/v1/LinkTests \
  -u username:password \
  -i \
  -X POST \
  -H "Content-type: application/json" \
  -d "\"<div><a href='http://www.litmus.com?utm_source=twitter&utm_term=oct'>Litmus</a></div>\""

Note: There are quotes surrounding the HTML

Important: You should only paste the HTML portion of your email - no subject line, plain text parts etc.

Just like an Email Previews test, once you POST to the API you will need to poll the API to determine if your Link Check Test has completed. Make the following GET request to check the State:

Shell

curl -u username:password https://previews-api.litmus.com/api/v1/LinkTests/{id}

Once the State of the test is Complete you can parse through the object to get the result of your test.

Understanding Link Check Results

LinkTest Object

Attribute	Description
Id	Unique Id for this LinkTest. Use this value to poll for results.
Links	Collection of Link Objects with details about the links we've detected in your email.
SourceUrl	The HTML source that was used for this test.
ImageUrl	A screenshot of the rendered HTML.
State	Processing, Complete, or Error
Error	Boolean value indicating if there was an error processing this LinkTest
ErrorMessage	Details about the error if Error == true.

Link Object

Attribute	Description
Url	The Url for this Link.
IsValid	If the Url returned a 200 via an Http request.
Exception	If the Url did not return a 200 - what error did it return.
IsBlackListed	Is the Url listed on common blacklists?
HasGoogleAnalytics	Does the Url have Google Analytics parameters?
HasClickTracking	Does the Url have click tracking turned on? This is determined by detecting a URL redirect, which is the most common way to perform click tracking.
PageTtitle	The title of the page the link leads to.
TopLeftX	X position of the link in the rendered HTML.
TopLeftY	Y position of the link in the rendered HTML.
GoogleAnalyticsParameters	If the link does have GoogleAnalyticsParameters this will contain a parsed collection of those parameters.
ThumbnailsUrl	A small screenshot of the page the the link leads to.

Code Analysis

The Litmus Code Analysis tool will check submitted HTML and CSS for style problems. If the tool identifies a problem we will provide the line number and problem description.

To retrieve a list of all ApplicationName fields for CodeAnalysisByTestingApplications place a GET request to https://previews-api.litmus.com/api/v1/TestingApplications

Submit your CodeAnalysis request by POST request:

Shell

curl https://previews-api.litmus.com/api/v1/CodeAnalysis \
  -u username:password \
  -i \
  -X POST \
  -H "Content-type: application/json" \
  -d "\"<div><a href='http://www.litmus.com?utm_source=twitter&utm_term=oct'>Litmus</a></div>\""

You can request a CodeAnalysis test for only certain applications by making a call to CodeAnalysisByTestingApplications:

Shell

curl https://previews-api.litmus.com/api/v1/CodeAnalysisByTestingApplications \
  -u username:password \
  -i \
  -X POST \
  -H "Content-type: application/json" \
  -d '{"Html": "<h1>Test</h1><p><a href=\"http://www.litmus.com\">Litmus</a></p>","TestingApplications": [ "ol2010"]}'

Note: Quotes should be surrounding the HTML
Important: You should only paste the HTML portion of your email - no subject line, plain text parts etc.

Understanding CodeAnalysis Results

CodeAnalysisTest

Attribute	Description
CompatibilityProblems	A collection of compatibility problems that we found in your HTML.
CompatibilityRulesCount	The total number of compatibility rules we validated your HTML against.
HtmlProblems	A collection of HTML format and syntax problems we found in your HTML.

CodeAnalysisPotentialProblems

Attribute	Description
LineNumber	The line in the HTML where this problem was found.
Severity	0 or 1 where 0 is less severe an issue and 1 is more severe.
Description	A text description of the problem.

CodeAnalysisHtmlValidation

Attribute	Description
LineNumber	The line in the HTML where this problem was found.
Description	A text description of the problem.

Spam Testing

The process for Spam Testing is similar to the process for Email Previews, but there are a few additional steps.

Include Spam TestingApplications

Make sure you include all TestingApplications that have a ResultType of 1 or Spam. To retrieve all TestingApplications follow the steps listed here for GET TestingApplications. If you want to include all TestingApplications send an empty EmailTest object.

Include Spam Seed Addresses

In addition to sending your email to [e-mail], you will need to send the email to Litmus' spam seed addresses. To receive a list of spam seed addresses follow the steps here for GET SpamSeedAddresses. If you skip this step your email will not be tested for spam.

Verify

Verify that we have received your test and are processing it.

Process Results

Process your results and provide them to your end user. Once you receive your results via polling or callbacks you can provide them to your end user

Understanding Spam Test Results

SpamHeader

Attribute	Description
Key	String key returned by the spam provider for this header.
Id	Integer unique id in Litmus for this header.
Description	Text description in English of what potential issue this header indicates.
Rating	A value, determined by Litmus, indicating the severity of this potential issue. The values are 1 - 5 with 1 being very minor and 5 being a serious issue.

Polling

Once the State of your EmailTests is processing you may start polling for results. Note: Litmus recommends polling sequentially. For example: 3s, 3s, 6s, 9s, 15s, 24s, 30s. Once you reach 30s poll every 30s to avoid polling aggressively. Important: Aggressive polling will trigger slower updates.

To begin polling your program should start GetEmailTest once the State is processing. The Result for each ApplicationName should begin to return completed. You may poll every 60 seconds until every Result is completed.

Callbacks

To get started using callbacks you will need to provide us with a URL to send Litmus test results to. You can set this up easily by contacting our reseller support at [email protected].

We strongly recommend that your URL is SSL (served over https) with a valid certificate and uses basic authentication. This means you'll need to provide us with a username and password.

Once we have your URL stored in our system we will POST data to that URL every time one of your individual results completes.

Here is an example of what your POST request might look like:

C#

var emailTest = new EmailTest();

// Create our list and make space for two clients
emailTest.Results = new Client[3]
// Create a Client object within the first space
emailTest.Results[0] = new Client
// Assign Outlook 2003's ApplicationName to that new Client object
emailTest.Results[0].ApplicationName = "OL2010"
// Repeat for Spam Asassin
emailTest.Results[2] = new Client
emailTest.Results[2].ApplicationName = "SPAMASSASSIN3"
emailTest = LitmusApi.CreateEmailTest("api-key", "api-pass", emailTest);

As soon as the Completed becomes true we will POST data to your URL.

Here is an example of what that data might look like:

XML

<?xml version="1.0" encoding="utf-8"?>
<TestResult type="mail">
  <Id>your-id</Id>
  <ApiId>OL2010</ApiId>
  <SupportsContentBlocking>False</SupportsContentBlocking>
  <ResultImageSet>
    <ImagesOnUrls>
      <WindowUrls>
        <ImageUrl>s3.amazonaws.com/resultcaptures/unique-guid.windowon.png</ImageUrl>
        <ThumbUrl>s3.amazonaws.com/resultcaptures/unique-guid.windowonthumb.png</ThumbUrl>
      </WindowUrls>
      <FullPageUrls>
        <ImageUrl>s3.amazonaws.com/resultcaptures/unique-guid.fullpageon.png</ImageUrl>
        <ThumbUrl>s3.amazonaws.com/resultcaptures/unique-guid.fullpageonthumb.png</ThumbUrl>
      </FullPageUrls>
    </ImagesOnUrls>
    <ImagesOffUrls>
      <WindowUrls>
        <ImageUrl>s3.amazonaws.com/resultcaptures/unique-guid.windowon.png</ImageUrl>
        <ThumbUrl>s3.amazonaws.com/resultcaptures/unique-guid.windowonthumb.png</ThumbUrl>
      </WindowUrls>
      <FullPageUrls>
        <ImageUrl>s3.amazonaws.com/resultcaptures/unique-guid.fullpageon.png</ImageUrl>
        <ThumbUrl>s3.amazonaws.com/resultcaptures/unique-guid.fullpageonthumb.png</ThumbUrl>
      </FullPageUrls>
    </ImagesOffUrls>
  </ResultImageSet>
  <SpamResult />
  <State>Completed</State>
  <CallbackUrl>http://mysite.com/callback/</CallbackUrl>
</TestResult>

For spam tests, the xml will have the following format:

XML

<?xml version="1.0" encoding="utf-8"?>
<TestResult type="spam">
  <Id>554</Id>
  <ApiId>SPAMASSASSIN3</ApiId>
  <SupportsContentBlocking>false</SupportsContentBlocking>
  <ResultImageSet />
  <SpamResult>
    <SpamScore>9.4</SpamScore>
    <IsSpam>True</IsSpam>
    <SpamHeaders>
      <SpamHeader>
        <Key>HTML_FONT_FACE_BAD</Key>
        <Description>The font face used in your email is not valid.
        Try validating the HTML of your email using the W3C
        validator to make sure you are using standard
        HTML.</Description>
        <Rating>4</Rating>
      </SpamHeader>
      <SpamHeader>
        <Key>HTML_MESSAGE</Key>
        <Description>Your email contains HTML content. This won't
        usually cause you to fail any spam filters.</Description>
        <Rating>2</Rating>
      </SpamHeader>
      <SpamHeader>
        <Key>URIBL_AB_SURBL</Key>
        <Description>Your email contains a URL blacklisted by &lt;a
        href="http://www.abusebutler.com/"&gt;Abuse
        Butler&lt;/a&gt;.</Description>
        <Rating>3</Rating>
      </SpamHeader>
      <SpamHeader>
        <Key>URIBL_JP_SURBL</Key>
        <Description>Your email contains a URL blacklisted by &lt;a
        href="http://www.joewein.de/sw/blacklist.htm"&gt;jwSpamSpy&lt;/a&gt;.</Description>
        <Rating>3</Rating>
      </SpamHeader>
      <SpamHeader>
        <Key>URIBL_OB_SURBL</Key>
        <Description>Your email contains a URL blacklisted by &lt;a
        href="http://www.outblaze.com/"&gt;Outblaze&lt;/a&gt;.</Description>
        <Rating>3</Rating>
      </SpamHeader>
      <SpamHeader>
        <Key>URIBL_SC_SURBL</Key>
        <Description>Your email contains a URL blacklisted by &lt;a
        href="http://www.spamcop.net/"&gt;SpamCop&lt;/a&gt;.</Description>
        <Rating>3</Rating>
      </SpamHeader>
    </SpamHeaders>
  </SpamResult>
 <CallbackUrl>http://mysite.com/callback/</CallbackUrl>
</TestResult>

Generating and Using User GUIDs

If you are offering an unlimited testing facility to your users, we need to be able to identify the number of unique users of your application. This is done by setting a user GUID for each test you create.

If you are billing your users exclusively on a per-test basis you can ignore this feature

Important: You must be certain that the GUID used is unique to that user. The GUID should be stored in a unique field within your database and should not change for the life of that user's account.

This information is never shared with anyone, not even your user. It will be used in your billing reports and returned to you along with your test results.

Do not use a hash of your user's details unless you ensure that this will remain unchanged and unique for that user. You will want to refrain from hashing user details because, by doing so, a hash of their email address could change over time and cause them to be identified twice in one month.

Some examples of using Generated User GUIDs in POST requests:

Shell

curl https://previews-api.litmus.com/api/v1/EmailTests \
  -u username:password \
  -X POST \
  -H "Content-type: application/json" \
  -d '{"UserGuid":"SomeGuid"}'

Shell

curl https://previews-api.litmus.com/api/v1/EmailTests \
  -u username:password \
  -X POST \
  -H "Content-type: application/json" \
  -d '{"UserGuid":"YourUsersGuid", \
    "TestingApplications": {["ApplicationName": ...]}
  }'