{"__v":12,"_id":"56668cadce8caf0d006018b4","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"This documentation applies to our reseller APIs. For access please [get in touch](https://litmus.com/api#api-form).\"\n}\n[/block]\n# Overview\n\nLitmus APIs enable you to integrate industry-leading tools into your own products and applications. We offer solutions for both Email Previews and Email Analytics, so you or your customers can preview their email designs, and learn more about their subscriber base through powerful metrics.\n\nThe [Litmus Instant API](doc: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.\n\nThe [Litmus Email Analytics API](doc:email-analytics) allows you to create new campaigns, generate HTML tracking code to insert into your outgoing emails, and the ability to access in-depth metrics detailing the ‘when,’ ‘where,’ and ‘how’ an email is opened.\n\nThe [Legacy Previews API](doc:legacy-previews) allows you to run email previews, spam tests, link-check tests, and perform code analysis.\n\n## REST Based\n\nThe latest version of all of our API's are REST based—this makes them easy to integrate no matter which technology you use! We have partners integrate with our APIs using C#, Visual Basic, PHP, Ruby, Python, Perl, and Java.  \n\n## Status\n\nYou can check the status of the API and other services via our status page: https://status.litmus.com/.\n\n## Support\n\nHaving trouble implementing one of our API's?  Don't see an example of something you want to do?  Not sure if we support your language or platform?  Have any other questions or problems?  Our support engineers are experts at navigating all kinds of API related issues.  Contact us at [resellers@litmus.com](mailto:resellers@litmus.com).","category":"56668bca7cc81e0d00253f77","createdAt":"2015-12-08T07:54:21.004Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","next":{"description":"","pages":[]},"order":0,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"litmus-api-documentation","sync_unique":"","title":"Litmus API Docs","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Litmus API Docs


[block:callout] { "type": "info", "body": "This documentation applies to our reseller APIs. For access please [get in touch](https://litmus.com/api#api-form)." } [/block] # Overview Litmus APIs enable you to integrate industry-leading tools into your own products and applications. We offer solutions for both Email Previews and Email Analytics, so you or your customers can preview their email designs, and learn more about their subscriber base through powerful metrics. The [Litmus Instant API](doc: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 [Litmus Email Analytics API](doc:email-analytics) allows you to create new campaigns, generate HTML tracking code to insert into your outgoing emails, and the ability to access in-depth metrics detailing the ‘when,’ ‘where,’ and ‘how’ an email is opened. The [Legacy Previews API](doc:legacy-previews) allows you to run email previews, spam tests, link-check tests, and perform code analysis. ## REST Based The latest version of all of our API's are REST based—this makes them easy to integrate no matter which technology you use! We have partners integrate with our APIs using C#, Visual Basic, PHP, Ruby, Python, Perl, and Java. ## Status You can check the status of the API and other services via our status page: https://status.litmus.com/. ## Support Having trouble implementing one of our API's? Don't see an example of something you want to do? Not sure if we support your language or platform? Have any other questions or problems? Our support engineers are experts at navigating all kinds of API related issues. Contact us at [resellers@litmus.com](mailto:resellers@litmus.com).
[block:callout] { "type": "info", "body": "This documentation applies to our reseller APIs. For access please [get in touch](https://litmus.com/api#api-form)." } [/block] # Overview Litmus APIs enable you to integrate industry-leading tools into your own products and applications. We offer solutions for both Email Previews and Email Analytics, so you or your customers can preview their email designs, and learn more about their subscriber base through powerful metrics. The [Litmus Instant API](doc: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 [Litmus Email Analytics API](doc:email-analytics) allows you to create new campaigns, generate HTML tracking code to insert into your outgoing emails, and the ability to access in-depth metrics detailing the ‘when,’ ‘where,’ and ‘how’ an email is opened. The [Legacy Previews API](doc:legacy-previews) allows you to run email previews, spam tests, link-check tests, and perform code analysis. ## REST Based The latest version of all of our API's are REST based—this makes them easy to integrate no matter which technology you use! We have partners integrate with our APIs using C#, Visual Basic, PHP, Ruby, Python, Perl, and Java. ## Status You can check the status of the API and other services via our status page: https://status.litmus.com/. ## Support Having trouble implementing one of our API's? Don't see an example of something you want to do? Not sure if we support your language or platform? Have any other questions or problems? Our support engineers are experts at navigating all kinds of API related issues. Contact us at [resellers@litmus.com](mailto:resellers@litmus.com).
{"__v":26,"_id":"565f2992bca87d0d006bc679","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"## Why the Instant API?\n\nThe 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.\n\nOur 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](https://litmus.com/email-builder) to see the API in action.\n\n[![The Instant API in action in Litmus Builder](https://litmuswww.s3.amazonaws.com/partners/instant-builder.png)](https://litmus.com/email-builder)\n\nIn our editor, a user makes a change to their email and saves. The screenshots on the right automatically refresh within seconds.\n\n## How does it work?\n\nWhen 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.\n\n**And that's it!** To show the screenshots to the user, all you need to do is set the `src` attribute of an `img`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<img alt=\\\"Outlook 2003\\\"\\n     src=\\\"https://instant-api.litmus.com/v1/emails/{email_guid}/previews/OL2003/full\\\"/>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nLitmus 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.\n\n### How fast is fast?\n\nPretty 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.\n\nTypically, 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.\n\n| Email Client             | Average speed via the Instant API   |\n| ------------------------ | --------- |\n| Outlooks                 | 3s - 7s   |\n| iPhones & iPads          | 7s        |\n| Android & Gmail apps     | 7s - 10s  |\n| Gmail & Google Apps      | 5s -  8s  |\n| Yahoo, AOL & Outlook.com | 5s -  11s |\n| Apple Mails              | 5s        |\n| Lotus Notes              | 6s        |\n\n\n## Overview\n\nPreviews can be obtained in only two steps:\n\n1. **POST an email**<br>Describe its content and attributes in JSON. In response, the API will provide you with an `email_guid`\n\n2. **GET each preview required**<br>Specify the `email_guid` and the desired `client`\n\nThe GET request does not require authentication, so it can be used directly as the source for an image within an end user’s browser.\n\nRequiring 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.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"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.\"\n}\n[/block]\n### Base URI\n\nThe base URI of the API is `https://instant-api.litmus.com/v1`\n\n### SSL/TLS\n\nAll API endpoints are only available via HTTPS.\n\n### Content types\n\nBy default all data is sent and received as `application/json`, exceptions to this are marked in the documentation.\n\n### CORS, JSONP\n\nNeither CORS nor JSONP are currently supported. If you have a use case that would benefit from either, please [let us know](mailto:hello@litmus.com).\n\n## Authentication\n\nThe Instant API support authentication with either:\n- **HTTP Basic Authentication** - use an API key to make calls on behalf of your own account; or:\n- **OAuth Bearer tokens** - act on behalf of Litmus users with usage against their account\n\n### HTTP Basic Authentication\n\nFor 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.\n\nFor the cURL examples shown below, either export your key to the API_KEY environment variable, eg\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ export API_KEY=\\\"XeyNuXp_NdVtTREH1iaJ78vjFqlBGQfaJOur\\\"\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nor 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.\n\n### OAuth Bearer Tokens\n\nOAuth 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.\n\nObtaining 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](doc:oauth-integration-guide) for detailed integration details.\n\nTo authorize an API request with a Bearer token, provide an HTTP `Authorization` header of `Bearer $TOKEN` (replacing $TOKEN appropriately), eg\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X \\\"POST\\\" \\\"https://instant-api.litmus.com/v1/emails\\\" \\\\\\n       -H \\\"Content-Type: application/json\\\" \\\\\\n       -H \\\"Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e\\\"\\\\\\n       -d \\\"{\\\\\\\"plain_text\\\\\\\":\\\\\\\"Hello World\\\\\\\"}\\\" -v\\n\\n> POST /v1/emails HTTP/1.1\\n> Host: instant-api.litmus.com\\n> User-Agent: curl/7.43.0\\n> Accept: */*\\n> Content-Type: application/json\\n> Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e\\n> Content-Length: 28\\n>\\n\\n< HTTP/1.1 200 OK\\n< Server: nginx\\n< Date: Tue, 21 Jun 2016 20:10:06 GMT\\n< Content-Type: application/json;charset=utf-8\\n< Content-Length: 58\\n< Connection: keep-alive\\n< Strict-Transport-Security: max-age=3600; includeSubdomains; preload\\n< X-Frame-Options: DENY\\n< X-Content-Type-Options: nosniff\\n<\\n\\n{\\n  \\\"email_guid\\\": \\\"113bdfdf-6d54-4cbe-8d38-dd66157e1751\\\"\\n}\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n## Lifetimes\n\n### Emails\n\nUploaded emails are available to request new captures against for up to 48 hours. After this time, attempting to capture a preview may yield a `404 Not Found` when using the corresponding `email_guid`.\n\nIf access to *unrequested* previews is likely outside the 48 hour window, you can:\n\n- Pre-request previews if you know expected capture configurations; or:\n- Repost the email and obtain a fresh `email_guid` then capture a new preview using this\n\n### Previews\n\nThe image data following a successful capture will be available for 365 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.\n\nIf access to previews is likely outside the 365 day window, you can:\n\n- Download the previews when first captured and host them elsewhere\n\n# Example\n\nTo make our example less verbose, first download an example [HTML email](https://litmus.com/partners/api/documentation/instant/html-test-email.json) encoded in to the `html_text` property of a JSON object:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ wget https://litmus.com/partners/api/documentation/instant/html-test-email.json\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nNext 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X \\\"POST\\\" \\\"https://instant-api.litmus.com/v1/emails\\\" \\\\\\n       -H \\\"Content-Type: application/json\\\" \\\\\\n       -u \\\"$API_KEY:\\\" \\\\\\n       -d @html-test-email.json -v\\n> POST /v1/emails HTTP/1.1\\n> Authorization: Basic XXXXXXXXXXXXXXXXXXXXXX\\n> User-Agent: curl/7.37.1\\n> Host: instant-api.litmus.com\\n> Accept: */*\\n> Content-Type: application/json\\n> Content-Length: 59740\\n> Expect: 100-continue\\n>\\n< HTTP/1.1 100 Continue\\n< HTTP/1.1 200 OK\\n< Server: nginx\\n< Date: Fri, 12 Jun 2015 16:58:38 GMT\\n< Content-Type: application/json\\n< Content-Length: 58\\n< Connection: keep-alive\\n< Strict-Transport-Security: max-age=3600;\\n<\\n{\\n  \\\"email_guid\\\": \\\"87bf47f2-600e-40eb-8ccb-c9649f17644d\\\"\\n}\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nThen 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):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X \\\"GET\\\" \\\"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full\\\" -v\\n> GET /v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full HTTP/1.1\\n> User-Agent: curl/7.37.1\\n> Host: instant-api.litmus.com\\n> Accept: */*\\n>\\n< HTTP/1.1 301 Moved Permanently\\n< Server: nginx\\n< Date: Fri, 12 Jun 2015 17:37:40 GMT\\n< Content-Type: application/json\\n< Content-Length: 0\\n< Connection: keep-alive\\n< Location: https://ol2015.capture.litmuscdn.com/87bf47f2-600e-40eb-8ccb-c9649f17644d/results/ol2015-vertical-allowed.png\\n< Strict-Transport-Security: max-age=3600;\\n<\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nBehind 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.\n\nThe GET URL can be embedded directly in an HTML image tag:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<html>\\n<body>\\n  <img src=\\\"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full\\\">\\n</body>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]","category":"565f29797f93280d0052cf03","createdAt":"2015-12-02T17:25:38.060Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":0,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"instant-api","sync_unique":"","title":"Instant API","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Instant API


## 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](https://litmus.com/email-builder) to see the API in action. [![The Instant API in action in Litmus Builder](https://litmuswww.s3.amazonaws.com/partners/instant-builder.png)](https://litmus.com/email-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`: [block:code] { "codes": [ { "code": "<img alt=\"Outlook 2003\"\n src=\"https://instant-api.litmus.com/v1/emails/{email_guid}/previews/OL2003/full\"/>", "language": "html" } ] } [/block] 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 Client | Average speed via the Instant API | | ------------------------ | --------- | | Outlooks | 3s - 7s | | iPhones & iPads | 7s | | Android & Gmail apps | 7s - 10s | | Gmail & Google Apps | 5s - 8s | | Yahoo, AOL & Outlook.com | 5s - 11s | | Apple Mails | 5s | | Lotus Notes | 6s | ## Overview Previews can be obtained in only two steps: 1. **POST an email**<br>Describe its content and attributes in JSON. In response, the API will provide you with an `email_guid` 2. **GET each preview required**<br>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. [block:callout] { "type": "info", "body": "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." } [/block] ### 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](mailto:hello@litmus.com). ## 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 [block:code] { "codes": [ { "code": "$ export API_KEY=\"XeyNuXp_NdVtTREH1iaJ78vjFqlBGQfaJOur\"", "language": "shell" } ] } [/block] 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](doc:oauth-integration-guide) 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 [block:code] { "codes": [ { "code": "$ curl -X \"POST\" \"https://instant-api.litmus.com/v1/emails\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e\"\\\n -d \"{\\\"plain_text\\\":\\\"Hello World\\\"}\" -v\n\n> POST /v1/emails HTTP/1.1\n> Host: instant-api.litmus.com\n> User-Agent: curl/7.43.0\n> Accept: */*\n> Content-Type: application/json\n> Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e\n> Content-Length: 28\n>\n\n< HTTP/1.1 200 OK\n< Server: nginx\n< Date: Tue, 21 Jun 2016 20:10:06 GMT\n< Content-Type: application/json;charset=utf-8\n< Content-Length: 58\n< Connection: keep-alive\n< Strict-Transport-Security: max-age=3600; includeSubdomains; preload\n< X-Frame-Options: DENY\n< X-Content-Type-Options: nosniff\n<\n\n{\n \"email_guid\": \"113bdfdf-6d54-4cbe-8d38-dd66157e1751\"\n}", "language": "shell" } ] } [/block] ## Lifetimes ### Emails Uploaded emails are available to request new captures against for up to 48 hours. After this time, attempting to capture a 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 365 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 365 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](https://litmus.com/partners/api/documentation/instant/html-test-email.json) encoded in to the `html_text` property of a JSON object: [block:code] { "codes": [ { "code": "$ wget https://litmus.com/partners/api/documentation/instant/html-test-email.json", "language": "shell" } ] } [/block] 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. [block:code] { "codes": [ { "code": "$ curl -X \"POST\" \"https://instant-api.litmus.com/v1/emails\" \\\n -H \"Content-Type: application/json\" \\\n -u \"$API_KEY:\" \\\n -d @html-test-email.json -v\n> POST /v1/emails HTTP/1.1\n> Authorization: Basic XXXXXXXXXXXXXXXXXXXXXX\n> User-Agent: curl/7.37.1\n> Host: instant-api.litmus.com\n> Accept: */*\n> Content-Type: application/json\n> Content-Length: 59740\n> Expect: 100-continue\n>\n< HTTP/1.1 100 Continue\n< HTTP/1.1 200 OK\n< Server: nginx\n< Date: Fri, 12 Jun 2015 16:58:38 GMT\n< Content-Type: application/json\n< Content-Length: 58\n< Connection: keep-alive\n< Strict-Transport-Security: max-age=3600;\n<\n{\n \"email_guid\": \"87bf47f2-600e-40eb-8ccb-c9649f17644d\"\n}", "language": "shell" } ] } [/block] 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): [block:code] { "codes": [ { "code": "$ curl -X \"GET\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full\" -v\n> GET /v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full HTTP/1.1\n> User-Agent: curl/7.37.1\n> Host: instant-api.litmus.com\n> Accept: */*\n>\n< HTTP/1.1 301 Moved Permanently\n< Server: nginx\n< Date: Fri, 12 Jun 2015 17:37:40 GMT\n< Content-Type: application/json\n< Content-Length: 0\n< Connection: keep-alive\n< Location: https://ol2015.capture.litmuscdn.com/87bf47f2-600e-40eb-8ccb-c9649f17644d/results/ol2015-vertical-allowed.png\n< Strict-Transport-Security: max-age=3600;\n<", "language": "shell" } ] } [/block] 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: [block:code] { "codes": [ { "code": "<html>\n<body>\n <img src=\"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full\">\n</body>", "language": "html" } ] } [/block]
## 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](https://litmus.com/email-builder) to see the API in action. [![The Instant API in action in Litmus Builder](https://litmuswww.s3.amazonaws.com/partners/instant-builder.png)](https://litmus.com/email-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`: [block:code] { "codes": [ { "code": "<img alt=\"Outlook 2003\"\n src=\"https://instant-api.litmus.com/v1/emails/{email_guid}/previews/OL2003/full\"/>", "language": "html" } ] } [/block] 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 Client | Average speed via the Instant API | | ------------------------ | --------- | | Outlooks | 3s - 7s | | iPhones & iPads | 7s | | Android & Gmail apps | 7s - 10s | | Gmail & Google Apps | 5s - 8s | | Yahoo, AOL & Outlook.com | 5s - 11s | | Apple Mails | 5s | | Lotus Notes | 6s | ## Overview Previews can be obtained in only two steps: 1. **POST an email**<br>Describe its content and attributes in JSON. In response, the API will provide you with an `email_guid` 2. **GET each preview required**<br>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. [block:callout] { "type": "info", "body": "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." } [/block] ### 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](mailto:hello@litmus.com). ## 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 [block:code] { "codes": [ { "code": "$ export API_KEY=\"XeyNuXp_NdVtTREH1iaJ78vjFqlBGQfaJOur\"", "language": "shell" } ] } [/block] 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](doc:oauth-integration-guide) 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 [block:code] { "codes": [ { "code": "$ curl -X \"POST\" \"https://instant-api.litmus.com/v1/emails\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e\"\\\n -d \"{\\\"plain_text\\\":\\\"Hello World\\\"}\" -v\n\n> POST /v1/emails HTTP/1.1\n> Host: instant-api.litmus.com\n> User-Agent: curl/7.43.0\n> Accept: */*\n> Content-Type: application/json\n> Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e\n> Content-Length: 28\n>\n\n< HTTP/1.1 200 OK\n< Server: nginx\n< Date: Tue, 21 Jun 2016 20:10:06 GMT\n< Content-Type: application/json;charset=utf-8\n< Content-Length: 58\n< Connection: keep-alive\n< Strict-Transport-Security: max-age=3600; includeSubdomains; preload\n< X-Frame-Options: DENY\n< X-Content-Type-Options: nosniff\n<\n\n{\n \"email_guid\": \"113bdfdf-6d54-4cbe-8d38-dd66157e1751\"\n}", "language": "shell" } ] } [/block] ## Lifetimes ### Emails Uploaded emails are available to request new captures against for up to 48 hours. After this time, attempting to capture a 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 365 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 365 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](https://litmus.com/partners/api/documentation/instant/html-test-email.json) encoded in to the `html_text` property of a JSON object: [block:code] { "codes": [ { "code": "$ wget https://litmus.com/partners/api/documentation/instant/html-test-email.json", "language": "shell" } ] } [/block] 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. [block:code] { "codes": [ { "code": "$ curl -X \"POST\" \"https://instant-api.litmus.com/v1/emails\" \\\n -H \"Content-Type: application/json\" \\\n -u \"$API_KEY:\" \\\n -d @html-test-email.json -v\n> POST /v1/emails HTTP/1.1\n> Authorization: Basic XXXXXXXXXXXXXXXXXXXXXX\n> User-Agent: curl/7.37.1\n> Host: instant-api.litmus.com\n> Accept: */*\n> Content-Type: application/json\n> Content-Length: 59740\n> Expect: 100-continue\n>\n< HTTP/1.1 100 Continue\n< HTTP/1.1 200 OK\n< Server: nginx\n< Date: Fri, 12 Jun 2015 16:58:38 GMT\n< Content-Type: application/json\n< Content-Length: 58\n< Connection: keep-alive\n< Strict-Transport-Security: max-age=3600;\n<\n{\n \"email_guid\": \"87bf47f2-600e-40eb-8ccb-c9649f17644d\"\n}", "language": "shell" } ] } [/block] 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): [block:code] { "codes": [ { "code": "$ curl -X \"GET\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full\" -v\n> GET /v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full HTTP/1.1\n> User-Agent: curl/7.37.1\n> Host: instant-api.litmus.com\n> Accept: */*\n>\n< HTTP/1.1 301 Moved Permanently\n< Server: nginx\n< Date: Fri, 12 Jun 2015 17:37:40 GMT\n< Content-Type: application/json\n< Content-Length: 0\n< Connection: keep-alive\n< Location: https://ol2015.capture.litmuscdn.com/87bf47f2-600e-40eb-8ccb-c9649f17644d/results/ol2015-vertical-allowed.png\n< Strict-Transport-Security: max-age=3600;\n<", "language": "shell" } ] } [/block] 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: [block:code] { "codes": [ { "code": "<html>\n<body>\n <img src=\"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full\">\n</body>", "language": "html" } ] } [/block]
{"__v":0,"_id":"565ff306649b951900c8988a","api":{"auth":"required","examples":{"codes":[{"name":"cURL (key)","code":"curl -X \"POST\" \"https://instant-api.litmus.com/v1/emails\" \\\n  -H \"Content-Type: application/json\" \\\n  -u \"$API_KEY:\" \\\n  -d \"{\\\"plain_text\\\":\\\"Hello World\\\"}\" -v","language":"curl"},{"code":"$ curl -X \"POST\" \"https://instant-api.litmus.com/v1/emails\" \\\n       -H \"Content-Type: application/json\" \\\n       -H \"Authorization: Bearer $TOKEN\"\\\n       -d \"{\\\"plain_text\\\":\\\"Hello World\\\"}\" -v","language":"curl","name":"cURL (OAuth)"},{"name":"Ruby (key)","language":"ruby","code":"Litmus::Instant.api_key = ENV[\"API_KEY\"]\nLitmus::Instant.create_email(plain_text: \"Hello World\")\n# => {\"email_guid\"=>\"ce6ba90f-cf28-4772-ab09-30a1d48a5e12\"}"},{"name":"Ruby (OAuth)","language":"ruby","code":"api_client = Litmus::Instant::Client.new(oauth_token: user_oauth_token)\napi_client.create_email(plain_text: \"Hello World\")\n# => {\"email_guid\"=>\"ce6ba90f-cf28-4772-ab09-30a1d48a5e12\"}"}]},"params":[{"_id":"565ff306649b951900c89892","default":"","desc":"Quotes within the HTML must be escaped appropriately","name":"html_text","ref":"","required":false,"type":"string","in":"body"},{"_id":"565ff306649b951900c89891","default":"","desc":"","name":"plain_text","ref":"","required":false,"type":"string","in":"body"},{"_id":"565ff306649b951900c89890","default":"","desc":"","name":"subject","ref":"","required":false,"type":"string","in":"body"},{"_id":"565ff306649b951900c8988f","default":"","desc":"","name":"from_address","ref":"","required":false,"type":"string","in":"body"},{"_id":"565ff306649b951900c8988e","default":"","desc":"","name":"from_display_name","ref":"","required":false,"type":"string","in":"body"},{"_id":"565ff306649b951900c8988d","default":"","desc":"This field provides an alternative approach to defining the email and so is only valid in the absence of all the fields above","name":"raw_source","ref":"","required":false,"type":"string","in":"body"},{"_id":"565ff306649b951900c8988c","default":"","desc":"A unique identifier for your end users. When provided, we use this to partition your usage data. See [Identifying End Users](doc:identifying-end-users).","name":"end_user_id","ref":"","required":false,"type":"string","in":"body"},{"_id":"565ff306649b951900c8988b","default":"","desc":"An array of capture capture configurations as JSON objects<br>This allows pre-requesting previews that should be captured as soon as possible. This can be a useful performance optimisation. See the dedicated [pre-request](doc:pre-request-a-set-of-previews-before-download) method for further detail on format.","name":"configurations","ref":"","required":false,"type":"array_object","in":"body"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"email_guid\": \"ce6ba90f-cf28-4772-ab09-30a1d48a5e12\"\n}","name":""}]},"settings":"565ff34fb182df0d00d4e467","url":"/emails"},"body":"This method expects to receive a JSON object describing an email’s content and metadata and, in exchange, returns an `email_guid` required to capture previews of it.\n\nWe intend these objects to be treated as lightweight. Once uploaded, emails can't be modified. Obtain a new `email_guid` each time changes need to be reflected.\n\nThe uploaded email has a limited lifespan. As a result, a new `email_guid` should be obtained before requesting new previews if more than a day has passed since the last upload.\n\nAt least one of `html_text`, `plain_text`, `raw_source` must be provided.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Errors\",\n    \"0-0\": \"`400` Bad Request\",\n    \"1-0\": \"`401` Unauthorized\"\n  },\n  \"cols\": 1,\n  \"rows\": 2\n}\n[/block]\n| JSON response body attributes | Description   |\n| -------------------           | ------------- |\n| `email_guid`                  | A unique identifier for the uploaded email required to requests captures. |\n| `end_user_id`                   | *optional* <br><br> Confirmation if an `end_user_id` was provided in the request. |\n| `configurations`             | *optional* <br><br> Confirmation if `configurations` was provided in the request. |","category":"565f29797f93280d0052cf03","createdAt":"2015-12-03T07:45:10.238Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":1,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"create-an-email","sync_unique":"","title":"Create an email","type":"post","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

postCreate an email


Body Params

html_text:
string
Quotes within the HTML must be escaped appropriately
plain_text:
string
subject:
string
from_address:
string
from_display_name:
string
raw_source:
string
This field provides an alternative approach to defining the email and so is only valid in the absence of all the fields above
end_user_id:
string
A unique identifier for your end users. When provided, we use this to partition your usage data. See [Identifying End Users](doc:identifying-end-users).
configurations:
array of objects
An array of capture capture configurations as JSON objects<br>This allows pre-requesting previews that should be captured as soon as possible. This can be a useful performance optimisation. See the dedicated [pre-request](doc:pre-request-a-set-of-previews-before-download) method for further detail on format.
This method expects to receive a JSON object describing an email’s content and metadata and, in exchange, returns an `email_guid` required to capture previews of it. We intend these objects to be treated as lightweight. Once uploaded, emails can't be modified. Obtain a new `email_guid` each time changes need to be reflected. The uploaded email has a limited lifespan. As a result, a new `email_guid` should be obtained before requesting new previews if more than a day has passed since the last upload. At least one of `html_text`, `plain_text`, `raw_source` must be provided. [block:parameters] { "data": { "h-0": "Errors", "0-0": "`400` Bad Request", "1-0": "`401` Unauthorized" }, "cols": 1, "rows": 2 } [/block] | JSON response body attributes | Description | | ------------------- | ------------- | | `email_guid` | A unique identifier for the uploaded email required to requests captures. | | `end_user_id` | *optional* <br><br> Confirmation if an `end_user_id` was provided in the request. | | `configurations` | *optional* <br><br> Confirmation if `configurations` was provided in the request. |

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This method expects to receive a JSON object describing an email’s content and metadata and, in exchange, returns an `email_guid` required to capture previews of it. We intend these objects to be treated as lightweight. Once uploaded, emails can't be modified. Obtain a new `email_guid` each time changes need to be reflected. The uploaded email has a limited lifespan. As a result, a new `email_guid` should be obtained before requesting new previews if more than a day has passed since the last upload. At least one of `html_text`, `plain_text`, `raw_source` must be provided. [block:parameters] { "data": { "h-0": "Errors", "0-0": "`400` Bad Request", "1-0": "`401` Unauthorized" }, "cols": 1, "rows": 2 } [/block] | JSON response body attributes | Description | | ------------------- | ------------- | | `email_guid` | A unique identifier for the uploaded email required to requests captures. | | `end_user_id` | *optional* <br><br> Confirmation if an `end_user_id` was provided in the request. | | `configurations` | *optional* <br><br> Confirmation if `configurations` was provided in the request. |
{"__v":4,"_id":"565ff46eb182df0d00d4e469","api":{"auth":"never","examples":{"codes":[{"language":"curl","code":"curl -X \"GET\" \"https://instant-api.litmus.com/v1/clients\"","name":""},{"language":"ruby","code":"Litmus::Instant.clients\n# => [\"ANDROID4\",\n#     \"ANDROIDGMAILAPP\",\n#     \"AOLONLINE\",\n#     \"APPMAIL8\",\n#     ...clipped..."}]},"params":[],"results":{"codes":[{"status":200,"language":"json","code":"[\n  \"OL2000\",\n  \"OL2002\",\n  \"OL2003\",\n  \"OL2007\",\n  \"OL2010\",\n\n  ...clipped...\n\n  \"NOTES9\",\n  \"OFFICE365\",\n  \"FFOFFICE365\",\n  \"CHROMEOFFICE365\",\n  \"ANDROIDGMAILAPP\"\n]","name":""}]},"settings":"565ff34fb182df0d00d4e467","url":"/clients"},"body":"Returns a JSON array of email client names.","category":"565f29797f93280d0052cf03","createdAt":"2015-12-03T07:51:10.926Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":2,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"list-supported-email-clients","sync_unique":"","title":"List supported email clients","type":"get","updates":["57356068afab4417007239f4"],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getList supported email clients


Returns a JSON array of email client names.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Returns a JSON array of email client names.
{"__v":3,"_id":"565ff4eade5dc50d00acff50","api":{"auth":"never","examples":{"codes":[{"language":"curl","code":"curl -X \"GET\" \"https://instant-api.litmus.com/v1/clients/configurations\"","name":""},{"language":"ruby","code":"> Litmus::Instant.client_configurations\n# => {\"OL2000\"=>{\"orientation_options\"=>[\"vertical\"], \"images_options\"=>[\"allowed\"]},\n#     \"OL2002\"=>{\"orientation_options\"=>[\"vertical\"], \"images_options\"=>[\"allowed\"]},\n#     \"OL2003\"=>{\"orientation_options\"=>[\"vertical\"], \"images_options\"=>[\"allowed\", \"blocked\"]},\n#     ... clipped ... "}]},"params":[],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"OL2000\": {\n    \"orientation_options\": [\n      \"vertical\"\n    ],\n    \"images_options\": [\n      \"allowed\"\n    ]\n  },\n  \"OL2002\": {\n    \"orientation_options\": [\n      \"vertical\"\n    ],\n    \"images_options\": [\n      \"allowed\"\n    ]\n  },\n  \"OL2003\": {\n    \"orientation_options\": [\n      \"vertical\"\n    ],\n    \"images_options\": [\n      \"allowed\",\n      \"blocked\"\n    ]\n  }\n\n  ... clipped ...\n\n}\n","name":""}]},"settings":"565ff34fb182df0d00d4e467","url":"/clients/configurations"},"body":"Returns a JSON hash detailing available options for each client.","category":"565f29797f93280d0052cf03","createdAt":"2015-12-03T07:53:14.790Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":3,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"list-supported-email-client-configurations","sync_unique":"","title":"List supported email client configurations","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getList supported email client configurations


Returns a JSON hash detailing available options for each client.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Returns a JSON hash detailing available options for each client.
{"__v":1,"_id":"565ff5f5bca87d0d006bc7ca","api":{"auth":"never","examples":{"codes":[{"language":"curl","code":"curl -X \"GET\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015\" -v","name":""},{"language":"ruby","code":"Litmus::Instant.get_preview(\"7179b074-2b1e-455e-bf48-8068eb42d7ca\", \"OL2010\", images: \"blocked\")\n# => {\"full_url\"=>\"https://ol2010.capture.litmuscdn.com/7179b074-2b1e-455e-bf48-8068eb42d7ca/results/ol2010-vertical-blocked-1366.png\",\n# \"thumb_url\"=>\"https://ol2010.capture.litmuscdn.com/7179b074-2b1e-455e-bf48-8068eb42d7ca/results/ol2010-vertical-blocked-1366-thumb.png\",\n# \"thumb450_url\"=>\"https://ol2010.capture.litmuscdn.com/7179b074-2b1e-455e-bf48-068eb42d7ca/results/ol2010-vertical-blocked-1366-thumb450.png\"}"}]},"params":[{"_id":"565ff5f5bca87d0d006bc7cc","default":"","desc":"Provided on [email creation](doc:create-an-email)","name":"email_guid","ref":"","required":true,"type":"string","in":"path"},{"_id":"565ff5f5bca87d0d006bc7cb","default":"","desc":"An identifier present in [available clients](doc:list-supported-email-clients)","name":"client","ref":"","required":true,"type":"string","in":"path"},{"_id":"56c1f178f57d5b0d00569f68","default":"allowed","desc":"One of `allowed`, `blocked`<br> Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client","name":"images","ref":"","required":false,"type":"string","in":"query"},{"_id":"56c1f178f57d5b0d00569f67","default":"vertical","desc":"One of `horizontal`, `vertical`<br> Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client","name":"orientation","ref":"","required":false,"type":"string","in":"query"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"full_url\": \"https://OL2015.capture.litmuscdn.com/87bf47f2-600e-40eb-8ccb-c9649f17644d/results/ol2015-vertical-allowed-1366.png\",\n  \"thumb_url\": \"https://OL2015.capture.litmuscdn.com/87bf47f2-600e-40eb-8ccb-c9649f17644d/results/ol2015-vertical-allowed-1366-thumb.png\",\n  \"thumb450_url\": \"https://OL2015.capture.litmuscdn.com/87bf47f2-600e-40eb-8ccb-c9649f17644d/results/ol2015-vertical-allowed-1366-thumb450.png\"\n}","name":""}]},"settings":"565ff34fb182df0d00d4e467","url":"/emails/:email_guid/previews/:client"},"body":"This triggers the capture of a preview. Once the capture is complete, the content of the JSON response body will contain URLs for each of the image sizes available. A second request will be needed to obtain actual image data.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This method typically typically blocks for about 6 seconds when a new preview must be captured\"\n}\n[/block]\nThe URLs returned will be on subdomains of `litmuscdn.com` eg `https://ol2015.capture.litmuscdn.com/87bf47f2-600e-40eb-8ccb-c9649f17644d/results/ol2015-vertical-allowed.png`. GET requests to these URLs will return redirects to the current location of the image asset.\n\nSubsequent requests for a capture that's previously been made will result in a redirect to the cached result of the previous capture. To trigger a new capture a new `email_guid` must be obtained. Only the initial capture is a billable event, not GETs of the cached preview.\n\n| Errors  | \n| ----- |\n| `400` Bad Request |\n| `404` Not Found - when the `email_guid` is not found. This can occur when email assets or stored captures have expired having exceeded their [lifetime](#section-lifetimes) |\n| `500` Internal Server Error - in particular when email clients fail unexpectedly |\n| `503` Service Unavailable |\n| `504` Timeout - this can occur when an email client takes too long to respond |\n\nDifferent configurations of the same client are considered as separate captures and billed as such. For instance the following would be considered three separate captures:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X \\\"GET\\\" \\\"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/IPAD?images=allowed&orientation=vertical\\\"\\n$ curl -X \\\"GET\\\" \\\"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/IPAD?images=blocked&orientation=vertical\\\"\\n$ curl -X \\\"GET\\\" \\\"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/IPAD?images=blocked&orientation=horizontal\\\"\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]","category":"565f29797f93280d0052cf03","createdAt":"2015-12-03T07:57:41.243Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":4,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"request-a-preview","sync_unique":"","title":"Request a preview","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getRequest a preview


Path Params

email_guid:
required
string
Provided on [email creation](doc:create-an-email)
client:
required
string
An identifier present in [available clients](doc:list-supported-email-clients)

Query Params

images:
stringallowed
One of `allowed`, `blocked`<br> Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client
orientation:
stringvertical
One of `horizontal`, `vertical`<br> Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client
This triggers the capture of a preview. Once the capture is complete, the content of the JSON response body will contain URLs for each of the image sizes available. A second request will be needed to obtain actual image data. [block:callout] { "type": "warning", "body": "This method typically typically blocks for about 6 seconds when a new preview must be captured" } [/block] The URLs returned will be on subdomains of `litmuscdn.com` eg `https://ol2015.capture.litmuscdn.com/87bf47f2-600e-40eb-8ccb-c9649f17644d/results/ol2015-vertical-allowed.png`. GET requests to these URLs will return redirects to the current location of the image asset. Subsequent requests for a capture that's previously been made will result in a redirect to the cached result of the previous capture. To trigger a new capture a new `email_guid` must be obtained. Only the initial capture is a billable event, not GETs of the cached preview. | Errors | | ----- | | `400` Bad Request | | `404` Not Found - when the `email_guid` is not found. This can occur when email assets or stored captures have expired having exceeded their [lifetime](#section-lifetimes) | | `500` Internal Server Error - in particular when email clients fail unexpectedly | | `503` Service Unavailable | | `504` Timeout - this can occur when an email client takes too long to respond | Different configurations of the same client are considered as separate captures and billed as such. For instance the following would be considered three separate captures: [block:code] { "codes": [ { "code": "$ curl -X \"GET\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/IPAD?images=allowed&orientation=vertical\"\n$ curl -X \"GET\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/IPAD?images=blocked&orientation=vertical\"\n$ curl -X \"GET\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/IPAD?images=blocked&orientation=horizontal\"", "language": "shell" } ] } [/block]

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This triggers the capture of a preview. Once the capture is complete, the content of the JSON response body will contain URLs for each of the image sizes available. A second request will be needed to obtain actual image data. [block:callout] { "type": "warning", "body": "This method typically typically blocks for about 6 seconds when a new preview must be captured" } [/block] The URLs returned will be on subdomains of `litmuscdn.com` eg `https://ol2015.capture.litmuscdn.com/87bf47f2-600e-40eb-8ccb-c9649f17644d/results/ol2015-vertical-allowed.png`. GET requests to these URLs will return redirects to the current location of the image asset. Subsequent requests for a capture that's previously been made will result in a redirect to the cached result of the previous capture. To trigger a new capture a new `email_guid` must be obtained. Only the initial capture is a billable event, not GETs of the cached preview. | Errors | | ----- | | `400` Bad Request | | `404` Not Found - when the `email_guid` is not found. This can occur when email assets or stored captures have expired having exceeded their [lifetime](#section-lifetimes) | | `500` Internal Server Error - in particular when email clients fail unexpectedly | | `503` Service Unavailable | | `504` Timeout - this can occur when an email client takes too long to respond | Different configurations of the same client are considered as separate captures and billed as such. For instance the following would be considered three separate captures: [block:code] { "codes": [ { "code": "$ curl -X \"GET\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/IPAD?images=allowed&orientation=vertical\"\n$ curl -X \"GET\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/IPAD?images=blocked&orientation=vertical\"\n$ curl -X \"GET\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/IPAD?images=blocked&orientation=horizontal\"", "language": "shell" } ] } [/block]
{"__v":0,"_id":"565ff6eb6c2a8d0d002765bd","api":{"auth":"never","examples":{"codes":[{"language":"html","code":"<img src=\"https://instant-api.litmus.com/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full\">"},{"code":"curl -X \"GET\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full\" -v\n*   Trying 216.126.40.158...\n* Connected to instant-api.litmus.com (216.126.40.158) port 443 (#0)\n* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384\n* Server certificate: instant-api.litmus.com\n* Server certificate: RapidSSL SHA256 CA - G4\n* Server certificate: GeoTrust Primary Certification Authority - G3\n> GET /v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full HTTP/1.1\n> Host: instant-api.litmus.com\n> User-Agent: curl/7.43.0\n> Accept: */*\n>\n< HTTP/1.1 301 Moved Permanently\n< Server: nginx\n< Date: Tue, 16 Feb 2016 09:53:39 GMT\n< Content-Type: application/json;charset=utf-8\n< Content-Length: 0\n< Connection: keep-alive\n< Location: https://OL2015.capture.litmuscdn.com/87bf47f2-600e-40eb-8ccb-c9649f17644d/results/ol2015-vertical-allowed-1366.png\n< Strict-Transport-Security: max-age=3600; includeSubdomains; preload\n< X-Frame-Options: DENY\n< X-Content-Type-Options: nosniff\n<","language":"curl","name":"cURL - success"},{"code":"# failure with default fallback behaviour\n\ncurl -X \"GET\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full\" -v\n*   Trying 216.126.40.158...\n* Connected to instant-api.litmus.com (216.126.40.158) port 443 (#0)\n* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384\n* Server certificate: instant-api.litmus.com\n* Server certificate: RapidSSL SHA256 CA - G4\n* Server certificate: GeoTrust Primary Certification Authority - G3\n> GET /v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full HTTP/1.1\n> Host: instant-api.litmus.com\n> User-Agent: curl/7.43.0\n> Accept: */*\n>\n< HTTP/1.1 302 Moved Temporarily\n< Server: nginx\n< Date: Tue, 16 Feb 2016 09:57:24 GMT\n< Content-Type: application/json;charset=utf-8\n< Content-Length: 0\n< Connection: keep-alive\n< X-Litmus-Error: 500 Server error\n< Location: https://instant-api.litmuscdn.com/images/placeholder-full.png\n< Strict-Transport-Security: max-age=3600; includeSubdomains; preload\n< X-Frame-Options: DENY\n< X-Content-Type-Options: nosniff\n<","language":"curl","name":"cURL - fallback"},{"code":"# failure with fallback disabled\n\ncurl -X \"GET\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full?fallback=false\" -v\n*   Trying 216.126.40.158...\n* Connected to instant-api.litmus.com (216.126.40.158) port 443 (#0)\n* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384\n* Server certificate: instant-api.litmus.com\n* Server certificate: RapidSSL SHA256 CA - G4\n* Server certificate: GeoTrust Primary Certification Authority - G3\n> GET /v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/OL2015/full?fallback=false HTTP/1.1\n> Host: instant-api.litmus.com\n> User-Agent: curl/7.43.0\n> Accept: */*\n>\n< HTTP/1.1 500 Internal Server Error\n< Server: nginx\n< Date: Tue, 16 Feb 2016 10:02:09 GMT\n< Content-Type: application/json;charset=utf-8\n< Content-Length: 496\n< Connection: keep-alive\n<\n{\n  \"status\": 500,\n  \"title\": \"Server error\",\n  \"description\": \"An unknown error occurred. We know this is frustrating, but we ran into a problem and we don’t yet have a way to categorize and report it to you as this type of error hasn’t occurred before. This type of error is logged on our end, but if you see this while in development, please do reach out to us at resellers@litmus.com with details of your request and we’ll have a Support Engineer get back to you as soon as possible.\"\n}","language":"curl","name":"cURL - no fallback"},{"language":"ruby","code":"@preview_url = Litmus::Instant.preview_image_url(email_guid, \"OL2010\")\n# => \"https://OL2010.instant-api.litmus.com/v1/emails/755d1f9f-ad28-460f-8e45-632e0eceab32/previews/OL2010/full\"\n# Which could be used in a view template eg\n# <%= image_tag @preview_url %>"}]},"params":[{"_id":"565ff6eb6c2a8d0d002765c4","default":"","desc":"Provided on [email creation](doc:create-an-email)","name":"email_guid","ref":"","required":true,"type":"string","in":"path"},{"_id":"565ff6eb6c2a8d0d002765c3","default":"","desc":"An identifier present in [available clients](doc:list-supported-email-clients)","name":"client","ref":"","required":true,"type":"string","in":"path"},{"_id":"565ff6eb6c2a8d0d002765c2","default":"","desc":"One of `full`,`thumb450`,`thumb`","name":"capture_size","ref":"","required":true,"type":"string","in":"path"},{"_id":"565ff6eb6c2a8d0d002765c1","default":"allowed","desc":"One of `allowed`, `blocked`<br>Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client","name":"images","ref":"","required":false,"type":"string","in":"query"},{"_id":"565ff6eb6c2a8d0d002765c0","default":"vertical","desc":"One of `horizontal`, `vertical`<br>Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client","name":"orientation","ref":"","required":false,"type":"string","in":"query"},{"_id":"565ff6eb6c2a8d0d002765bf","default":"true","desc":"When fallback is enabled capture errors result in a redirect to a fallback image rather than in a failed response.<br>An error is indicated by the presence of the custom header **X-Litmus-Error**. Errors relating to the request (ie 400 errors) are returned normally and do not result in the fallback redirect.","name":"fallback","ref":"","required":false,"type":"boolean","in":"query"},{"_id":"565ff6eb6c2a8d0d002765be","default":"","desc":"A custom fallback image to display in case of errors<br>This must be an absolute URL, URL encoded and have a recognizable image extension. Query parameters are not supported. The image should be accessible publicly without the need for authentication.<br>defaults to the following fallback images: [full](https://instant-api.litmuscdn.com/images/placeholder-full.png), [thumb450](https://instant-api.litmuscdn.com/images/placeholder-thumb450.png), [thumb](https://instant-api.litmuscdn.com/images/placeholder-thumb.png)","name":"fallback_url","ref":"","required":false,"type":"string","in":"query"}],"results":{"codes":[{"status":301,"language":"text","code":""}]},"settings":"565ff34fb182df0d00d4e467","url":"/emails/:email_guid/previews/:client/:capture_size"},"body":"This method returns a redirect to the preview image or an (optional) redirect to a fallback image. In all other respects it behaves identically to [requesting a preview](#request-a-preview) above.\n\nThis makes requesting and displaying a capture in your user interface as simple as including any other remote image. For example, for a web application, you would place the constructed URL in the `src` attribute of an `<img>` tag (see [example](instant-api#section-example)).\n\nIt can also be used as a convenience when downloading captures by simply configuring your HTTP client to follow redirects, cutting out the need to parse JSON and make a second request.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This method typically typically blocks for about 6 seconds when a new preview must be captured\"\n}\n[/block]\n|Errors|\n|----|\n| `400` Bad Request |\n| `404` Not Found - when the `email_guid` is not found. This can occur when email assets or stored captures have expired having exceeded their [lifetime](instant-api#section-lifetimes) |\n| `500` Internal Server Error - in particular when email clients fail unexpectedly |\n| `503` Service Unavailable |\n| `504` Timeout - this can occur when an email client takes too long to respond |\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Some failure cases can take significantly longer to return than the typical 6 seconds for a successful case.\"\n}\n[/block]","category":"565f29797f93280d0052cf03","createdAt":"2015-12-03T08:01:47.794Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":5,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"directly-request-or-embed-a-preview-image","sync_unique":"","title":"Directly request a preview image","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getDirectly request a preview image


Path Params

email_guid:
required
string
Provided on [email creation](doc:create-an-email)
client:
required
string
An identifier present in [available clients](doc:list-supported-email-clients)
capture_size:
required
string
One of `full`,`thumb450`,`thumb`

Query Params

images:
stringallowed
One of `allowed`, `blocked`<br>Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client
orientation:
stringvertical
One of `horizontal`, `vertical`<br>Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client
fallback:
booleantrue
When fallback is enabled capture errors result in a redirect to a fallback image rather than in a failed response.<br>An error is indicated by the presence of the custom header **X-Litmus-Error**. Errors relating to the request (ie 400 errors) are returned normally and do not result in the fallback redirect.
fallback_url:
string
A custom fallback image to display in case of errors<br>This must be an absolute URL, URL encoded and have a recognizable image extension. Query parameters are not supported. The image should be accessible publicly without the need for authentication.<br>defaults to the following fallback images: [full](https://instant-api.litmuscdn.com/images/placeholder-full.png), [thumb450](https://instant-api.litmuscdn.com/images/placeholder-thumb450.png), [thumb](https://instant-api.litmuscdn.com/images/placeholder-thumb.png)
This method returns a redirect to the preview image or an (optional) redirect to a fallback image. In all other respects it behaves identically to [requesting a preview](#request-a-preview) above. This makes requesting and displaying a capture in your user interface as simple as including any other remote image. For example, for a web application, you would place the constructed URL in the `src` attribute of an `<img>` tag (see [example](instant-api#section-example)). It can also be used as a convenience when downloading captures by simply configuring your HTTP client to follow redirects, cutting out the need to parse JSON and make a second request. [block:callout] { "type": "warning", "body": "This method typically typically blocks for about 6 seconds when a new preview must be captured" } [/block] |Errors| |----| | `400` Bad Request | | `404` Not Found - when the `email_guid` is not found. This can occur when email assets or stored captures have expired having exceeded their [lifetime](instant-api#section-lifetimes) | | `500` Internal Server Error - in particular when email clients fail unexpectedly | | `503` Service Unavailable | | `504` Timeout - this can occur when an email client takes too long to respond | [block:callout] { "type": "warning", "body": "Some failure cases can take significantly longer to return than the typical 6 seconds for a successful case." } [/block]

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples



This method returns a redirect to the preview image or an (optional) redirect to a fallback image. In all other respects it behaves identically to [requesting a preview](#request-a-preview) above. This makes requesting and displaying a capture in your user interface as simple as including any other remote image. For example, for a web application, you would place the constructed URL in the `src` attribute of an `<img>` tag (see [example](instant-api#section-example)). It can also be used as a convenience when downloading captures by simply configuring your HTTP client to follow redirects, cutting out the need to parse JSON and make a second request. [block:callout] { "type": "warning", "body": "This method typically typically blocks for about 6 seconds when a new preview must be captured" } [/block] |Errors| |----| | `400` Bad Request | | `404` Not Found - when the `email_guid` is not found. This can occur when email assets or stored captures have expired having exceeded their [lifetime](instant-api#section-lifetimes) | | `500` Internal Server Error - in particular when email clients fail unexpectedly | | `503` Service Unavailable | | `504` Timeout - this can occur when an email client takes too long to respond | [block:callout] { "type": "warning", "body": "Some failure cases can take significantly longer to return than the typical 6 seconds for a successful case." } [/block]
{"__v":0,"_id":"565ffb476c2a8d0d002765c6","api":{"auth":"never","examples":{"codes":[{"language":"curl","code":"curl -X \"POST\" \"https://instant-api.litmus.com/v1/emails/87bf47f2-600e-40eb-8ccb-c9649f17644d/previews/prefetch\" \\\n-H \"Content-Type: application/json\" -v \\\n-d '{\"configurations\":[\n  {\"client\":\"OL2010\"},\n  {\"client\":\"OL2010\", \"images\":\"blocked\"},\n  {\"client\":\"IPAD\"}\n  ]}'\n","name":""},{"language":"ruby","code":"Litmus::Instant.prefetch_previews(\n  email_guid, [\n    { client: \"OL2010\" },\n    { client: \"OL2013\", images: \"blocked\" }\n  ]\n)\n# => {\"configurations\"=>\n#     [{\"orientation\"=>\"vertical\", \"images\"=>\"allowed\", \"client\"=>\"OL2010\"},\n#      {\"orientation\"=>\"vertical\", \"images\"=>\"blocked\", \"client\"=>\"OL2013\"}]}"}]},"params":[{"_id":"565ffb476c2a8d0d002765c8","default":"","desc":"Provided on [email creation](doc:create-an-email)","name":"email_guid","ref":"","required":true,"type":"string","in":"path"},{"_id":"565ffb476c2a8d0d002765c7","default":"","desc":"An array of capture capture configurations as JSON objects, see table below","name":"configurations","ref":"","required":true,"type":"array_object","in":"body"}],"results":{"codes":[{"status":202,"language":"json","code":"{\n  \"configurations\": [\n    {\n      \"orientation\": \"vertical\",\n      \"images\": \"allowed\",\n      \"client\": \"OL2010\"\n    },\n    {\n      \"orientation\": \"vertical\",\n      \"images\": \"blocked\",\n      \"client\": \"OL2010\"\n    },\n    {\n      \"orientation\": \"vertical\",\n      \"images\": \"allowed\",\n      \"client\": \"IPAD\"\n    }\n  ]\n}","name":""}]},"settings":"565ff34fb182df0d00d4e467","url":"/emails/:email_guid/previews/prefetch"},"body":"This method is provided as an optional performance enhancement, typically useful before embedding a set of previews within a browser, where connection limits might otherwise delay the start of capture of some previews. For more detail on when this might be useful see [performance](doc:performance).\n\nThe method does not block while capture occurs, a `202 Accepted` response is returned immediately.\n\nNote that should capture failure occur for a preview, it will only be discovered when the preview is later requested. Request errors, for instance attempting to prefetch an invalid client, will result in a `400 Bad Request` however.\n\n| Capture configuration        | Description   |\n| -------------------          | ------------- |\n| `client`                     | *required* <br><br> an identifier present in [available clients](doc:list-supported-email-clients)  |\n| `images`                     | *optional* <br><br> one of `allowed` (default), `blocked` <br><br> Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client |\n| `orientation`                | *optional* <br><br> one of `horizontal`, `vertical` (default) <br><br> Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client |\n\n| Errors |\n| ----- |\n| `400` Bad Request - if the request body is malformed, or if any requested capture configuration is invalid |\n| `404` Not Found - when the `email_guid` is not found. This can occur when email assets or stored captures have expired having exceeded their [lifetime](instant-api#section-lifetimes) |\n\n| JSON response body attributes | Description   |\n| -------------------           | ------------- |\n| `configurations`              | Confirmation of capture configurations that will be prefetched. |","category":"565f29797f93280d0052cf03","createdAt":"2015-12-03T08:20:23.038Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":6,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"pre-request-a-set-of-previews-before-download","sync_unique":"","title":"Pre-request previews before download","type":"post","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

postPre-request previews before download


Path Params

email_guid:
required
string
Provided on [email creation](doc:create-an-email)

Body Params

configurations:
required
array of objects
An array of capture capture configurations as JSON objects, see table below
This method is provided as an optional performance enhancement, typically useful before embedding a set of previews within a browser, where connection limits might otherwise delay the start of capture of some previews. For more detail on when this might be useful see [performance](doc:performance). The method does not block while capture occurs, a `202 Accepted` response is returned immediately. Note that should capture failure occur for a preview, it will only be discovered when the preview is later requested. Request errors, for instance attempting to prefetch an invalid client, will result in a `400 Bad Request` however. | Capture configuration | Description | | ------------------- | ------------- | | `client` | *required* <br><br> an identifier present in [available clients](doc:list-supported-email-clients) | | `images` | *optional* <br><br> one of `allowed` (default), `blocked` <br><br> Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client | | `orientation` | *optional* <br><br> one of `horizontal`, `vertical` (default) <br><br> Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client | | Errors | | ----- | | `400` Bad Request - if the request body is malformed, or if any requested capture configuration is invalid | | `404` Not Found - when the `email_guid` is not found. This can occur when email assets or stored captures have expired having exceeded their [lifetime](instant-api#section-lifetimes) | | JSON response body attributes | Description | | ------------------- | ------------- | | `configurations` | Confirmation of capture configurations that will be prefetched. |

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This method is provided as an optional performance enhancement, typically useful before embedding a set of previews within a browser, where connection limits might otherwise delay the start of capture of some previews. For more detail on when this might be useful see [performance](doc:performance). The method does not block while capture occurs, a `202 Accepted` response is returned immediately. Note that should capture failure occur for a preview, it will only be discovered when the preview is later requested. Request errors, for instance attempting to prefetch an invalid client, will result in a `400 Bad Request` however. | Capture configuration | Description | | ------------------- | ------------- | | `client` | *required* <br><br> an identifier present in [available clients](doc:list-supported-email-clients) | | `images` | *optional* <br><br> one of `allowed` (default), `blocked` <br><br> Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client | | `orientation` | *optional* <br><br> one of `horizontal`, `vertical` (default) <br><br> Refer to [configurations](doc:list-supported-email-client-configurations) to determine what's valid for for each client | | Errors | | ----- | | `400` Bad Request - if the request body is malformed, or if any requested capture configuration is invalid | | `404` Not Found - when the `email_guid` is not found. This can occur when email assets or stored captures have expired having exceeded their [lifetime](instant-api#section-lifetimes) | | JSON response body attributes | Description | | ------------------- | ------------- | | `configurations` | Confirmation of capture configurations that will be prefetched. |
{"__v":5,"_id":"565f2d1e649b951900c89729","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"In earlier API versions \\\"End User Identifier\\\" was referred to as \\\"User GUID\\\"\"\n}\n[/block]\nYou may find it useful to partition your API usage data by your end users. If you are offering an unlimited previews facility to your users, we need to be able to identify the number of unique users of your application.\n\nTo do this, you can associate emails (and, as a consequence, any previews), with a unique identifier of your choosing—an end_user_id.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The identifier used must be unique to that user. The identifier should be stored in a unique field within your database and should not change for the life of that user’s account.\"\n}\n[/block]\nThis information is never shared with anyone, not even your user.  It will only be shown in your billing reports and confirmed in the response to a POST request that provides it.\n\nDo not use a hash of your user’s details unless you can ensure that this will remain unchanged and unique for that user. You'll 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.\n\n[Standard UUIDs](http://tools.ietf.org/html/rfc4122) make a good choice for this field, but any uniquely identifying string of 64 characters or less may be used.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# An example of identifying an end user when POSTing a new email\\n\\n$ curl -X \\\"POST\\\" \\\"https://instant-api.litmus.com/v1/emails\\\" \\\\\\n  -H \\\"Content-Type: application/json\\\" \\\\\\n  -u \\\"$API_KEY:\\\" \\\\\\n  -d \\\"{\\\\\\\"plain_text\\\\\\\":\\\\\\\"Hello World\\\\\\\",\\\\\\\"end_user_id\\\\\\\":\\\\\\\"a5725576-07d5-4e28-9e6c-2f1851825c14\\\\\\\"}\\\" -v\\n> POST /v1/emails HTTP/1.1\\n> User-Agent: curl/7.37.1\\n> Host: instant-api.litmus.com\\n> Accept: */*\\n> Content-Type: application/json\\n> Authorization: Basic XXXXXXXXXXXXXXXXXXXXXX\\n> Content-Length: 28\\n>\\n< HTTP/1.1 200 OK\\n< Server: nginx\\n< Date: Thu, 16 Jul 2015 12:35:02 GMT\\n< Content-Type: application/json;charset=utf-8\\n< Content-Length: 58\\n< Connection: keep-alive\\n< Strict-Transport-Security: max-age=3600;\\n<\\n{\\n  \\\"email_guid\\\": \\\"ce6ba90f-cf28-4772-ab09-30a1d48a5e12\\\",\\n  \\\"end_user_id\\\": \\\"a5725576-07d5-4e28-9e6c-2f1851825c14\\\"\\n}\",\n      \"language\": \"curl\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","category":"565f29797f93280d0052cf03","createdAt":"2015-12-02T17:40:46.168Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":7,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"identifying-end-users","sync_unique":"","title":"Identifying End Users","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Identifying End Users


[block:callout] { "type": "info", "body": "In earlier API versions \"End User Identifier\" was referred to as \"User GUID\"" } [/block] You may find it useful to partition your API usage data by your end users. If you are offering an unlimited previews facility to your users, we need to be able to identify the number of unique users of your application. To do this, you can associate emails (and, as a consequence, any previews), with a unique identifier of your choosing—an end_user_id. [block:callout] { "type": "warning", "body": "The identifier used must be unique to that user. The identifier should be stored in a unique field within your database and should not change for the life of that user’s account." } [/block] This information is never shared with anyone, not even your user. It will only be shown in your billing reports and confirmed in the response to a POST request that provides it. Do not use a hash of your user’s details unless you can ensure that this will remain unchanged and unique for that user. You'll 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. [Standard UUIDs](http://tools.ietf.org/html/rfc4122) make a good choice for this field, but any uniquely identifying string of 64 characters or less may be used. [block:code] { "codes": [ { "code": "# An example of identifying an end user when POSTing a new email\n\n$ curl -X \"POST\" \"https://instant-api.litmus.com/v1/emails\" \\\n -H \"Content-Type: application/json\" \\\n -u \"$API_KEY:\" \\\n -d \"{\\\"plain_text\\\":\\\"Hello World\\\",\\\"end_user_id\\\":\\\"a5725576-07d5-4e28-9e6c-2f1851825c14\\\"}\" -v\n> POST /v1/emails HTTP/1.1\n> User-Agent: curl/7.37.1\n> Host: instant-api.litmus.com\n> Accept: */*\n> Content-Type: application/json\n> Authorization: Basic XXXXXXXXXXXXXXXXXXXXXX\n> Content-Length: 28\n>\n< HTTP/1.1 200 OK\n< Server: nginx\n< Date: Thu, 16 Jul 2015 12:35:02 GMT\n< Content-Type: application/json;charset=utf-8\n< Content-Length: 58\n< Connection: keep-alive\n< Strict-Transport-Security: max-age=3600;\n<\n{\n \"email_guid\": \"ce6ba90f-cf28-4772-ab09-30a1d48a5e12\",\n \"end_user_id\": \"a5725576-07d5-4e28-9e6c-2f1851825c14\"\n}", "language": "curl" } ], "sidebar": true } [/block]
[block:callout] { "type": "info", "body": "In earlier API versions \"End User Identifier\" was referred to as \"User GUID\"" } [/block] You may find it useful to partition your API usage data by your end users. If you are offering an unlimited previews facility to your users, we need to be able to identify the number of unique users of your application. To do this, you can associate emails (and, as a consequence, any previews), with a unique identifier of your choosing—an end_user_id. [block:callout] { "type": "warning", "body": "The identifier used must be unique to that user. The identifier should be stored in a unique field within your database and should not change for the life of that user’s account." } [/block] This information is never shared with anyone, not even your user. It will only be shown in your billing reports and confirmed in the response to a POST request that provides it. Do not use a hash of your user’s details unless you can ensure that this will remain unchanged and unique for that user. You'll 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. [Standard UUIDs](http://tools.ietf.org/html/rfc4122) make a good choice for this field, but any uniquely identifying string of 64 characters or less may be used. [block:code] { "codes": [ { "code": "# An example of identifying an end user when POSTing a new email\n\n$ curl -X \"POST\" \"https://instant-api.litmus.com/v1/emails\" \\\n -H \"Content-Type: application/json\" \\\n -u \"$API_KEY:\" \\\n -d \"{\\\"plain_text\\\":\\\"Hello World\\\",\\\"end_user_id\\\":\\\"a5725576-07d5-4e28-9e6c-2f1851825c14\\\"}\" -v\n> POST /v1/emails HTTP/1.1\n> User-Agent: curl/7.37.1\n> Host: instant-api.litmus.com\n> Accept: */*\n> Content-Type: application/json\n> Authorization: Basic XXXXXXXXXXXXXXXXXXXXXX\n> Content-Length: 28\n>\n< HTTP/1.1 200 OK\n< Server: nginx\n< Date: Thu, 16 Jul 2015 12:35:02 GMT\n< Content-Type: application/json;charset=utf-8\n< Content-Length: 58\n< Connection: keep-alive\n< Strict-Transport-Security: max-age=3600;\n<\n{\n \"email_guid\": \"ce6ba90f-cf28-4772-ab09-30a1d48a5e12\",\n \"end_user_id\": \"a5725576-07d5-4e28-9e6c-2f1851825c14\"\n}", "language": "curl" } ], "sidebar": true } [/block]
{"__v":3,"_id":"565f2d2d0dc99e1900f24bb5","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"### Working with long running requests\n\nTo avoid complexity, the first request for a new preview blocks for a number of seconds until the capture has completed. However, this introduces some complications.\n\nCaptures are only initiated when a request for a preview has been made. If you make your requests in serial and wait for responses before proceeding, then they’ll stack behind each other. This will multiply your overall load time.\n\nRequesting multiple previews in parallel can be used to initiate capture for all desired configurations at once. In this case, your load time will be limited to the longest running query. Alternatively, you could choose to show those ready earlier as soon as they’re available.\n\nAt scale, this could lead to a large number of open waiting connections if these requests are made server-side. We can also run into client-side connection limits in the browser..\n\n\n### Working with browser connection limits\n\n#### Requesting a single preview or two in parallel\n\nIf you’re only requesting a single preview or two in parallel, then you can skip this section on working with browser connection limitations. All common browsers allow this to occur unrestricted.\n\n#### Requesting 3-6 images in parallel\n\nYou can safely ignore this unless you're concerned about the performance of your web application in legacy browsers where per-host connection limits will impact users.\n\nHowever, if you’re concerned about the following browsers, we have a solution:\n\n- **IE6 or IE7** — Maximum connections per host is 2\n- **Opera 9.x** — Maximum connections per host is 4\n- **Safari 3 and 4** — Maximum connections per host is 4\n\nTo remedy this, we allow access to the API assets using [domain sharding](#section-domain-sharding).\n\n#### Requesting 7-10 images in parallel\n\nAt 7 concurrent connections many browsers start to reach per host limits. As above, see [domain sharding](#section-domain-sharding).\n\n#### Requesting 10+ images in parallel\n\nWhen we reach 10 concurrent connections we start to hit all-host connection limits, particularly in Chrome. Domain sharding doesn’t stop our 11th request being queued, so it’s best to [pre-request](#section-pre-request) any images required before embedding.\n\n### Domain sharding\n\nWe allow GET requests against the API at custom subdomains, which allows you to circumvent browser per-host connections limits at the small cost of additional DNS lookups.\n\nFor instance, if the following hit a per-host connection limit:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<img src=\\\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2000/thumb\\\">\\n<img src=\\\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2002/thumb\\\">\\n<img src=\\\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2003/thumb\\\">\\n<img src=\\\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2007/thumb\\\">\\n<img src=\\\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2010/thumb\\\">\\n<img src=\\\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/NOTES9/thumb\\\">\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThe limit could be circumvented with:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<img src=\\\"https://OL2000.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2000/thumb\\\">\\n<img src=\\\"https://OL2002.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2002/thumb\\\">\\n<img src=\\\"https://OL2003.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2003/thumb\\\">\\n<img src=\\\"https://OL2007.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2007/thumb\\\">\\n<img src=\\\"https://OL2010.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2010/thumb\\\">\\n<img src=\\\"https://NOTES9.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/NOTES9/thumb\\\">\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nNote that the choice of subdomain is arbitrary. You only need to ensure that they are distinct. You could equally use:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<img src=\\\"https://1.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2000/thumb\\\">\\n<img src=\\\"https://2.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2002/thumb\\\">\\n<img src=\\\"https://3.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2003/thumb\\\">\\n<img src=\\\"https://4.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2007/thumb\\\">\\n<img src=\\\"https://5.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2010/thumb\\\">\\n<img src=\\\"https://6.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/NOTES9/thumb\\\">\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n### Pre-request\n\nPre-requesting allows for requesting that a capture (or set of captures) is initiated for specified configurations with an immediate (non-blocking) response.\n\nBecause the API guards against duplicate captures, this means that any requests queued due to browser connection limits will yield the preview as soon as the pre-requested capture has completed, rather than initiating then waiting the full duration of capture.\n\nSee the [API method](pre-request-a-set-of-previews-before-download) for further information.\n\n### Managing server-side connections\n\nDownloading large volumes of raw image data or holding large numbers of open connections server-side could place unwanted burden on your infrastructure.\n\nThe simple solution to alleviate these concerns is to ensure capture requests are only made in-browser or in-app. This will distribute the bulk of the network and bandwidth strain.\n\nIf your use case doesn't allow for this approach, the bandwidth requirements are difficult to avoid. However, the number of open connections can be reduced by employing a [pre-request](#section-pre-request) along with a delay before attempting download of the captured previews.","category":"565f29797f93280d0052cf03","createdAt":"2015-12-02T17:41:01.597Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":8,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"performance","sync_unique":"","title":"Performance","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Performance


### Working with long running requests To avoid complexity, the first request for a new preview blocks for a number of seconds until the capture has completed. However, this introduces some complications. Captures are only initiated when a request for a preview has been made. If you make your requests in serial and wait for responses before proceeding, then they’ll stack behind each other. This will multiply your overall load time. Requesting multiple previews in parallel can be used to initiate capture for all desired configurations at once. In this case, your load time will be limited to the longest running query. Alternatively, you could choose to show those ready earlier as soon as they’re available. At scale, this could lead to a large number of open waiting connections if these requests are made server-side. We can also run into client-side connection limits in the browser.. ### Working with browser connection limits #### Requesting a single preview or two in parallel If you’re only requesting a single preview or two in parallel, then you can skip this section on working with browser connection limitations. All common browsers allow this to occur unrestricted. #### Requesting 3-6 images in parallel You can safely ignore this unless you're concerned about the performance of your web application in legacy browsers where per-host connection limits will impact users. However, if you’re concerned about the following browsers, we have a solution: - **IE6 or IE7** — Maximum connections per host is 2 - **Opera 9.x** — Maximum connections per host is 4 - **Safari 3 and 4** — Maximum connections per host is 4 To remedy this, we allow access to the API assets using [domain sharding](#section-domain-sharding). #### Requesting 7-10 images in parallel At 7 concurrent connections many browsers start to reach per host limits. As above, see [domain sharding](#section-domain-sharding). #### Requesting 10+ images in parallel When we reach 10 concurrent connections we start to hit all-host connection limits, particularly in Chrome. Domain sharding doesn’t stop our 11th request being queued, so it’s best to [pre-request](#section-pre-request) any images required before embedding. ### Domain sharding We allow GET requests against the API at custom subdomains, which allows you to circumvent browser per-host connections limits at the small cost of additional DNS lookups. For instance, if the following hit a per-host connection limit: [block:code] { "codes": [ { "code": "<img src=\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2000/thumb\">\n<img src=\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2002/thumb\">\n<img src=\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2003/thumb\">\n<img src=\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2007/thumb\">\n<img src=\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2010/thumb\">\n<img src=\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/NOTES9/thumb\">", "language": "html" } ] } [/block] The limit could be circumvented with: [block:code] { "codes": [ { "code": "<img src=\"https://OL2000.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2000/thumb\">\n<img src=\"https://OL2002.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2002/thumb\">\n<img src=\"https://OL2003.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2003/thumb\">\n<img src=\"https://OL2007.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2007/thumb\">\n<img src=\"https://OL2010.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2010/thumb\">\n<img src=\"https://NOTES9.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/NOTES9/thumb\">", "language": "html" } ] } [/block] Note that the choice of subdomain is arbitrary. You only need to ensure that they are distinct. You could equally use: [block:code] { "codes": [ { "code": "<img src=\"https://1.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2000/thumb\">\n<img src=\"https://2.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2002/thumb\">\n<img src=\"https://3.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2003/thumb\">\n<img src=\"https://4.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2007/thumb\">\n<img src=\"https://5.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2010/thumb\">\n<img src=\"https://6.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/NOTES9/thumb\">", "language": "html" } ] } [/block] ### Pre-request Pre-requesting allows for requesting that a capture (or set of captures) is initiated for specified configurations with an immediate (non-blocking) response. Because the API guards against duplicate captures, this means that any requests queued due to browser connection limits will yield the preview as soon as the pre-requested capture has completed, rather than initiating then waiting the full duration of capture. See the [API method](pre-request-a-set-of-previews-before-download) for further information. ### Managing server-side connections Downloading large volumes of raw image data or holding large numbers of open connections server-side could place unwanted burden on your infrastructure. The simple solution to alleviate these concerns is to ensure capture requests are only made in-browser or in-app. This will distribute the bulk of the network and bandwidth strain. If your use case doesn't allow for this approach, the bandwidth requirements are difficult to avoid. However, the number of open connections can be reduced by employing a [pre-request](#section-pre-request) along with a delay before attempting download of the captured previews.
### Working with long running requests To avoid complexity, the first request for a new preview blocks for a number of seconds until the capture has completed. However, this introduces some complications. Captures are only initiated when a request for a preview has been made. If you make your requests in serial and wait for responses before proceeding, then they’ll stack behind each other. This will multiply your overall load time. Requesting multiple previews in parallel can be used to initiate capture for all desired configurations at once. In this case, your load time will be limited to the longest running query. Alternatively, you could choose to show those ready earlier as soon as they’re available. At scale, this could lead to a large number of open waiting connections if these requests are made server-side. We can also run into client-side connection limits in the browser.. ### Working with browser connection limits #### Requesting a single preview or two in parallel If you’re only requesting a single preview or two in parallel, then you can skip this section on working with browser connection limitations. All common browsers allow this to occur unrestricted. #### Requesting 3-6 images in parallel You can safely ignore this unless you're concerned about the performance of your web application in legacy browsers where per-host connection limits will impact users. However, if you’re concerned about the following browsers, we have a solution: - **IE6 or IE7** — Maximum connections per host is 2 - **Opera 9.x** — Maximum connections per host is 4 - **Safari 3 and 4** — Maximum connections per host is 4 To remedy this, we allow access to the API assets using [domain sharding](#section-domain-sharding). #### Requesting 7-10 images in parallel At 7 concurrent connections many browsers start to reach per host limits. As above, see [domain sharding](#section-domain-sharding). #### Requesting 10+ images in parallel When we reach 10 concurrent connections we start to hit all-host connection limits, particularly in Chrome. Domain sharding doesn’t stop our 11th request being queued, so it’s best to [pre-request](#section-pre-request) any images required before embedding. ### Domain sharding We allow GET requests against the API at custom subdomains, which allows you to circumvent browser per-host connections limits at the small cost of additional DNS lookups. For instance, if the following hit a per-host connection limit: [block:code] { "codes": [ { "code": "<img src=\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2000/thumb\">\n<img src=\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2002/thumb\">\n<img src=\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2003/thumb\">\n<img src=\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2007/thumb\">\n<img src=\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2010/thumb\">\n<img src=\"https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/NOTES9/thumb\">", "language": "html" } ] } [/block] The limit could be circumvented with: [block:code] { "codes": [ { "code": "<img src=\"https://OL2000.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2000/thumb\">\n<img src=\"https://OL2002.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2002/thumb\">\n<img src=\"https://OL2003.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2003/thumb\">\n<img src=\"https://OL2007.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2007/thumb\">\n<img src=\"https://OL2010.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2010/thumb\">\n<img src=\"https://NOTES9.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/NOTES9/thumb\">", "language": "html" } ] } [/block] Note that the choice of subdomain is arbitrary. You only need to ensure that they are distinct. You could equally use: [block:code] { "codes": [ { "code": "<img src=\"https://1.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2000/thumb\">\n<img src=\"https://2.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2002/thumb\">\n<img src=\"https://3.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2003/thumb\">\n<img src=\"https://4.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2007/thumb\">\n<img src=\"https://5.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2010/thumb\">\n<img src=\"https://6.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/NOTES9/thumb\">", "language": "html" } ] } [/block] ### Pre-request Pre-requesting allows for requesting that a capture (or set of captures) is initiated for specified configurations with an immediate (non-blocking) response. Because the API guards against duplicate captures, this means that any requests queued due to browser connection limits will yield the preview as soon as the pre-requested capture has completed, rather than initiating then waiting the full duration of capture. See the [API method](pre-request-a-set-of-previews-before-download) for further information. ### Managing server-side connections Downloading large volumes of raw image data or holding large numbers of open connections server-side could place unwanted burden on your infrastructure. The simple solution to alleviate these concerns is to ensure capture requests are only made in-browser or in-app. This will distribute the bulk of the network and bandwidth strain. If your use case doesn't allow for this approach, the bandwidth requirements are difficult to avoid. However, the number of open connections can be reduced by employing a [pre-request](#section-pre-request) along with a delay before attempting download of the captured previews.
{"__v":5,"_id":"565f2947bca87d0d006bc676","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Litmus Email Analytics provides detailed metrics to better understand how your emails are performing. You will find data on who read your email, who deleted it, if they were on a mobile device, what email client they used, where were they located, and if they printed or forwarded. \n\nUsing the Email Analytics API you'll primarily be performing 2 functions: creating new campaigns and retrieving analytics data on those campaigns.\n\n## Authentication\n\nAs an API user youʼll have an API key which, combined with your API passphrase, allows you to log into the Litmus API over basic HTTP authentication. Note: this is different from any email address and password combination you might have used to access Litmus.\n\n## Reference Documentation\n\nIn additon to this documentation you can view all available functions at [https://analytics-api.litmus.com/#!/Campaigns](https://analytics-api.litmus.com/#!/Campaigns).  This site also allows you to run API calls directly in your browser!","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T17:24:23.532Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":0,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"email-analytics","sync_unique":"","title":"Email Analytics API","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Email Analytics API


Litmus Email Analytics provides detailed metrics to better understand how your emails are performing. You will find data on who read your email, who deleted it, if they were on a mobile device, what email client they used, where were they located, and if they printed or forwarded. Using the Email Analytics API you'll primarily be performing 2 functions: creating new campaigns and retrieving analytics data on those campaigns. ## Authentication As an API user youʼll have an API key which, combined with your API passphrase, allows you to log into the Litmus API over basic HTTP authentication. Note: this is different from any email address and password combination you might have used to access Litmus. ## Reference Documentation In additon to this documentation you can view all available functions at [https://analytics-api.litmus.com/#!/Campaigns](https://analytics-api.litmus.com/#!/Campaigns). This site also allows you to run API calls directly in your browser!
Litmus Email Analytics provides detailed metrics to better understand how your emails are performing. You will find data on who read your email, who deleted it, if they were on a mobile device, what email client they used, where were they located, and if they printed or forwarded. Using the Email Analytics API you'll primarily be performing 2 functions: creating new campaigns and retrieving analytics data on those campaigns. ## Authentication As an API user youʼll have an API key which, combined with your API passphrase, allows you to log into the Litmus API over basic HTTP authentication. Note: this is different from any email address and password combination you might have used to access Litmus. ## Reference Documentation In additon to this documentation you can view all available functions at [https://analytics-api.litmus.com/#!/Campaigns](https://analytics-api.litmus.com/#!/Campaigns). This site also allows you to run API calls directly in your browser!
{"__v":3,"_id":"565f29647f93280d0052cf01","api":{"auth":"required","examples":{"codes":[{"language":"curl","code":"curl -X POST \\\n-d '{ UserGuid: \"some-user-guid\" }' \\\n-u apikey:password \\\n-H \"Content-type: application/json\" \\\nhttps://analytics-api.litmus.com/api/v1/Campaigns","name":""}]},"params":[{"_id":"565f30a80dc99e1900f24bc7","default":"","desc":"","name":"UserGuid","required":false,"type":"string","in":"body"}],"results":{"codes":[{"name":"","code":"{\n  \"Id\": 1,\n  \"BugHtml\": \"<style>@media print{ #_t { background-image: url('https:\\/\\/xyz123.emltrk.com\\/xyz123?p&d=[UNIQUE]');}} div.OutlookMessageHeader {background-image:url('https:\\/\\/xyz123.emltrk.com\\/xyz123?f&d=[UNIQUE]')} table.moz-email-headers-table {background-image:url('https:\\/\\/xyz123.emltrk.com\\/xyz123?f&d=[UNIQUE]')} blockquote #_t {background-image:url('https:\\/\\/xyz123.emltrk.com\\/xyz123?f&d=[UNIQUE]')} #MailContainerBody #_t {background-image:url('https:\\/\\/xyz123.emltrk.com\\/xyz123?f&d=[UNIQUE]')}<\\/style><div id=\\\"_t\\\"><\\/div>\\r\\n<img src=\\\"https:\\/\\/xyz123.emltrk.com\\/xyz123?d=[UNIQUE]\\\" width=\\\"1\\\" height=\\\"1\\\" border=\\\"0\\\" \\/>\",\n  \"Guid\": \"xyz123\",\n  \"ReportGuid\": \"11111111-1111-1111-1111-abcdabcdabcd\",\n  \"UserGuid\": \"some-user-guid\",\n  \"CreatedAt\": \"2015-03-27T18:56:10Z\",\n  \"SentAt\": null,\n  \"OpenCount\": 0,\n  \"ExpiresAt\": null,\n  \"NeverExpires\": false\n}\n","language":"json","status":200}]},"settings":"565f2ff3413e06170093debc","url":"/Campaigns"},"body":"The only parameter in the create request is the `UserGuid`.  This is a pass-through field that should tie to a unique user ID in your system.  You can use this to track all the campaigns by a user.  This field is optional and can be left empty.\n\nThe response is the campaign serialized to json.\n\nThe two important fields to examine in the response are the `Guid` and the `BugHtml`.  You will need the `Guid` for all future requests regarding this campaign.  This is unique to this one campaign.  The `BugHtml` is the snippet of HTML you will need to insert into your outgoing email.  You will need to insert this inside the `<body></body>` tags.\n\nA note about the `BugHtml`:  You should try to keep this exactly as it is.  Altering this snippet can have unexpected consquences.  There is one exception.  You'll notice a few points where we include the url a parameter `d=[UNIQUE]`.  You will want to swap `[UNIQUE]` with a merge code from your system that will allow you to identify the recipients later.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T17:24:52.736Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"creating-a-campaign","sync_unique":"","title":"Creating a campaign","type":"post","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

postCreating a campaign


Body Params

UserGuid:
string
The only parameter in the create request is the `UserGuid`. This is a pass-through field that should tie to a unique user ID in your system. You can use this to track all the campaigns by a user. This field is optional and can be left empty. The response is the campaign serialized to json. The two important fields to examine in the response are the `Guid` and the `BugHtml`. You will need the `Guid` for all future requests regarding this campaign. This is unique to this one campaign. The `BugHtml` is the snippet of HTML you will need to insert into your outgoing email. You will need to insert this inside the `<body></body>` tags. A note about the `BugHtml`: You should try to keep this exactly as it is. Altering this snippet can have unexpected consquences. There is one exception. You'll notice a few points where we include the url a parameter `d=[UNIQUE]`. You will want to swap `[UNIQUE]` with a merge code from your system that will allow you to identify the recipients later.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



The only parameter in the create request is the `UserGuid`. This is a pass-through field that should tie to a unique user ID in your system. You can use this to track all the campaigns by a user. This field is optional and can be left empty. The response is the campaign serialized to json. The two important fields to examine in the response are the `Guid` and the `BugHtml`. You will need the `Guid` for all future requests regarding this campaign. This is unique to this one campaign. The `BugHtml` is the snippet of HTML you will need to insert into your outgoing email. You will need to insert this inside the `<body></body>` tags. A note about the `BugHtml`: You should try to keep this exactly as it is. Altering this snippet can have unexpected consquences. There is one exception. You'll notice a few points where we include the url a parameter `d=[UNIQUE]`. You will want to swap `[UNIQUE]` with a merge code from your system that will allow you to identify the recipients later.
{"__v":1,"_id":"565f29b90dc99e1900f24ba4","api":{"auth":"required","examples":{"codes":[{"language":"curl","code":"curl -X POST \\\n-d '{ \"Guids\": [ \"xyz123\" ] }' \\\n-u apikey:password \\\n-H \"Content-type: application/json\" \\\nhttps://analytics-api.litmus.com/api/v1/Campaigns/Get","name":""}]},"params":[{"_id":"565f32ba413e06170093dec5","default":"","desc":"","name":"Guids","required":true,"type":"array_string","in":"body"}],"results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"Id\": 1,\n    \"BugHtml\": \"<style>@media print{ #_t { background-image: url('https:\\/\\/xyz123.emltrk.com\\/xyz123?p&d=[UNIQUE]');}} div.OutlookMessageHeader {background-image:url('https:\\/\\/xyz123.emltrk.com\\/xyz123?f&d=[UNIQUE]')} table.moz-email-headers-table {background-image:url('https:\\/\\/xyz123.emltrk.com\\/xyz123?f&d=[UNIQUE]')} blockquote #_t {background-image:url('https:\\/\\/xyz123.emltrk.com\\/xyz123?f&d=[UNIQUE]')} #MailContainerBody #_t {background-image:url('https:\\/\\/xyz123.emltrk.com\\/xyz123?f&d=[UNIQUE]')}<\\/style><div id=\\\"_t\\\"><\\/div>\\r\\n<img src=\\\"https:\\/\\/xyz123.emltrk.com\\/xyz123?d=[UNIQUE]\\\" width=\\\"1\\\" height=\\\"1\\\" border=\\\"0\\\" \\/>\",\n    \"Guid\": \"xyz123\",\n    \"ReportGuid\": \"11111111-1111-1111-1111-abcdabcdabcd\",\n    \"UserGuid\": \"some-user-guid\",\n    \"CreatedAt\": \"2015-03-27T18:56:10Z\",\n    \"SentAt\": null,\n    \"OpenCount\": 0,\n    \"ExpiresAt\": null,\n    \"NeverExpires\": false\n  }\n]\n","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"565f2ff3413e06170093debc","url":"/Campaigns/Get"},"body":"You can fetch \"meta data\" on campaigns, including when the campaign expires and the user associated with it.  You can fetch this for 1 or many campaigns at one time.\n\nThe response is a collection of campaigns requested in json format.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T17:26:17.776Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"get-campaign-meta-data","sync_unique":"","title":"Get campaign meta data","type":"post","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

postGet campaign meta data


Body Params

Guids:
required
array of strings
You can fetch "meta data" on campaigns, including when the campaign expires and the user associated with it. You can fetch this for 1 or many campaigns at one time. The response is a collection of campaigns requested in json format.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



You can fetch "meta data" on campaigns, including when the campaign expires and the user associated with it. You can fetch this for 1 or many campaigns at one time. The response is a collection of campaigns requested in json format.
{"__v":3,"_id":"565f29d00dc99e1900f24ba6","api":{"auth":"required","examples":{"codes":[{"language":"text","code":"curl -X PUT \\\n-d '{ \"UserGuid\": \"some-guid\", \"ExpiresAt\": \"2015-12-31T23:59:59Z\", \"NeverExpires\": false }' \\\n-u apikey:password \\\n-H \"Content-type: application/json\" \\\nhttps://analytics-api.litmus.com/api/v1/Campaigns/xyz123","name":""}]},"params":[{"_id":"565f3d7423fd5f0d00a12ac8","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"},{"_id":"565f3d7423fd5f0d00a12ac7","required":false,"desc":"","default":"","type":"string","name":"UserGuid","in":"body"},{"_id":"565f3d7423fd5f0d00a12ac6","required":false,"desc":"","default":"","type":"timestamp","name":"ExpiresAt","in":"body"},{"_id":"565f3ddb649b951900c89763","required":false,"desc":"","default":"","type":"boolean","name":"NeverExpires","in":"body"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n    \"Id\": 1,\n    \"BugHtml\": \"<style>@media print{ #_t { background-image: url('https:\\/\\/xyz123.emltrk.com\\/xyz123?p&d=[UNIQUE]');}} div.OutlookMessageHeader {background-image:url('https:\\/\\/xyz123.emltrk.com\\/xyz123?f&d=[UNIQUE]')} table.moz-email-headers-table {background-image:url('https:\\/\\/xyz123.emltrk.com\\/xyz123?f&d=[UNIQUE]')} blockquote #_t {background-image:url('https:\\/\\/xyz123.emltrk.com\\/xyz123?f&d=[UNIQUE]')} #MailContainerBody #_t {background-image:url('https:\\/\\/xyz123.emltrk.com\\/xyz123?f&d=[UNIQUE]')}<\\/style><div id=\\\"_t\\\"><\\/div>\\r\\n<img src=\\\"https:\\/\\/xyz123.emltrk.com\\/xyz123?d=[UNIQUE]\\\" width=\\\"1\\\" height=\\\"1\\\" border=\\\"0\\\" \\/>\",\n    \"Guid\": \"xyz123\",\n    \"ReportGuid\": \"11111111-1111-1111-1111-abcdabcdabcd\",\n    \"UserGuid\": \"some-user-guid\",\n    \"CreatedAt\": \"2015-03-27T18:56:10Z\",\n    \"SentAt\": null,\n    \"OpenCount\": 0,\n    \"ExpiresAt\": \"2015-12-31T23:59:59Z\",\n    \"NeverExpires\": false\n}","name":""}]},"settings":"565f2ff3413e06170093debc","url":"/Campaigns/:Guid"},"body":"You can only update 3 fields on a campaign once it's been created:\n1. `UserGuid` - A pass-through field that should tie to a unique user ID in your system\n2. `ExpiresAt` - The date we will stop recording data on a campaign, note this time is <a href=\"http://en.wikipedia.org/wiki/Coordinated_Universal_Time\" target=\"_blank\">UTC</a>.\n3. `NeverExpires` - If this is set to true, Litmus will never stop recording data and will ignore `ExpiresAt`.\n\nThe response is the campaign in json format with the updated values.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T17:26:40.148Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"update-a-campaign","sync_unique":"","title":"Update a campaign","type":"put","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

putUpdate a campaign


Path Params

Guid:
required
string

Body Params

UserGuid:
string
ExpiresAt:
timestamp
NeverExpires:
boolean
You can only update 3 fields on a campaign once it's been created: 1. `UserGuid` - A pass-through field that should tie to a unique user ID in your system 2. `ExpiresAt` - The date we will stop recording data on a campaign, note this time is <a href="http://en.wikipedia.org/wiki/Coordinated_Universal_Time" target="_blank">UTC</a>. 3. `NeverExpires` - If this is set to true, Litmus will never stop recording data and will ignore `ExpiresAt`. The response is the campaign in json format with the updated values.

User Information

Try It Out

put
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



You can only update 3 fields on a campaign once it's been created: 1. `UserGuid` - A pass-through field that should tie to a unique user ID in your system 2. `ExpiresAt` - The date we will stop recording data on a campaign, note this time is <a href="http://en.wikipedia.org/wiki/Coordinated_Universal_Time" target="_blank">UTC</a>. 3. `NeverExpires` - If this is set to true, Litmus will never stop recording data and will ignore `ExpiresAt`. The response is the campaign in json format with the updated values.
{"__v":1,"_id":"565f29e5ea46251700972751","api":{"auth":"required","examples":{"codes":[{"language":"curl","code":"curl -X PUT \\\n-u apikey:password \\\n-H \"Content-type: application/json\" \\\nhttps://analytics-api.litmus.com/api/v1/Campaigns/xyz123/Start","name":""}]},"params":[{"_id":"565f3e9bea462517009727a3","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"}],"results":{"codes":[{"language":"text","code":""}]},"settings":"565f2ff3413e06170093debc","url":"/Campaigns/:Guid/Start"},"body":"Activating or starting a campaign will primarily do two things: timestamp the `SentAt` on the campaign, and set the `ExpiresAt` to 30 days from now if the `ExpiresAt` is null or less then 30 days from now.\n\nYou do not have to activate a campaign.  *If you do not Litmus will automatically activate it after it receives 500 opens.*","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T17:27:01.188Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"activate-a-campaign","sync_unique":"","title":"Activate a campaign","type":"put","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

putActivate a campaign


Path Params

Guid:
required
string
Activating or starting a campaign will primarily do two things: timestamp the `SentAt` on the campaign, and set the `ExpiresAt` to 30 days from now if the `ExpiresAt` is null or less then 30 days from now. You do not have to activate a campaign. *If you do not Litmus will automatically activate it after it receives 500 opens.*

User Information

Try It Out

put
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples



Activating or starting a campaign will primarily do two things: timestamp the `SentAt` on the campaign, and set the `ExpiresAt` to 30 days from now if the `ExpiresAt` is null or less then 30 days from now. You do not have to activate a campaign. *If you do not Litmus will automatically activate it after it receives 500 opens.*
{"__v":2,"_id":"565f29f57f93280d0052cf04","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Summary reports will get high-level data on a campaign and total opens.  All of these reports can be run for a single or multiple campaigns in a single call.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T17:27:17.403Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":5,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"summary-reports","sync_unique":"","title":"Summary reports","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Summary reports


Summary reports will get high-level data on a campaign and total opens. All of these reports can be run for a single or multiple campaigns in a single call.
Summary reports will get high-level data on a campaign and total opens. All of these reports can be run for a single or multiple campaigns in a single call.
{"__v":0,"_id":"565f4689de5dc50d00acfe41","api":{"settings":"565f2ff3413e06170093debc","results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"CampaignGuid\": \"xyz123\",\n    \"TotalOpens\": 116245\n  }\n]","name":""}]},"examples":{"codes":[{"language":"curl","code":"curl -X POST \\\n-d '{ \"Guids\": [ \"xyz123\" ] }' \\\n-u apikey:password \\\n-H \"Content-type: application/json\" \\\nhttps://analytics-api.litmus.com/api/v1/Campaigns/OpenCounts","name":""}]},"auth":"required","params":[{"_id":"565f403d7f93280d0052cf61","required":true,"desc":"","default":"","type":"array_string","name":"Guids","in":"body"}],"url":"/Campaigns/OpenCounts"},"body":"Use the Open Counts report to display the total opens a campaign has received.  You can use different requests to filter the opens to a specific date range, but note that the return object for all 3 possible calls is the same.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T19:29:13.960Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":6,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"open-counts-reports-guids","sync_unique":"","title":"Open counts reports (guid)","type":"post","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

postOpen counts reports (guid)


Body Params

Guids:
required
array of strings
Use the Open Counts report to display the total opens a campaign has received. You can use different requests to filter the opens to a specific date range, but note that the return object for all 3 possible calls is the same.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Use the Open Counts report to display the total opens a campaign has received. You can use different requests to filter the opens to a specific date range, but note that the return object for all 3 possible calls is the same.
{"__v":0,"_id":"565f41637f93280d0052cf65","api":{"examples":{"codes":[{"language":"curl","code":"# fetches all opens for given 4 digit year and 2 digit month - ie /OpenCounts/2015/03\ncurl -X POST \\\n-d '{ \"Guids\": [ \"xyz123\" ] }' \\\n-u apikey:password \\\n-H \"Content-type: application/json\" \\\nhttps://analytics-api.litmus.com/api/v1/Campaigns/OpenCounts/{year}/{month}","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"CampaignGuid\": \"xyz123\",\n    \"TotalOpens\": 116245\n  }\n]","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f41637f93280d0052cf68","required":true,"desc":"","default":"","type":"array_string","name":"Guids","in":"body"},{"_id":"565f41637f93280d0052cf67","required":false,"desc":"","default":"","type":"string","name":"year","in":"path"},{"_id":"565f41637f93280d0052cf66","required":false,"desc":"","default":"","type":"string","name":"month","in":"path"}],"url":"/Campaigns/OpenCounts/:year/:month"},"body":"Summary reports will get high-level data on a campaign and total opens.  All of these reports can be run for a single or multiple campaigns in a single call.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T19:07:15.576Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":7,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"open-count-reports-month","sync_unique":"","title":"Open count reports (month)","type":"post","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

postOpen count reports (month)


Path Params

year:
string
month:
string

Body Params

Guids:
required
array of strings
Summary reports will get high-level data on a campaign and total opens. All of these reports can be run for a single or multiple campaigns in a single call.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Summary reports will get high-level data on a campaign and total opens. All of these reports can be run for a single or multiple campaigns in a single call.
{"__v":0,"_id":"565f4237bca87d0d006bc6ce","api":{"examples":{"codes":[{"language":"curl","code":"# fetches all opens for given date range \n# to fetch all from 3/1/2015 to 3/15/2015 the call would be: /OpenCounts/20150301/20150315\ncurl -X POST \\\n-d '{ \"Guids\": [ \"xyz123\" ] }' \\\n-u apikey:password \\\n-H \"Content-type: application/json\" \\\nhttps://analytics-api.litmus.com/api/v1/Campaigns/OpenCounts/{fromDate}/{untilDate}","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"CampaignGuid\": \"xyz123\",\n    \"TotalOpens\": 116245\n  }\n]","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f4237bca87d0d006bc6d1","required":false,"desc":"","default":"","type":"array_string","name":"Guids","in":"body"},{"_id":"565f4237bca87d0d006bc6d0","required":false,"desc":"","default":"","type":"string","name":"fromDate","in":"path"},{"_id":"565f4237bca87d0d006bc6cf","required":false,"desc":"","default":"","type":"string","name":"untilDate","in":"path"}],"url":"/Campaigns/OpenCounts/:fromDate/:untilDate"},"body":"Use the Open Counts report to display the total opens a campaign has received.  You can use different requests to filter the opens to a specific date range, but note that the return object for all 3 possible calls is the same.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T19:10:47.178Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":8,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"open-count-reports-range","sync_unique":"","title":"Open count reports (range)","type":"post","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

postOpen count reports (range)


Path Params

fromDate:
string
untilDate:
string

Body Params

Guids:
array of strings
Use the Open Counts report to display the total opens a campaign has received. You can use different requests to filter the opens to a specific date range, but note that the return object for all 3 possible calls is the same.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Use the Open Counts report to display the total opens a campaign has received. You can use different requests to filter the opens to a specific date range, but note that the return object for all 3 possible calls is the same.
{"__v":0,"_id":"565f42f80dc99e1900f24c0b","api":{"examples":{"codes":[{"language":"curl","code":"curl -X POST \\\n-d '{ \"Guids\": [ \"xyz123\" ] }' \\\n-u apikey:password \\\n-H \"Content-type: application/json\" \\\nhttps://analytics-api.litmus.com/api/v1/Campaigns/AdvancedOpenCounts","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"CampaignGuid\": \"xyz123\",\n    \"TotalOpens\": 116026,\n    \"CreatedAt\": \"2015-03-27T18:56:10Z\",\n    \"SentAt\": \"2015-03-28T10:43:32Z\",\n    \"ExpiresAt\": \"2015-12-31T23:59:59Z\"\n  }\n]","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f42f80dc99e1900f24c0c","required":true,"desc":"","default":"","type":"array_string","name":"Guids","in":"body"}],"url":"/Campaigns/AdvancedOpenCounts"},"body":"Use the Advanced Open Counts report to display the total opens a campaign has received, how long it's been running, and when it will expire.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T19:14:00.585Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":9,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"advanced-open-counts-report","sync_unique":"","title":"Advanced open counts report","type":"post","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

postAdvanced open counts report


Body Params

Guids:
required
array of strings
Use the Advanced Open Counts report to display the total opens a campaign has received, how long it's been running, and when it will expire.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Use the Advanced Open Counts report to display the total opens a campaign has received, how long it's been running, and when it will expire.
{"__v":2,"_id":"565f2a05bca87d0d006bc67e","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Use Engagement Reports to see how much time users spent viewing an email.  For more information on our engagement metrics see: [How are engagement metrics defined?](https://litmus.com/help/analytics/engagement-metrics-definitions/)","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T17:27:33.748Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":10,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"engagement-reports","sync_unique":"","title":"Engagement reports","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Engagement reports


Use Engagement Reports to see how much time users spent viewing an email. For more information on our engagement metrics see: [How are engagement metrics defined?](https://litmus.com/help/analytics/engagement-metrics-definitions/)
Use Engagement Reports to see how much time users spent viewing an email. For more information on our engagement metrics see: [How are engagement metrics defined?](https://litmus.com/help/analytics/engagement-metrics-definitions/)
{"__v":0,"_id":"565f43b123fd5f0d00a12ae2","api":{"examples":{"codes":[{"language":"curl","code":"curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/EngagementReport\n","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"GlancedOrUnreadCount\": 15720,\n  \"SkimmedCount\": 12540,\n  \"ReadCount\": 44148,\n  \"GlancedOrUnreadPercentage\": 22,\n  \"SkimmedPercentage\": 17,\n  \"ReadPercentage\": 61,\n  \"GlancedOrUnreadAvgPercentage\": 30,\n  \"SkimmedAvgPercentage\": 21,\n  \"ReadAvgPercentage\": 49\n}\n","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f43b123fd5f0d00a12ae3","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"}],"url":"/Campaigns/:Guid/EngagementReport"},"body":"Use the Engagement Report to view the high-level engagement statistics for a campaign. This report returns the raw totals, as well as percentages for Read, Skimmed, and Glanced metrics. The report will also provide the average percentage that Litmus sees across all campaigns for comparison purposes.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T19:17:05.814Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":11,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"engagement-report","sync_unique":"","title":"Engagement report","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getEngagement report


Path Params

Guid:
required
string
Use the Engagement Report to view the high-level engagement statistics for a campaign. This report returns the raw totals, as well as percentages for Read, Skimmed, and Glanced metrics. The report will also provide the average percentage that Litmus sees across all campaigns for comparison purposes.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Use the Engagement Report to view the high-level engagement statistics for a campaign. This report returns the raw totals, as well as percentages for Read, Skimmed, and Glanced metrics. The report will also provide the average percentage that Litmus sees across all campaigns for comparison purposes.
{"__v":0,"_id":"565f44b2413e06170093def7","api":{"examples":{"codes":[{"language":"curl","code":"curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/DetailedEngagementReport\n","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"Less2SecCount\": 15765,\n  \"Less4SecCount\": 6343,\n  \"Less6SecCount\": 3672,\n  \"Less8SecCount\": 2542,\n  \"Less10SecCount\": 1916,\n  \"Less12SecCount\": 1423,\n  \"Less14SecCount\": 1200,\n  \"Less16SecCount\": 1134,\n  \"Less18SecCount\": 832,\n  \"Over18SecCount\": 37725,\n  \"Less2SecPercentage\": 22,\n  \"Less4SecPercentage\": 9,\n  \"Less6SecPercentage\": 5,\n  \"Less8SecPercentage\": 4,\n  \"Less10SecPercentage\": 3,\n  \"Less12SecPercentage\": 2,\n  \"Less14SecPercentage\": 2,\n  \"Less16SecPercentage\": 2,\n  \"Less18SecPercentage\": 1,\n  \"Over18SecPercentage\": 50,\n  \"Less2SecAvgCount\": 5820,\n  \"Less4SecAvgCount\": 1151,\n  \"Less6SecAvgCount\": 752,\n  \"Less8SecAvgCount\": 579,\n  \"Less10SecAvgCount\": 527,\n  \"Less12SecAvgCount\": 409,\n  \"Less14SecAvgCount\": 516,\n  \"Less16SecAvgCount\": 299,\n  \"Less18SecAvgCount\": 232,\n  \"Over18SecAvgCount\": 5445,\n  \"Less2SecAvgPercentage\": 37,\n  \"Less4SecAvgPercentage\": 7,\n  \"Less6SecAvgPercentage\": 5,\n  \"Less8SecAvgPercentage\": 4,\n  \"Less10SecAvgPercentage\": 3,\n  \"Less12SecAvgPercentage\": 3,\n  \"Less14SecAvgPercentage\": 3,\n  \"Less16SecAvgPercentage\": 2,\n  \"Less18SecAvgPercentage\": 1,\n  \"Over18SecAvgPercentage\": 35\n}\n","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f44b2413e06170093def8","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"}],"url":"/Campaigns/:Guid/DetailedEngagementReport"},"body":"Use the Detailed Engagement Report to see a breakdown of your open engagement into 2 second blocks.  This is useful for drawing line graphs to show where engagement drops off.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T19:21:22.215Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":12,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"detailed-engagement-report","sync_unique":"","title":"Detailed engagement report","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getDetailed engagement report


Path Params

Guid:
required
string
Use the Detailed Engagement Report to see a breakdown of your open engagement into 2 second blocks. This is useful for drawing line graphs to show where engagement drops off.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Use the Detailed Engagement Report to see a breakdown of your open engagement into 2 second blocks. This is useful for drawing line graphs to show where engagement drops off.
{"__v":0,"_id":"565f452e649b951900c89780","api":{"examples":{"codes":[{"language":"curl","code":"curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/GroupEngagementReport\n","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"Name\": \"Mobile\",\n    \"Count\": 10318,\n    \"GlancedOrUnreadCount\": 1253,\n    \"SkimmedCount\": 1790,\n    \"ReadCount\": 7275,\n    \"GlancedOrUnreadPercentage\": 1,\n    \"SkimmedPercentage\": 2,\n    \"ReadPercentage\": 6\n  },\n  {\n    \"Name\": \"Webmail\",\n    \"Count\": 43640,\n    \"GlancedOrUnreadCount\": 0,\n    \"SkimmedCount\": 0,\n    \"ReadCount\": 0,\n    \"GlancedOrUnreadPercentage\": 0,\n    \"SkimmedPercentage\": 0,\n    \"ReadPercentage\": 0\n  },\n  {\n    \"Name\": \"Desktop\",\n    \"Count\": 58658,\n    \"GlancedOrUnreadCount\": 13779,\n    \"SkimmedCount\": 10206,\n    \"ReadCount\": 34672,\n    \"GlancedOrUnreadPercentage\": 12,\n    \"SkimmedPercentage\": 9,\n    \"ReadPercentage\": 30\n  },\n  {\n    \"Name\": \"Other\",\n    \"Count\": 3433,\n    \"GlancedOrUnreadCount\": 688,\n    \"SkimmedCount\": 544,\n    \"ReadCount\": 2201,\n    \"GlancedOrUnreadPercentage\": 1,\n    \"SkimmedPercentage\": 0,\n    \"ReadPercentage\": 2\n  }\n]\n","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f452e649b951900c89781","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"}],"url":"/Campaigns/:Guid/GroupEngagementReport"},"body":"The Group Engagement Report breaks the engagement data down by platform: Mobile, Webmail, Desktop, Other / Unknown.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T19:23:26.016Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":13,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"group-engagement-report","sync_unique":"","title":"Group engagement report","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getGroup engagement report


Path Params

Guid:
required
string
The Group Engagement Report breaks the engagement data down by platform: Mobile, Webmail, Desktop, Other / Unknown.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



The Group Engagement Report breaks the engagement data down by platform: Mobile, Webmail, Desktop, Other / Unknown.
{"__v":0,"_id":"565f459e23fd5f0d00a12ae7","api":{"examples":{"codes":[{"language":"curl","code":"curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/MailClientEngagement","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"Name\": \"Mobile\",\n    \"Count\": 10318,\n    \"GlancedOrUnreadCount\": 1253,\n    \"SkimmedCount\": 1790,\n    \"ReadCount\": 7275,\n    \"GlancedOrUnreadPercentage\": 1,\n    \"SkimmedPercentage\": 2,\n    \"ReadPercentage\": 6\n  },\n  {\n    \"Name\": \"Webmail\",\n    \"Count\": 43640,\n    \"GlancedOrUnreadCount\": 0,\n    \"SkimmedCount\": 0,\n    \"ReadCount\": 0,[\n  {\n    \"Name\": \"Apple iPad\",\n    \"Count\": 1206,\n    \"GlancedOrUnreadCount\": 234,\n    \"SkimmedCount\": 288,\n    \"ReadCount\": 684,\n    \"GlancedOrUnreadPercentage\": 0,\n    \"SkimmedPercentage\": 0,\n    \"ReadPercentage\": 1\n  },\n  {\n    \"Name\": \"Apple iPhone\",\n    \"Count\": 7714,\n    \"GlancedOrUnreadCount\": 898,\n    \"SkimmedCount\": 1305,\n    \"ReadCount\": 5511,\n    \"GlancedOrUnreadPercentage\": 1,\n    \"SkimmedPercentage\": 2,\n    \"ReadPercentage\": 8\n  },\n  {\n    \"Name\": \"Outlook\",\n    \"Count\": 21491,\n    \"GlancedOrUnreadCount\": 4388,\n    \"SkimmedCount\": 3237,\n    \"ReadCount\": 13866,\n    \"GlancedOrUnreadPercentage\": 6,\n    \"SkimmedPercentage\": 4,\n    \"ReadPercentage\": 19\n  },\n  {\n    \"Name\": \"Google Android\",\n    \"Count\": 1343,\n    \"GlancedOrUnreadCount\": 107,\n    \"SkimmedCount\": 188,\n    \"ReadCount\": 1048,\n    \"GlancedOrUnreadPercentage\": 0,\n    \"SkimmedPercentage\": 0,\n    \"ReadPercentage\": 1\n  },\n  {\n    \"Name\": \"Thunderbird\",\n    \"Count\": 121,\n    \"GlancedOrUnreadCount\": 13,\n    \"SkimmedCount\": 22,\n    \"ReadCount\": 86,\n    \"GlancedOrUnreadPercentage\": 0,\n    \"SkimmedPercentage\": 0,\n    \"ReadPercentage\": 0\n  },\n  {\n    \"Name\": \"Entourage\",\n    \"Count\": 1,\n    \"GlancedOrUnreadCount\": 0,\n    \"SkimmedCount\": 0,\n    \"ReadCount\": 0,\n    \"GlancedOrUnreadPercentage\": 0,\n    \"SkimmedPercentage\": 0,\n    \"ReadPercentage\": 0\n  },\n  {\n    \"Name\": \"Postbox\",\n    \"Count\": 179,\n    \"GlancedOrUnreadCount\": 50,\n    \"SkimmedCount\": 51,\n    \"ReadCount\": 78,\n    \"GlancedOrUnreadPercentage\": 0,\n    \"SkimmedPercentage\": 0,\n    \"ReadPercentage\": 0\n  },\n  {\n    \"Name\": \"Windows Live Mail\",\n    \"Count\": 323,\n    \"GlancedOrUnreadCount\": 98,\n    \"SkimmedCount\": 76,\n    \"ReadCount\": 149,\n    \"GlancedOrUnreadPercentage\": 0,\n    \"SkimmedPercentage\": 0,\n    \"ReadPercentage\": 0\n  },\n  {\n    \"Name\": \"BlackBerry\",\n    \"Count\": 66,\n    \"GlancedOrUnreadCount\": 14,\n    \"SkimmedCount\": 11,\n    \"ReadCount\": 41,\n    \"GlancedOrUnreadPercentage\": 0,\n    \"SkimmedPercentage\": 0,\n    \"ReadPercentage\": 0\n  },\n  {\n    \"Name\": \"Apple Mail\",\n    \"Count\": 36640,\n    \"GlancedOrUnreadCount\": 9272,\n    \"SkimmedCount\": 6835,\n    \"ReadCount\": 20533,\n    \"GlancedOrUnreadPercentage\": 13,\n    \"SkimmedPercentage\": 9,\n    \"ReadPercentage\": 28\n  },\n  {\n    \"Name\": \"Other\",\n    \"Count\": 3469,\n    \"GlancedOrUnreadCount\": 691,\n    \"SkimmedCount\": 544,\n    \"ReadCount\": 2234,\n    \"GlancedOrUnreadPercentage\": 1,\n    \"SkimmedPercentage\": 1,\n    \"ReadPercentage\": 3\n  }\n]\n","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f459e23fd5f0d00a12ae8","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"}],"url":"/Campaigns/:Guid/MailClientEngagement"},"body":"The Mail Client Engagement Report breaks down the engagement data by specific mail client. Get the Glanced, Skimmed, and Read metrics across each of your email clients.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T19:25:18.590Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":14,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"mail-client-engagement-report","sync_unique":"","title":"Mail engagement report","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getMail engagement report


Path Params

Guid:
required
string
The Mail Client Engagement Report breaks down the engagement data by specific mail client. Get the Glanced, Skimmed, and Read metrics across each of your email clients.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



The Mail Client Engagement Report breaks down the engagement data by specific mail client. Get the Glanced, Skimmed, and Read metrics across each of your email clients.
{"__v":0,"_id":"565f462ebca87d0d006bc6df","api":{"examples":{"codes":[{"language":"curl","code":"curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/DetailedMailClientEngagement\n","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"Name\": \"Apple iPad\",\n    \"Count\": 1206,\n    \"ReadCount\": 684,\n    \"Less2SecCount\": 234,\n    \"Less4SecCount\": 140,\n    \"Less6SecCount\": 79,\n    \"Less8SecCount\": 69,\n    \"Less10SecCount\": 49,\n    \"Less12SecCount\": 42,\n    \"Less14SecCount\": 29,\n    \"Less16SecCount\": 29,\n    \"Less18SecCount\": 25,\n    \"Over18SecCount\": 510,\n    \"ReadPercentage\": 57,\n    \"Less2SecPercentage\": 0,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 100\n  },\n  {\n    \"Name\": \"Apple iPhone\",\n    \"Count\": 7714,\n    \"ReadCount\": 5511,\n    \"Less2SecCount\": 898,\n    \"Less4SecCount\": 643,\n    \"Less6SecCount\": 380,\n    \"Less8SecCount\": 282,\n    \"Less10SecCount\": 245,\n    \"Less12SecCount\": 207,\n    \"Less14SecCount\": 163,\n    \"Less16SecCount\": 221,\n    \"Less18SecCount\": 111,\n    \"Over18SecCount\": 4564,\n    \"ReadPercentage\": 71,\n    \"Less2SecPercentage\": 1,\n    \"Less4SecPercentage\": 1,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 98\n  },\n  {\n    \"Name\": \"AOL Mail\",\n    \"Count\": 44,\n    \"ReadCount\": 0,\n    \"Less2SecCount\": 0,\n    \"Less4SecCount\": 0,\n    \"Less6SecCount\": 0,\n    \"Less8SecCount\": 0,\n    \"Less10SecCount\": 0,\n    \"Less12SecCount\": 0,\n    \"Less14SecCount\": 0,\n    \"Less16SecCount\": 0,\n    \"Less18SecCount\": 0,\n    \"Over18SecCount\": 0,\n    \"ReadPercentage\": 0,\n    \"Less2SecPercentage\": 0,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 100\n  },\n  {\n    \"Name\": \"Outlook\",\n    \"Count\": 21491,\n    \"ReadCount\": 13866,\n    \"Less2SecCount\": 4388,\n    \"Less4SecCount\": 1658,\n    \"Less6SecCount\": 922,\n    \"Less8SecCount\": 657,\n    \"Less10SecCount\": 535,\n    \"Less12SecCount\": 398,\n    \"Less14SecCount\": 342,\n    \"Less16SecCount\": 332,\n    \"Less18SecCount\": 277,\n    \"Over18SecCount\": 11982,\n    \"ReadPercentage\": 65,\n    \"Less2SecPercentage\": 4,\n    \"Less4SecPercentage\": 1,\n    \"Less6SecPercentage\": 1,\n    \"Less8SecPercentage\": 1,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 93\n  },\n  {\n    \"Name\": \"Yahoo! Mail\",\n    \"Count\": 791,\n    \"ReadCount\": 0,\n    \"Less2SecCount\": 0,\n    \"Less4SecCount\": 0,\n    \"Less6SecCount\": 0,\n    \"Less8SecCount\": 0,\n    \"Less10SecCount\": 0,\n    \"Less12SecCount\": 0,\n    \"Less14SecCount\": 0,\n    \"Less16SecCount\": 0,\n    \"Less18SecCount\": 0,\n    \"Over18SecCount\": 0,\n    \"ReadPercentage\": 0,\n    \"Less2SecPercentage\": 0,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 100\n  },\n  {\n    \"Name\": \"Google Android\",\n    \"Count\": 1343,\n    \"ReadCount\": 1048,\n    \"Less2SecCount\": 107,\n    \"Less4SecCount\": 72,\n    \"Less6SecCount\": 67,\n    \"Less8SecCount\": 49,\n    \"Less10SecCount\": 50,\n    \"Less12SecCount\": 40,\n    \"Less14SecCount\": 29,\n    \"Less16SecCount\": 36,\n    \"Less18SecCount\": 25,\n    \"Over18SecCount\": 868,\n    \"ReadPercentage\": 78,\n    \"Less2SecPercentage\": 0,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 100\n  },\n  {\n    \"Name\": \"Thunderbird\",\n    \"Count\": 121,\n    \"ReadCount\": 86,\n    \"Less2SecCount\": 13,\n    \"Less4SecCount\": 13,\n    \"Less6SecCount\": 5,\n    \"Less8SecCount\": 4,\n    \"Less10SecCount\": 3,\n    \"Less12SecCount\": 4,\n    \"Less14SecCount\": 2,\n    \"Less16SecCount\": 2,\n    \"Less18SecCount\": 0,\n    \"Over18SecCount\": 75,\n    \"ReadPercentage\": 71,\n    \"Less2SecPercentage\": 0,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 100\n  },\n  {\n    \"Name\": \"Outlook.com\",\n    \"Count\": 817,\n    \"ReadCount\": 0,\n    \"Less2SecCount\": 0,\n    \"Less4SecCount\": 0,\n    \"Less6SecCount\": 0,\n    \"Less8SecCount\": 0,\n    \"Less10SecCount\": 0,\n    \"Less12SecCount\": 0,\n    \"Less14SecCount\": 0,\n    \"Less16SecCount\": 0,\n    \"Less18SecCount\": 0,\n    \"Over18SecCount\": 0,\n    \"ReadPercentage\": 0,\n    \"Less2SecPercentage\": 0,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 100\n  },\n  {\n    \"Name\": \"Entourage\",\n    \"Count\": 1,\n    \"ReadCount\": 0,\n    \"Less2SecCount\": 0,\n    \"Less4SecCount\": 0,\n    \"Less6SecCount\": 0,\n    \"Less8SecCount\": 0,\n    \"Less10SecCount\": 0,\n    \"Less12SecCount\": 0,\n    \"Less14SecCount\": 0,\n    \"Less16SecCount\": 0,\n    \"Less18SecCount\": 0,\n    \"Over18SecCount\": 0,\n    \"ReadPercentage\": 0,\n    \"Less2SecPercentage\": 0,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 100\n  },\n  {\n    \"Name\": \"Postbox\",\n    \"Count\": 179,\n    \"ReadCount\": 78,\n    \"Less2SecCount\": 50,\n    \"Less4SecCount\": 24,\n    \"Less6SecCount\": 16,\n    \"Less8SecCount\": 11,\n    \"Less10SecCount\": 7,\n    \"Less12SecCount\": 5,\n    \"Less14SecCount\": 2,\n    \"Less16SecCount\": 3,\n    \"Less18SecCount\": 1,\n    \"Over18SecCount\": 60,\n    \"ReadPercentage\": 44,\n    \"Less2SecPercentage\": 0,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 100\n  },\n  {\n    \"Name\": \"Windows Live Mail\",\n    \"Count\": 323,\n    \"ReadCount\": 149,\n    \"Less2SecCount\": 98,\n    \"Less4SecCount\": 39,\n    \"Less6SecCount\": 15,\n    \"Less8SecCount\": 22,\n    \"Less10SecCount\": 5,\n    \"Less12SecCount\": 11,\n    \"Less14SecCount\": 3,\n    \"Less16SecCount\": 7,\n    \"Less18SecCount\": 6,\n    \"Over18SecCount\": 117,\n    \"ReadPercentage\": 46,\n    \"Less2SecPercentage\": 0,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 100\n  },\n  {\n    \"Name\": \"BlackBerry\",\n    \"Count\": 66,\n    \"ReadCount\": 41,\n    \"Less2SecCount\": 14,\n    \"Less4SecCount\": 4,\n    \"Less6SecCount\": 4,\n    \"Less8SecCount\": 3,\n    \"Less10SecCount\": 4,\n    \"Less12SecCount\": 2,\n    \"Less14SecCount\": 1,\n    \"Less16SecCount\": 0,\n    \"Less18SecCount\": 1,\n    \"Over18SecCount\": 33,\n    \"ReadPercentage\": 62,\n    \"Less2SecPercentage\": 0,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 100\n  },\n  {\n    \"Name\": \"Gmail\",\n    \"Count\": 35909,\n    \"ReadCount\": 0,\n    \"Less2SecCount\": 0,\n    \"Less4SecCount\": 0,\n    \"Less6SecCount\": 0,\n    \"Less8SecCount\": 0,\n    \"Less10SecCount\": 0,\n    \"Less12SecCount\": 0,\n    \"Less14SecCount\": 0,\n    \"Less16SecCount\": 0,\n    \"Less18SecCount\": 0,\n    \"Over18SecCount\": 0,\n    \"ReadPercentage\": 0,\n    \"Less2SecPercentage\": 0,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 100\n  },\n  {\n    \"Name\": \"Web version\",\n    \"Count\": 6130,\n    \"ReadCount\": 0,\n    \"Less2SecCount\": 0,\n    \"Less4SecCount\": 0,\n    \"Less6SecCount\": 0,\n    \"Less8SecCount\": 0,\n    \"Less10SecCount\": 0,\n    \"Less12SecCount\": 0,\n    \"Less14SecCount\": 0,\n    \"Less16SecCount\": 0,\n    \"Less18SecCount\": 0,\n    \"Over18SecCount\": 0,\n    \"ReadPercentage\": 0,\n    \"Less2SecPercentage\": 0,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 100\n  },\n  {\n    \"Name\": \"Apple Mail\",\n    \"Count\": 36640,\n    \"ReadCount\": 20533,\n    \"Less2SecCount\": 9272,\n    \"Less4SecCount\": 3499,\n    \"Less6SecCount\": 2007,\n    \"Less8SecCount\": 1329,\n    \"Less10SecCount\": 902,\n    \"Less12SecCount\": 655,\n    \"Less14SecCount\": 575,\n    \"Less16SecCount\": 464,\n    \"Less18SecCount\": 355,\n    \"Over18SecCount\": 17582,\n    \"ReadPercentage\": 56,\n    \"Less2SecPercentage\": 8,\n    \"Less4SecPercentage\": 3,\n    \"Less6SecPercentage\": 2,\n    \"Less8SecPercentage\": 1,\n    \"Less10SecPercentage\": 1,\n    \"Less12SecPercentage\": 1,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 84\n  },\n  {\n    \"Name\": \"Other\",\n    \"Count\": 3469,\n    \"ReadCount\": 2234,\n    \"Less2SecCount\": 691,\n    \"Less4SecCount\": 251,\n    \"Less6SecCount\": 177,\n    \"Less8SecCount\": 116,\n    \"Less10SecCount\": 116,\n    \"Less12SecCount\": 59,\n    \"Less14SecCount\": 54,\n    \"Less16SecCount\": 40,\n    \"Less18SecCount\": 31,\n    \"Over18SecCount\": 1934,\n    \"ReadPercentage\": 64,\n    \"Less2SecPercentage\": 1,\n    \"Less4SecPercentage\": 0,\n    \"Less6SecPercentage\": 0,\n    \"Less8SecPercentage\": 0,\n    \"Less10SecPercentage\": 0,\n    \"Less12SecPercentage\": 0,\n    \"Less14SecPercentage\": 0,\n    \"Less16SecPercentage\": 0,\n    \"Less18SecPercentage\": 0,\n    \"Over18SecPercentage\": 99\n  }\n]\n","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f462ebca87d0d006bc6e0","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"}],"url":"/Campaigns/:Guid/DetailedMailClientEngagement"},"body":"The Detailed Mail Client Engagement Report breaks down the detailed engagement data by specific mail client. Get the 2 second engagement blocks across each of your email clients.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T19:27:42.471Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":15,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"detailed-mail-client-engagement-report","sync_unique":"","title":"Detailed mail engagement report","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getDetailed mail engagement report


Path Params

Guid:
required
string
The Detailed Mail Client Engagement Report breaks down the detailed engagement data by specific mail client. Get the 2 second engagement blocks across each of your email clients.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



The Detailed Mail Client Engagement Report breaks down the detailed engagement data by specific mail client. Get the 2 second engagement blocks across each of your email clients.
{"__v":2,"_id":"565f2a16649b951900c89721","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Use Platform Reports to learn more about the environment an email is being viewed in.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T17:27:50.641Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":16,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"platform-reports","sync_unique":"","title":"Platform reports","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Platform reports


Use Platform Reports to learn more about the environment an email is being viewed in.
Use Platform Reports to learn more about the environment an email is being viewed in.
{"__v":0,"_id":"565f50f5649b951900c897b2","api":{"examples":{"codes":[{"language":"curl","code":"curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/MailClientUsage\n","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"Name\": \"Apple Mail\",\n    \"Count\": 36640,\n    \"Percentage\": 31.5,\n    \"AvgPercentage\": 7.305,\n    \"Versions\": [\n      {\n        \"Name\": \"Apple Mail 3\",\n        \"Count\": 41,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 2.024\n      },\n      {\n        \"Name\": \"Apple Mail 2\",\n        \"Count\": 17,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.456\n      },\n      {\n        \"Name\": \"Apple Mail 8\",\n        \"Count\": 23750,\n        \"Percentage\": 20.4,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Apple Mail 7\",\n        \"Count\": 8465,\n        \"Percentage\": 7.3,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Apple Mail 6\",\n        \"Count\": 2398,\n        \"Percentage\": 2.1,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Apple Mail 5\",\n        \"Count\": 1094,\n        \"Percentage\": 0.9,\n        \"AvgPercentage\": 0.039\n      },\n      {\n        \"Name\": \"Apple Mail 4\",\n        \"Count\": 875,\n        \"Percentage\": 0.8,\n        \"AvgPercentage\": 4.786\n      }\n    ]\n  },\n  {\n    \"Name\": \"Gmail\",\n    \"Count\": 35909,\n    \"Percentage\": 30.9,\n    \"AvgPercentage\": 0,\n    \"Versions\": [\n      {\n        \"Name\": \"Via Gmail's Image Cache\",\n        \"Count\": 35909,\n        \"Percentage\": 30.9,\n        \"AvgPercentage\": 0\n      }\n    ]\n  },\n  {\n    \"Name\": \"Outlook\",\n    \"Count\": 21491,\n    \"Percentage\": 18.5,\n    \"AvgPercentage\": 38.294,\n    \"Versions\": [\n      {\n        \"Name\": \"Outlook Web Access (Firefox)\",\n        \"Count\": 1,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.006\n      },\n      {\n        \"Name\": \"Outlook 2007\",\n        \"Count\": 3198,\n        \"Percentage\": 2.8,\n        \"AvgPercentage\": 5.86\n      },\n      {\n        \"Name\": \"Outlook Web Access (Explorer)\",\n        \"Count\": 1,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.076\n      },\n      {\n        \"Name\": \"Outlook 2013\",\n        \"Count\": 7146,\n        \"Percentage\": 6.1,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Outlook 2010\",\n        \"Count\": 9527,\n        \"Percentage\": 8.2,\n        \"AvgPercentage\": 1.324\n      },\n      {\n        \"Name\": \"Outlook 2000-2003\",\n        \"Count\": 1618,\n        \"Percentage\": 1.4,\n        \"AvgPercentage\": 31.028\n      }\n    ]\n  },\n  {\n    \"Name\": \"Apple iPhone\",\n    \"Count\": 7714,\n    \"Percentage\": 6.6,\n    \"AvgPercentage\": 0,\n    \"Versions\": [\n      {\n        \"Name\": \"iOS 6\",\n        \"Count\": 94,\n        \"Percentage\": 0.1,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"iOS 5\",\n        \"Count\": 9,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"iOS 4\",\n        \"Count\": 3,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"iOS 8\",\n        \"Count\": 6669,\n        \"Percentage\": 5.7,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"iOS 7\",\n        \"Count\": 939,\n        \"Percentage\": 0.8,\n        \"AvgPercentage\": 0\n      }\n    ]\n  },\n  {\n    \"Name\": \"Web version\",\n    \"Count\": 6130,\n    \"Percentage\": 5.3,\n    \"AvgPercentage\": 7.617,\n    \"Versions\": [\n      {\n        \"Name\": \"Using Explorer\",\n        \"Count\": 98,\n        \"Percentage\": 0.1,\n        \"AvgPercentage\": 5.148\n      },\n      {\n        \"Name\": \"Using iPad\",\n        \"Count\": 24,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.022\n      },\n      {\n        \"Name\": \"Using iPhone\",\n        \"Count\": 91,\n        \"Percentage\": 0.1,\n        \"AvgPercentage\": 0.024\n      },\n      {\n        \"Name\": \"Using Android\",\n        \"Count\": 93,\n        \"Percentage\": 0.1,\n        \"AvgPercentage\": 0.032\n      },\n      {\n        \"Name\": \"Using Chrome\",\n        \"Count\": 4083,\n        \"Percentage\": 3.5,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Using Firefox\",\n        \"Count\": 1257,\n        \"Percentage\": 1.1,\n        \"AvgPercentage\": 1.756\n      },\n      {\n        \"Name\": \"Using Safari\",\n        \"Count\": 362,\n        \"Percentage\": 0.3,\n        \"AvgPercentage\": 0.391\n      },\n      {\n        \"Name\": \"Other\",\n        \"Count\": 122,\n        \"Percentage\": 0.1,\n        \"AvgPercentage\": 0.051\n      }\n    ]\n  },\n  {\n    \"Name\": \"Other\",\n    \"Count\": 3469,\n    \"Percentage\": 3,\n    \"AvgPercentage\": 2.433,\n    \"Versions\": [\n      {\n        \"Name\": \"Other\",\n        \"Count\": 3469,\n        \"Percentage\": 3,\n        \"AvgPercentage\": 2.433\n      }\n    ]\n  },\n  {\n    \"Name\": \"Google Android\",\n    \"Count\": 1343,\n    \"Percentage\": 1.2,\n    \"AvgPercentage\": 0,\n    \"Versions\": [\n      {\n        \"Name\": \"5.x\",\n        \"Count\": 305,\n        \"Percentage\": 0.3,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"4.x\",\n        \"Count\": 1019,\n        \"Percentage\": 0.9,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"2.x\",\n        \"Count\": 19,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      }\n    ]\n  },\n  {\n    \"Name\": \"Apple iPad\",\n    \"Count\": 1206,\n    \"Percentage\": 1,\n    \"AvgPercentage\": 0,\n    \"Versions\": [\n      {\n        \"Name\": \"iOS 7\",\n        \"Count\": 207,\n        \"Percentage\": 0.2,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"iOS 6\",\n        \"Count\": 5,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"iOS 5\",\n        \"Count\": 32,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"iOS 8\",\n        \"Count\": 962,\n        \"Percentage\": 0.8,\n        \"AvgPercentage\": 0\n      }\n    ]\n  },\n  {\n    \"Name\": \"Outlook.com\",\n    \"Count\": 817,\n    \"Percentage\": 0.6,\n    \"AvgPercentage\": 0,\n    \"Versions\": [\n      {\n        \"Name\": \"Using iPhone\",\n        \"Count\": 2,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Using Android\",\n        \"Count\": 2,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Using Firefox\",\n        \"Count\": 214,\n        \"Percentage\": 0.2,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Using Explorer\",\n        \"Count\": 11,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Using iPad\",\n        \"Count\": 2,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Using Chrome\",\n        \"Count\": 498,\n        \"Percentage\": 0.4,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Using Safari\",\n        \"Count\": 52,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Other\",\n        \"Count\": 36,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      }\n    ]\n  },\n  {\n    \"Name\": \"Yahoo! Mail\",\n    \"Count\": 791,\n    \"Percentage\": 0.6,\n    \"AvgPercentage\": 7.825,\n    \"Versions\": [\n      {\n        \"Name\": \"Using Firefox\",\n        \"Count\": 276,\n        \"Percentage\": 0.2,\n        \"AvgPercentage\": 2.1\n      },\n      {\n        \"Name\": \"Using Explorer\",\n        \"Count\": 10,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 4.983\n      },\n      {\n        \"Name\": \"Using Chrome\",\n        \"Count\": 436,\n        \"Percentage\": 0.4,\n        \"AvgPercentage\": 0.299\n      },\n      {\n        \"Name\": \"Using Safari\",\n        \"Count\": 55,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.427\n      },\n      {\n        \"Name\": \"Other\",\n        \"Count\": 14,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.016\n      }\n    ]\n  },\n  {\n    \"Name\": \"Windows Live Mail\",\n    \"Count\": 323,\n    \"Percentage\": 0.3,\n    \"AvgPercentage\": 0.864,\n    \"Versions\": [\n      {\n        \"Name\": \"Live Mail 2008\",\n        \"Count\": 323,\n        \"Percentage\": 0.3,\n        \"AvgPercentage\": 0.864\n      }\n    ]\n  },\n  {\n    \"Name\": \"Postbox\",\n    \"Count\": 179,\n    \"Percentage\": 0.2,\n    \"AvgPercentage\": 0.006,\n    \"Versions\": [\n      {\n        \"Name\": \"Postbox\",\n        \"Count\": 179,\n        \"Percentage\": 0.2,\n        \"AvgPercentage\": 0.006\n      }\n    ]\n  },\n  {\n    \"Name\": \"Thunderbird\",\n    \"Count\": 121,\n    \"Percentage\": 0,\n    \"AvgPercentage\": 1.098,\n    \"Versions\": [\n      {\n        \"Name\": \"Thunderbird 14\",\n        \"Count\": 3,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Thunderbird 11\",\n        \"Count\": 3,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Thunderbird 24\",\n        \"Count\": 58,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Thunderbird 17\",\n        \"Count\": 43,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Thunderbird 10\",\n        \"Count\": 1,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Thunderbird 16\",\n        \"Count\": 1,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Thunderbird 3\",\n        \"Count\": 9,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 1.022\n      },\n      {\n        \"Name\": \"Thunderbird 2\",\n        \"Count\": 3,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.076\n      }\n    ]\n  },\n  {\n    \"Name\": \"BlackBerry\",\n    \"Count\": 66,\n    \"Percentage\": 0.1,\n    \"AvgPercentage\": 0.026,\n    \"Versions\": [\n      {\n        \"Name\": \"BlackBerry Z10\",\n        \"Count\": 64,\n        \"Percentage\": 0.1,\n        \"AvgPercentage\": 0\n      },\n      {\n        \"Name\": \"Other BlackBerry\",\n        \"Count\": 2,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.026\n      }\n    ]\n  },\n  {\n    \"Name\": \"AOL Mail\",\n    \"Count\": 44,\n    \"Percentage\": 0,\n    \"AvgPercentage\": 0.671,\n    \"Versions\": [\n      {\n        \"Name\": \"Using Android\",\n        \"Count\": 2,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.006\n      },\n      {\n        \"Name\": \"Using Explorer\",\n        \"Count\": 7,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.644\n      },\n      {\n        \"Name\": \"Using Firefox\",\n        \"Count\": 2,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.016\n      },\n      {\n        \"Name\": \"Using Chrome\",\n        \"Count\": 28,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.004\n      },\n      {\n        \"Name\": \"Other\",\n        \"Count\": 5,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.001\n      }\n    ]\n  },\n  {\n    \"Name\": \"Entourage\",\n    \"Count\": 1,\n    \"Percentage\": 0,\n    \"AvgPercentage\": 0.326,\n    \"Versions\": [\n      {\n        \"Name\": \"Entourage\",\n        \"Count\": 1,\n        \"Percentage\": 0,\n        \"AvgPercentage\": 0.326\n      }\n    ]\n  }\n]\n","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f50f5649b951900c897b3","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"}],"url":"/Campaigns/:Guid/MailClientUsage"},"body":"The Mail Client Usage report provides a complete breakdown of the different email clients used to view an email. The report breaks down email clients by different versions, provides a percentage of each client share across the whole campaign, and an average percentage against all Litmus' data for comparison.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T20:13:41.904Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":17,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"mail-client-usage-report","sync_unique":"","title":"Mail client usage report","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getMail client usage report


Path Params

Guid:
required
string
The Mail Client Usage report provides a complete breakdown of the different email clients used to view an email. The report breaks down email clients by different versions, provides a percentage of each client share across the whole campaign, and an average percentage against all Litmus' data for comparison.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



The Mail Client Usage report provides a complete breakdown of the different email clients used to view an email. The report breaks down email clients by different versions, provides a percentage of each client share across the whole campaign, and an average percentage against all Litmus' data for comparison.
{"__v":0,"_id":"565f517d649b951900c897b4","api":{"examples":{"codes":[{"language":"curl","code":"curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/GroupUsageReport\n","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"ClientType\": \"Mobile\",\n    \"Total\": 10329,\n    \"Percentage\": 9\n  },\n  {\n    \"ClientType\": \"Webmail\",\n    \"Total\": 43691,\n    \"Percentage\": 39\n  },\n  {\n    \"ClientType\": \"Desktop\",\n    \"Total\": 58755,\n    \"Percentage\": 52\n  }\n]\n","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f517d649b951900c897b5","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"}],"url":"/Campaigns/:Guid/GroupUsageReport"},"body":"The Group Usage Report breaks down the open data by platform: Mobile, Webmail, Desktop, Other / Unknown.  For more information on how we determine these platforms see: [How are mobile, desktop and webmail categories defined?](https://litmus.com/help/analytics/category-definitions/)","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T20:15:57.873Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":18,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"group-usage-report","sync_unique":"","title":"Group usage report","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getGroup usage report


Path Params

Guid:
required
string
The Group Usage Report breaks down the open data by platform: Mobile, Webmail, Desktop, Other / Unknown. For more information on how we determine these platforms see: [How are mobile, desktop and webmail categories defined?](https://litmus.com/help/analytics/category-definitions/)

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



The Group Usage Report breaks down the open data by platform: Mobile, Webmail, Desktop, Other / Unknown. For more information on how we determine these platforms see: [How are mobile, desktop and webmail categories defined?](https://litmus.com/help/analytics/category-definitions/)
{"__v":0,"_id":"565f520b413e06170093df23","api":{"examples":{"codes":[{"language":"text","code":"curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/BrowserUsageReport\n","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"ClientType\": \"Using Firefox\",\n    \"Total\": 1749,\n    \"Percentage\": 4\n  },\n  {\n    \"ClientType\": \"Using Explorer\",\n    \"Total\": 126,\n    \"Percentage\": 0\n  },\n  {\n    \"ClientType\": \"Via Gmail's Image Cache\",\n    \"Total\": 35909,\n    \"Percentage\": 83\n  },\n  {\n    \"ClientType\": \"Using Chrome\",\n    \"Total\": 5045,\n    \"Percentage\": 12\n  },\n  {\n    \"ClientType\": \"Using Safari\",\n    \"Total\": 469,\n    \"Percentage\": 1\n  }\n]\n"}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f520b413e06170093df24","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"}],"url":"/Campaigns/:Guid/BrowserUsageReport"},"body":"The Browser Usage Report breaks down the open data by the web browser that was used. However, this only applies to web based email clients.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T20:18:19.263Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":19,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"browser-usage-report","sync_unique":"","title":"Browser usage report","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getBrowser usage report


Path Params

Guid:
required
string
The Browser Usage Report breaks down the open data by the web browser that was used. However, this only applies to web based email clients.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



The Browser Usage Report breaks down the open data by the web browser that was used. However, this only applies to web based email clients.
{"__v":0,"_id":"565f52817f93280d0052cf9a","api":{"examples":{"codes":[{"language":"curl","code":"curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/RenderingCategoryReport","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"RenderingType\": \"Other\",\n    \"Total\": 42387,\n    \"Percentage\": 36\n  },\n  {\n    \"RenderingType\": \"Webkit\",\n    \"Total\": 49868,\n    \"Percentage\": 43\n  },\n  {\n    \"RenderingType\": \"Firefox\",\n    \"Total\": 2050,\n    \"Percentage\": 2\n  },\n  {\n    \"RenderingType\": \"MSWord\",\n    \"Total\": 19871,\n    \"Percentage\": 17\n  },\n  {\n    \"RenderingType\": \"Explorer\",\n    \"Total\": 2068,\n    \"Percentage\": 2\n  }\n]\n","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f52817f93280d0052cf9b","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"}],"url":"/Campaigns/:Guid/RenderingCategoryReport"},"body":"The Rendering Category Report breaks down the open data by the core rendering engine that was used.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T20:20:17.896Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":20,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"rendering-category-report","sync_unique":"","title":"Rendering category report","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getRendering category report


Path Params

Guid:
required
string
The Rendering Category Report breaks down the open data by the core rendering engine that was used.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



The Rendering Category Report breaks down the open data by the core rendering engine that was used.
{"__v":2,"_id":"565f2a25413e06170093de9a","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Activity Reports provide information on print and forward activity we've detected on a campaign.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T17:28:05.598Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":21,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"activity-reports","sync_unique":"","title":"Activity reports","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Activity reports


Activity Reports provide information on print and forward activity we've detected on a campaign.
Activity Reports provide information on print and forward activity we've detected on a campaign.
{"__v":0,"_id":"565f536a0dc99e1900f24c39","api":{"examples":{"codes":[{"language":"curl","code":"curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/ActivitySummaryReport\n","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"PrintCount\": 44,\n  \"ForwardCount\": 320,\n  \"PrintAvgCount\": 12,\n  \"ForwardAvgCount\": 88\n}","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f536a0dc99e1900f24c3a","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"}],"url":"/Campaigns/:Guid/ActivitySummaryReport"},"body":"Use the Activity Summary report to display how many natural prints or forwards have been recorded.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T20:24:10.233Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":22,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"activity-summary-report","sync_unique":"","title":"Activity summary report","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getActivity summary report


Path Params

Guid:
required
string
Use the Activity Summary report to display how many natural prints or forwards have been recorded.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Use the Activity Summary report to display how many natural prints or forwards have been recorded.
{"__v":0,"_id":"565f53d6413e06170093df2d","api":{"examples":{"codes":[{"language":"curl","code":"curl -u apikey:password https://analytics-api.litmus.com/api/v1/Campaigns/xyz123/ActivityReport","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"[\n  {\n    \"Type\": \"Forwarded\",\n    \"Detail\": \"hello@litmus.com\",\n    \"RegionCode\": \"CaliforniaUnited States\",\n    \"RegionName\": \"California\",\n    \"City\": \"Mountain View\",\n    \"Country\": \"United States\",\n    \"Latitude\": 37.4192047,\n    \"Longitude\": -122.0574,\n    \"MailClient\": \"Other\",\n    \"CreatedAt\": \"2015-03-26T17:24:40\"\n  },\n  {\n    \"Type\": \"Printed\",\n    \"Detail\": \"resellers@litmus.com\",\n    \"RegionCode\": \"CaliforniaUnited States\",\n    \"RegionName\": \"California\",\n    \"City\": \"Mountain View\",\n    \"Country\": \"United States\",\n    \"Latitude\": 37.4192047,\n    \"Longitude\": -122.0574,\n    \"MailClient\": \"Other\",\n    \"CreatedAt\": \"2015-03-26T17:24:39\"\n  },\n  {\n    \"Type\": \"Printed\",\n    \"Detail\": \"hello@litmus.com\",\n    \"RegionCode\": \"CaliforniaUnited States\",\n    \"RegionName\": \"California\",\n    \"City\": \"Mountain View\",\n    \"Country\": \"United States\",\n    \"Latitude\": 37.4192047,\n    \"Longitude\": -122.0574,\n    \"MailClient\": \"Web version\",\n    \"CreatedAt\": \"2015-03-26T14:43:44\"\n  }\n]","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565f53d6413e06170093df2e","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"}],"url":"/Campaigns/:Guid/ActivityReport"},"body":"Use the Activity Report to fetch the last 25 print / forward activities on a campaign.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T20:25:58.991Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":23,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"activity-report","sync_unique":"","title":"Activity report","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getActivity report


Path Params

Guid:
required
string
Use the Activity Report to fetch the last 25 print / forward activities on a campaign.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Use the Activity Report to fetch the last 25 print / forward activities on a campaign.
{"__v":2,"_id":"565f2d06bca87d0d006bc688","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"If you want to access the underlying raw data behind Email Analytics, first check out the [data fields available via Email Analytics](https://litmus.com/help/analytics/csv-export-data-fields/).\n\nThere are three methods for retrieving the raw data for an Email Analytics campaign.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-02T17:40:22.543Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":24,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"getting-raw-data","sync_unique":"","title":"Getting raw data","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Getting raw data


If you want to access the underlying raw data behind Email Analytics, first check out the [data fields available via Email Analytics](https://litmus.com/help/analytics/csv-export-data-fields/). There are three methods for retrieving the raw data for an Email Analytics campaign.
If you want to access the underlying raw data behind Email Analytics, first check out the [data fields available via Email Analytics](https://litmus.com/help/analytics/csv-export-data-fields/). There are three methods for retrieving the raw data for an Email Analytics campaign.
{"__v":0,"_id":"565fecd5649b951900c89880","api":{"examples":{"codes":[{"language":"curl","code":"curl -X PUT \\\n-d '{ \"Email\" : \"hello@litmus.com\" }' \\\n-u apikey:password \\\n-H \"Content-type: application/json\" \\\nhttps://analytics-api.litmus.com/api/v1/Campaigns/xyz123/EmailExportLink","name":""}]},"results":{"codes":[{"language":"text","code":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565fecd5649b951900c89882","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"},{"_id":"565fecd5649b951900c89881","required":true,"desc":"","default":"","type":"string","name":"Email","in":"body"}],"url":"/Campaigns/:Guid/EmailExportLink"},"body":"You can use the API to submit a request for a full export to be delivered via email.","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-03T07:18:45.254Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":25,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"request-the-data-via-email","sync_unique":"","title":"Request the data via email","type":"put","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

putRequest the data via email


Path Params

Guid:
required
string

Body Params

Email:
required
string
You can use the API to submit a request for a full export to be delivered via email.

User Information

Try It Out

put
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples



You can use the API to submit a request for a full export to be delivered via email.
{"__v":0,"_id":"565fed11de5dc50d00acff47","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"body":"Litmus can deliver data from your campaigns to a FTP or SFTP site you provide.  You can learn more about our [FTP data feeds](https://litmus.com/help/analytics/ea-ftp-feeds/).\n\nAll FTP / SFTP sites need to be first vetted by Litmus to prevent incorrect transmissions or man-in-the-middle attacks.  If you are interested in using this feature please contact us at [resellers@litmus.com](mailto:resellers@litmus.com).\n\nFor FTP related API methods - including Create, Update, and Get calls - see the reference documentation:  https://analytics-api.litmus.com/#!/FtpSites","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-03T07:19:45.328Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":26,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"ftp-sftp","sync_unique":"","title":"FTP / SFTP","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

FTP / SFTP


Litmus can deliver data from your campaigns to a FTP or SFTP site you provide. You can learn more about our [FTP data feeds](https://litmus.com/help/analytics/ea-ftp-feeds/). All FTP / SFTP sites need to be first vetted by Litmus to prevent incorrect transmissions or man-in-the-middle attacks. If you are interested in using this feature please contact us at [resellers@litmus.com](mailto:resellers@litmus.com). For FTP related API methods - including Create, Update, and Get calls - see the reference documentation: https://analytics-api.litmus.com/#!/FtpSites
Litmus can deliver data from your campaigns to a FTP or SFTP site you provide. You can learn more about our [FTP data feeds](https://litmus.com/help/analytics/ea-ftp-feeds/). All FTP / SFTP sites need to be first vetted by Litmus to prevent incorrect transmissions or man-in-the-middle attacks. If you are interested in using this feature please contact us at [resellers@litmus.com](mailto:resellers@litmus.com). For FTP related API methods - including Create, Update, and Get calls - see the reference documentation: https://analytics-api.litmus.com/#!/FtpSites
{"__v":0,"_id":"565fee15b182df0d00d4e45d","api":{"examples":{"codes":[{"language":"curl","code":"curl -X PUT \\\n\t-d '{ \"NotificationUrl\" : \"http://some-url-you-host\" }' \\\n\t-u apikey:password \\\n\t-H \"Content-type: application/json\" \\\n\thttps://analytics-api.litmus.com/api/v1/Campaigns/{guid}/Subscribe","name":""}]},"results":{"codes":[{"status":200,"language":"json","code":"{\n\t  \"Type\": \"Notification\",\n\t  \"MessageId\": \"1d35d4be-6a51-593d-8c53-999b05ec7577\",\n\t  \"TopicArn\": \"arn:aws:sns:us-east-1:705477198468:ea_0xcafpsy\",\n\t  \"Message\": \"{\\n\\\"created_at\\\" : \\\"2015-01-06T05:06:53\\\",\\n\\\"email_address\\\" : \\\"user@something.com\\\",\\n\\\"custom_type\\\" : \\\"\\\",\\n\\\"mail_client\\\" : \\\"Outlook\\\",\\n\\\"mail_client_specific\\\" : \\\"Outlook 2007\\\",\\n\\\"rendering_engine\\\" : \\\"msword\\\",\\n\\\"platform\\\" : \\\"desktop\\\",\\n\\\"read_seconds\\\" : \\\"20\\\",\\n\\\"read_category\\\" : \\\"Read\\\",\\n\\\"city\\\" : \\\"Seattle\\\",\\n\\\"region\\\" : \\\"Washington\\\",\\n\\\"country\\\" : \\\"United States\\\",\\n\\\"long\\\" : \\\"-122.299499511719\\\",\\n\\\"lat\\\" : \\\"47.5838928222656\\\",\\n\\\"referrer\\\" : \\\"\\\",\\n\\\"user_agent\\\" : \\\"\\\",\\n\\\"ip_address\\\" : \\\"127.0.0.1\\\",\\n\\\"campaign_guid\\\" : \\\"someguid\\\",\\n\\\"activity_type\\\" : \\\"Read\\\"\\n}\",\n\t  \"Timestamp\": \"2015-01-06T05:07:09.072Z\",\n\t  \"SignatureVersion\": \"1\",\n\t  \"Signature\": \"uokI+6Io0g2k+zRYlemm1sSeb4r39aB+7VuRv701GrSN0IBmgTd3ANz2a3uKVNIul7Uw226APQr+Q6U20yGVXTSffi587CWkmIlO0ZyKcZHNgb1k1mzypo3GPIO649pbpPaErod3mna8dXXeM6Oe3nY2J4sI42XnCA4o1olvna53dWbWWORGD6FMl3Vf2AmInI1aOD+dFAEN79tHM6BNOBqqW4t5GPrdKhsOIrHyOMTob\\/bPTN00e8W8Hd7qmCmIBB6KOPmsjn9sNisILYSqtrEUGsFO8tWzInvZhQk1l3r2bQNzUzk2ZvD8RK4RqPYlSVNCle10DxC5tCJtaF98Ng==\",\n\t  \"SigningCertURL\": \"https:\\/\\/sns.us-east-1.amazonaws.com\\/SimpleNotificationService-d6d679a1d18e95c2f9ffcf11f4f9e198.pem\",\n\t  \"UnsubscribeURL\": \"https:\\/\\/sns.us-east-1.amazonaws.com\\/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-1:705477198468:ea_0xcafpsy:d5c3358f-0f24-4cb4-96bf-ee2a72a97abf\"\n\t}","name":""}]},"settings":"565f2ff3413e06170093debc","auth":"required","params":[{"_id":"565fee15b182df0d00d4e45f","required":true,"desc":"","default":"","type":"string","name":"Guid","in":"path"},{"_id":"565fee15b182df0d00d4e45e","required":true,"desc":"","default":"","type":"string","name":"NotificationUrl","in":"body"}],"url":"/Campaigns/:Guid/Subscribe"},"body":"Using <a href=\"http://aws.amazon.com/sns/\" target=\"_blank\">Amazon SNS</a>, Email Analytics provides an option to subscribe to a campaign and receive near real-time callbacks for each open.  Note:  In order to use this method you will need to be able to handle the volume of HTTP requests that will be generated.\n\nTo use Email Analytics callbcks:\n\n1\\. Subscribe to the campaign you want callbacks for using the API call:\n\n2\\. Respond to the Amazon SNS subscription confirmation:\n\nAfter you subscribe via the API call Amazon will POST a subscription confirmation to your URL.  You will need to confirm receipt of this in order to receive future POST requests.  See the [Amazon Documenation](http://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.html#SendMessageToHttp.prepare) for how to do this properly.  \n\n3\\. Process incoming hits\n\nOnce your subscription is confirmed you will receive a POST for each open that Email Analytics recieved.  The posts will be in a format similar to this:\n\nThe `Message` field is a json representation of a single open.  [You can read more about the data field definitions](https://litmus.com/help/analytics/csv-export-data-fields/).","category":"565f29350dc99e1900f24ba2","createdAt":"2015-12-03T07:24:05.967Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":27,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"real-time-callbacks","sync_unique":"","title":"Real-time callbacks","type":"put","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

putReal-time callbacks


Path Params

Guid:
required
string

Body Params

NotificationUrl:
required
string
Using <a href="http://aws.amazon.com/sns/" target="_blank">Amazon SNS</a>, Email Analytics provides an option to subscribe to a campaign and receive near real-time callbacks for each open. Note: In order to use this method you will need to be able to handle the volume of HTTP requests that will be generated. To use Email Analytics callbcks: 1\. Subscribe to the campaign you want callbacks for using the API call: 2\. Respond to the Amazon SNS subscription confirmation: After you subscribe via the API call Amazon will POST a subscription confirmation to your URL. You will need to confirm receipt of this in order to receive future POST requests. See the [Amazon Documenation](http://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.html#SendMessageToHttp.prepare) for how to do this properly. 3\. Process incoming hits Once your subscription is confirmed you will receive a POST for each open that Email Analytics recieved. The posts will be in a format similar to this: The `Message` field is a json representation of a single open. [You can read more about the data field definitions](https://litmus.com/help/analytics/csv-export-data-fields/).

User Information

Try It Out

put
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Using <a href="http://aws.amazon.com/sns/" target="_blank">Amazon SNS</a>, Email Analytics provides an option to subscribe to a campaign and receive near real-time callbacks for each open. Note: In order to use this method you will need to be able to handle the volume of HTTP requests that will be generated. To use Email Analytics callbcks: 1\. Subscribe to the campaign you want callbacks for using the API call: 2\. Respond to the Amazon SNS subscription confirmation: After you subscribe via the API call Amazon will POST a subscription confirmation to your URL. You will need to confirm receipt of this in order to receive future POST requests. See the [Amazon Documenation](http://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.html#SendMessageToHttp.prepare) for how to do this properly. 3\. Process incoming hits Once your subscription is confirmed you will receive a POST for each open that Email Analytics recieved. The posts will be in a format similar to this: The `Message` field is a json representation of a single open. [You can read more about the data field definitions](https://litmus.com/help/analytics/csv-export-data-fields/).
{"__v":18,"_id":"565f2d6123fd5f0d00a12a90","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This is our legacy Previews API, if you're starting a new project and require the fastest captures and a simpler integration consider using our newer [Instant API](doc:instant-api)\"\n}\n[/block]\n##Core Functionality\n\nFor all Email Previews tests you will follow the same basic process:\n\n1. **[Create](#section-start-your-test)**: Create a new test and get a unique test guid.\n2. **[Send](#section-send-us-your-email)**: Send in your email, HTML, or URL.\n3. **[Verify](#section-verify-your-test)**: Verify that we have received your test and are processing it.\n4. **[Process Results](#section-process-results)**: Once you receive your results via [polling](#section-polling) or [callbacks](#section-callbacks) you can provide them to your end user.\n\n\n##Additional Functionality\n\nIn 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:\n\n*  **[Link Check](#section-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.\n\n*  **[Code Analysis](#section-code-analysis)**: The Code Analysis feature provides a compatibility report for your email’s HTML/CSS within several email clients.\n\n* **[Spam Testing](#section-spam-testing)**:  Include Litmus' spam seed addresses in your Email Previews test to receive valuable information about your email.\n\n\n##Integration Assistance\n\nThere are few additional areas of resources to look at when building your integration with the Litmus API:\n\n*  **[Polling](#section-polling)**: To request information from Litmus.\n*  **[Callbacks](#section-callbacks)**:  To receive information from Litmus as soon as your `EmailTests` have completed.\n*  **[Index](doc:index)**: An explanation of some of the most important attributes in the API.\n*  **[Generating and Using User GUIDs](#section-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.\n*  **See the API Documentation at work**: Visit https://previews-api.litmus.com/\n\n\n#Start Your Test\n\nStart a Litmus email test by sending a `POST` request to https://previews-api.litmus.com/api/v1/EmailTests\n\nYou 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](doc:testing-applications) for GET TestingApplications.\n\nAn example of creating an email preview for all `TestingApplications` looks like this:\n\n```sh\ncurl https://previews-api.litmus.com/api/v1/EmailTests \\\n  -u username:password \\\n  -X POST \\\n  -H \"Content-type: application/json\" \\\n  -d '{}'\n```\n\n\nAn example of creating an email preview for only one `TestingApplications` for Outlook 2010 (\"ol2010\") looks like this:\n\n```sh\ncurl https://previews-api.litmus.com/api/v1/EmailTests \\\n  -u username:password \\\n  -X POST \\\n  -H \"Content-type: application/json\" \\\n  -d '{\"TestingApplications\": [\n    { \"ApplicationName\": \"OL2010\" }\n  ]\n}'\n```\n\nHere is an example of a response from Litmus:\n\n```json\n{\n  \"TestingApplications\": [\n    {\n      \"State\": \"pending\",\n      \"WindowImageContentBlocking\": \"s3.amazonaws.com\",\n      \"FullpageImageThumb\": \"s3.amazonaws.com\",\n      \"BusinessOrPopular\": true,\n      \"WindowImageThumbNoContentBlocking\": \"s3.amazonaws.com\",\n      \"Completed\": false,\n      \"FullpageImage\": \"s3.amazonaws.com\",\n      \"FoundInSpam\": false,\n      \"SupportsSpamScoring\": null,\n      \"Status\": 0,\n      \"WindowImageNoContentBlocking\": \"s3.amazonaws.com\",\n      \"PlatformName\": \"Windows\",\n      \"AverageTimeToProcess\": 38,\n      \"SpamHeaders\": [],\n      \"WindowImageThumb\": \"s3.amazonaws.com\",\n      \"RenderedHtmlUrl\": null,\n      \"PlatformLongName\": \"Microsoft Windows\",\n      \"FullpageImageThumbContentBlocking\": \"s3.amazonaws.com\",\n      \"WindowImage\": \"s3.amazonaws.com\",\n      \"FullpageImageContentBlocking\": \"s3.amazonaws.com\",\n      \"SupportsContentBlocking\": true,\n      \"ApplicationName\": \"OL2010\",\n      \"FullpageImageThumbNoContentBlocking\": \"s3.amazonaws.com\",\n      \"SpamScore\": 0.0,\n      \"DesktopClient\": true,\n      \"WindowImageThumbContentBlocking\": \"s3.amazonaws.com\",\n      \"Id\": your-result-id-here,\n      \"ResultType\": 0,\n      \"FullpageImageNoContentBlocking\": \"s3.amazonaws.com\",\n      \"ApplicationLongName\": \"Outlook 2010\"\n    }\n  ],\n  \"State\": \"waiting\",\n  \"InboxGuid\": your-inbox-guid-here,\n  \"Id\": your-test-set-id-here,\n  \"Source\": \"https://s3.amazonaws.com/sitevista/\",\n  \"Subject\": \"\",\n  \"Html\": \"https://html.litmus.com/email/?url=/sitevista/\",\n  \"ZipFile\": \"http://zip.litmus.com/resellers/?guid=\"your-guid-here,\n  \"TestType\": 0,\n  \"Sandbox\": false,\n  \"UserGuid\": null,\n  \"Error\": false,\n  \"ErrorMessage\": null\n}\n```\n\n#Send Us Your Email\n\nThe response you will receive contains some important information, including the`InboxGuid`.  The `InboxGuid` is a unique identifier for this test.  You will use the `InboxGuid` to create and send an email to `InboxGuid`@emailtests.com.  When we receive your email at that unique email address we will know to associate it with the test you created.\n\n**Note:** The email address `InboxGuid`@emailtests.com must appear in the email headers in the To:, CC:, or BCC: field in order for us to associate that message with your test.\n\nThe 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.\n\nHead back up [above](#section-start-your-test) to see the a sample of `InboxGuid` and `Id` from a sample Litmus response.\n\n\n#Verify Your Test\n\nAt this point you will need to ensure that your email has been received and is being processed.\n\nMake 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.\n\nHere is an example of the `GET` request:\n\n```sh\ncurl -u username:password https://previews-api.litmus.com/api/v1/EmailTests/{id}\n```\n\nYour response should look similar to the response you received from your `POST` request.\n\nCheck the `State` field.  There are 4 possible `State`s:\n\n1. **waiting**: Litmus is still waiting to receive your email.  Your test isn't running.\n2. **processing**: Litmus has received your email and is in the process of running your test.\n3. **complete**: Litmus has completed your test.  Your images are ready.\n4. **error**: Something went wrong.  You will have to retest for this client.\n\n####Note:####\nIf 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:\n\n1.  Your message never made it to your unique `InboxGuid` email address.  Contact support at <resellers@litmus.com> and/or contact your email service provider.\n2.  Your email service is providing placeholder data in the To:, CC:, and BCC: fields.  We cannot associate your email with your unique `InboxGuid` if `InboxGuid`@emailtests.com doesn't appear in the email headers.  Contact your email service provider for additional assistance.\n\n\n#Process Results\n\nEach 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:\n\n##Has the result completed?\nIf you [verified](#section-verify-your-test) that your result's `Completed` property is `true`, it is safe to use the result to find its images (covered below).\n\n##Is the result a type with captures?\nIf result's ResultType property is `email`, it will have capture images. If it's `spam`, it won't.\n\nIf the answer to the above questions is \"yes,\" then you can move onto deciding which properties contain the capture images you want.\n\n##Choosing the right images\nIf your result's SupportsContentBlocking property is `true`, you should use the following properties:\n\n```sh\nWindowImageNoContentBlocking\nWindowImageContentBlocking\nFullpageImageNoContentBlocking\nFullpageImageContentBlocking\n```\n\n```sh\nWindowImageNoContentBlockingThumb\nWindowImageContentBlockingThumb\nFullpageImageNoContentBlockingThumb\nFullpageImageContentBlockingThumb\n```\n\nIf SupportsContentBlocking is `false`, you should use the following properties:\n\n```sh\nWindowImage\nFullpageImage\n```\n\n```sh\nWindowImageThumb\nFullpageImageThumb\n```\n\n#Link Check\n\nThe 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.\"\n\nCreate a LinkTest by sending a POST request that includes your email's HTML to our API:\n\n```sh\ncurl https://previews-api.litmus.com/api/v1/LinkTests \\\n  -u username:password \\\n  -i \\\n  -X POST \\\n  -H \"Content-type: application/json\" \\\n  -d \"\\\"<div><a href='http://www.litmus.com?utm_source=twitter&utm_term=oct'>Litmus</a></div>\\\"\"\n  ```\n\n**Note**: There are quotes surrounding the HTML\n\n**Important**:  You should only paste the HTML portion of your email - no subject line, plain text parts etc.\n\nJust 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`:\n\n```sh\ncurl -u username:password https://previews-api.litmus.com/api/v1/LinkTests/{id}\n```\n\nOnce the `State` of the test is `Complete` you can parse through the object to get the result of your test.\n\n##Understanding Link Check Results\n\n**LinkTest Object**\n\n| Attribute    | Description                                                                           |\n|--------------|---------------------------------------------------------------------------------------|\n| Id           | Unique Id for this LinkTest.  Use this value to poll for results.                     |\n| Links        | Collection of Link Objects with details about the links we've detected in your email. |\n| SourceUrl    | The HTML source that was used for this test.                                          |\n| ImageUrl     | A screenshot of the rendered HTML.                                                   |\n| State        | Processing, Complete, or Error                                                         |\n| Error        | Boolean value indicating if there was an error processing this LinkTest               |\n| ErrorMessage | Details about the error if Error == true.                                             |\n\n</br>\n\n**Link Object**\n\n| Attribute                 | Description                                                                                                                                         |\n|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|\n| Url                       | The Url for this Link.                                                                                                                              |\n| IsValid                   | If the Url returned a 200 via an Http request.                                                                                                      |\n| Exception                 | If the Url did not return a 200 - what error did it return.                                                                                         |\n| IsBlackListed             | Is the Url listed on common blacklists?                                                                                                             |\n| HasGoogleAnalytics        | Does the Url have Google Analytics parameters?                                                                                                      |\n| 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. |\n| PageTtitle                | The title of the page the link leads to.                                                                                                            |\n| TopLeftX                  | X position of the link in the rendered HTML.                                                                                                        |\n| TopLeftY                  | Y position of the link in the rendered HTML.                                                                                                        |\n| GoogleAnalyticsParameters | If the link does have GoogleAnalyticsParameters this will contain a parsed collection of those parameters.                                          |\n| ThumbnailsUrl             | A small screenshot of the page the the link leads to.\n\n\n#Code Analysis\n\nThe 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.\n\nTo retrieve a list of all `ApplicationName` fields for `CodeAnalysisByTestingApplications` place a GET request to https://previews-api.litmus.com/api/v1/TestingApplications\n\nSubmit your CodeAnalysis request by POST request:\n\n```sh\ncurl https://previews-api.litmus.com/api/v1/CodeAnalysis \\\n  -u username:password \\\n  -i \\\n  -X POST \\\n  -H \"Content-type: application/json\" \\\n  -d \"\\\"<div><a href='http://www.litmus.com?utm_source=twitter&utm_term=oct'>Litmus</a></div>\\\"\"\n```\n\nYou can request a CodeAnalysis test for only certain applications by making a call to `CodeAnalysisByTestingApplications`:\n\n```sh\ncurl https://previews-api.litmus.com/api/v1/CodeAnalysisByTestingApplications \\\n  -u username:password \\\n  -i \\\n  -X POST \\\n  -H \"Content-type: application/json\" \\\n  -d '{\"Html\": \"<h1>Test</h1><p><a href=\\\"http://www.litmus.com\\\">Litmus</a></p>\",\"TestingApplications\": [ \"ol2010\"]}'\n  ```\n\n  **Note**: Quotes should be surrounding the HTML\n  **Important**: You should only paste the HTML portion of your email - no subject line, plain text parts etc.\n\n##Understanding CodeAnalysis Results\n\n**CodeAnalysisTest**\n\n| Attribute               | Description                                                             |\n|-------------------------|-------------------------------------------------------------------------|\n| CompatibilityProblems   | A collection of compatibility problems that we found in your HTML.      |\n| CompatibilityRulesCount | The total number of compatibility rules we validated your HTML against. |\n| HtmlProblems            | A collection of HTML format and syntax problems we found in your HTML.  |\n\n</br>\n\n**CodeAnalysisPotentialProblems**\n\n| Attribute   | Description                                                  |\n|-------------|--------------------------------------------------------------|\n| LineNumber  | The line in the HTML where this problem was found.           |\n| Severity    | 0 or 1 where 0 is less severe an issue and 1 is more severe. |\n| Description | A text description of the problem.                           |\n\n</br>\n\n**CodeAnalysisHtmlValidation**\n\n| Attribute   | Description                                        |\n|-------------|----------------------------------------------------|\n| LineNumber  | The line in the HTML where this problem was found. |\n| Description | A text description of the problem.                 |\n\n</br>\n\n\n#Spam Testing\n\nThe process for Spam Testing is similar to the process for Email Previews, but there are a few additional steps.\n\n##Include Spam TestingApplications\n\nMake sure you include all `TestingApplications` that have a `ResultType` of `1` or `Spam`.  To retrieve all `TestingApplications` follow the steps listed [here](doc:testing-applications) for GET TestingApplications.  If you want to include all `TestingApplications` send an empty EmailTest object.  \n\n##Include Spam Seed Addresses\n\nIn addition to sending your email to `InboxGuid`@emailtests.com, you will need to send the email to Litmus' spam seed addresses.  To receive a list of spam seed addresses follow the steps [here](doc:get-spamseedaddresses) for GET SpamSeedAddresses.  If you skip this step your email will not be tested for spam.\n\n##Verify\n\n[Verify](#section-verify-your-test) that we have received your test and are processing it.\n\n##Process Results\n\n[Process](#section-process-results) your results and provide them to your end user.  Once you receive your results via [polling](#section-polling) or [callbacks](#section-callbacks) you can provide them to your end user\n\n###Understanding Spam Test Results\n\n**SpamHeader**\n\n| Attribute   | Description                                                                                                                |\n|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Key         | String key returned by the spam provider for this header.                                                                                                  |\n| Id          | Integer unique id in Litmus for this header.                                                                                                               |\n| Description | Text description in English of what potential issue this header indicates.                                                                                 |\n| 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. |\n\n</br>\n\n\n##Polling\n\nOnce 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.\n\nTo 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.\n\n\n##Callbacks\n\nTo 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 <resellers@litmus.com>.\n\nWe 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.\n\nOnce we have your URL stored in our system we will POST data to that URL every time one of your individual results completes.\n\nHere is an example of what your POST request might look like:\n\n```cs\nvar emailTest = new EmailTest();\n\n// Create our list and make space for two clients\nemailTest.Results = new Client[3]\n// Create a Client object within the first space\nemailTest.Results[0] = new Client\n// Assign Outlook 2003's ApplicationName to that new Client object\nemailTest.Results[0].ApplicationName = \"OL2010\"\n// Repeat for Spam Asassin\nemailTest.Results[2] = new Client\nemailTest.Results[2].ApplicationName = \"SPAMASSASSIN3\"\nemailTest = LitmusApi.CreateEmailTest(\"api-key\", \"api-pass\", emailTest);\n```\n\nAs soon as the `Completed` becomes `true` we will POST data to your URL.\n\nHere is an example of what that data might look like:\n\n```xml\n<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<TestResult type=\"mail\">\n  <Id>your-id</Id>\n  <ApiId>OL2010</ApiId>\n  <SupportsContentBlocking>False</SupportsContentBlocking>\n  <ResultImageSet>\n    <ImagesOnUrls>\n      <WindowUrls>\n        <ImageUrl>s3.amazonaws.com/resultcaptures/unique-guid.windowon.png</ImageUrl>\n        <ThumbUrl>s3.amazonaws.com/resultcaptures/unique-guid.windowonthumb.png</ThumbUrl>\n      </WindowUrls>\n      <FullPageUrls>\n        <ImageUrl>s3.amazonaws.com/resultcaptures/unique-guid.fullpageon.png</ImageUrl>\n        <ThumbUrl>s3.amazonaws.com/resultcaptures/unique-guid.fullpageonthumb.png</ThumbUrl>\n      </FullPageUrls>\n    </ImagesOnUrls>\n    <ImagesOffUrls>\n      <WindowUrls>\n        <ImageUrl>s3.amazonaws.com/resultcaptures/unique-guid.windowon.png</ImageUrl>\n        <ThumbUrl>s3.amazonaws.com/resultcaptures/unique-guid.windowonthumb.png</ThumbUrl>\n      </WindowUrls>\n      <FullPageUrls>\n        <ImageUrl>s3.amazonaws.com/resultcaptures/unique-guid.fullpageon.png</ImageUrl>\n        <ThumbUrl>s3.amazonaws.com/resultcaptures/unique-guid.fullpageonthumb.png</ThumbUrl>\n      </FullPageUrls>\n    </ImagesOffUrls>\n  </ResultImageSet>\n  <SpamResult />\n  <State>Completed</State>\n  <CallbackUrl>http://mysite.com/callback/</CallbackUrl>\n</TestResult>\n```\n\nFor spam tests, the xml will have the following format:\n\n```xml\n<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<TestResult type=\"spam\">\n  <Id>554</Id>\n  <ApiId>SPAMASSASSIN3</ApiId>\n  <SupportsContentBlocking>false</SupportsContentBlocking>\n  <ResultImageSet />\n  <SpamResult>\n    <SpamScore>9.4</SpamScore>\n    <IsSpam>True</IsSpam>\n    <SpamHeaders>\n      <SpamHeader>\n        <Key>HTML_FONT_FACE_BAD</Key>\n        <Description>The font face used in your email is not valid.\n        Try validating the HTML of your email using the W3C\n        validator to make sure you are using standard\n        HTML.</Description>\n        <Rating>4</Rating>\n      </SpamHeader>\n      <SpamHeader>\n        <Key>HTML_MESSAGE</Key>\n        <Description>Your email contains HTML content. This won't\n        usually cause you to fail any spam filters.</Description>\n        <Rating>2</Rating>\n      </SpamHeader>\n      <SpamHeader>\n        <Key>URIBL_AB_SURBL</Key>\n        <Description>Your email contains a URL blacklisted by &lt;a\n        href=\"http://www.abusebutler.com/\"&gt;Abuse\n        Butler&lt;/a&gt;.</Description>\n        <Rating>3</Rating>\n      </SpamHeader>\n      <SpamHeader>\n        <Key>URIBL_JP_SURBL</Key>\n        <Description>Your email contains a URL blacklisted by &lt;a\n        href=\"http://www.joewein.de/sw/blacklist.htm\"&gt;jwSpamSpy&lt;/a&gt;.</Description>\n        <Rating>3</Rating>\n      </SpamHeader>\n      <SpamHeader>\n        <Key>URIBL_OB_SURBL</Key>\n        <Description>Your email contains a URL blacklisted by &lt;a\n        href=\"http://www.outblaze.com/\"&gt;Outblaze&lt;/a&gt;.</Description>\n        <Rating>3</Rating>\n      </SpamHeader>\n      <SpamHeader>\n        <Key>URIBL_SC_SURBL</Key>\n        <Description>Your email contains a URL blacklisted by &lt;a\n        href=\"http://www.spamcop.net/\"&gt;SpamCop&lt;/a&gt;.</Description>\n        <Rating>3</Rating>\n      </SpamHeader>\n    </SpamHeaders>\n  </SpamResult>\n <CallbackUrl>http://mysite.com/callback/</CallbackUrl>\n</TestResult>\n```\n\n\n##Generating and Using User GUIDs\n\nIf 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.\n\n**If you are billing your users exclusively on a per-test basis you can ignore this feature**\n\n**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.\n\nThis 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.\n\nDo 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.\n\nSome examples of using Generated User GUIDs in POST requests:\n\n```sh\ncurl https://previews-api.litmus.com/api/v1/EmailTests \\\n  -u username:password \\\n  -X POST \\\n  -H \"Content-type: application/json\" \\\n  -d '{\"UserGuid\":\"SomeGuid\"}'\n```\n\n```sh\ncurl https://previews-api.litmus.com/api/v1/EmailTests \\\n  -u username:password \\\n  -X POST \\\n  -H \"Content-type: application/json\" \\\n  -d '{\"UserGuid\":\"YourUsersGuid\", \\\n    \"TestingApplications\": {[\"ApplicationName\": ...]}\n  }'\n\n```","category":"565f2d3f7f93280d0052cf11","createdAt":"2015-12-02T17:41:53.133Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":0,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"legacy-previews","sync_unique":"","title":"Legacy Previews API","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Legacy Previews API


[block:callout] { "type": "warning", "body": "This is our legacy Previews API, if you're starting a new project and require the fastest captures and a simpler integration consider using our newer [Instant API](doc:instant-api)" } [/block] ##Core Functionality For all Email Previews tests you will follow the same basic process: 1. **[Create](#section-start-your-test)**: Create a new test and get a unique test guid. 2. **[Send](#section-send-us-your-email)**: Send in your email, HTML, or URL. 3. **[Verify](#section-verify-your-test)**: Verify that we have received your test and are processing it. 4. **[Process Results](#section-process-results)**: Once you receive your results via [polling](#section-polling) or [callbacks](#section-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](#section-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](#section-code-analysis)**: The Code Analysis feature provides a compatibility report for your email’s HTML/CSS within several email clients. * **[Spam Testing](#section-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](#section-polling)**: To request information from Litmus. * **[Callbacks](#section-callbacks)**: To receive information from Litmus as soon as your `EmailTests` have completed. * **[Index](doc:index)**: An explanation of some of the most important attributes in the API. * **[Generating and Using User GUIDs](#section-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/ #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](doc:testing-applications) for GET TestingApplications. An example of creating an email preview for all `TestingApplications` looks like this: ```sh 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: ```sh 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 the`InboxGuid`. The `InboxGuid` is a unique identifier for this test. You will use the `InboxGuid` to create and send an email to `InboxGuid`@emailtests.com. 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 `InboxGuid`@emailtests.com 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](#section-start-your-test) 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: ```sh 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 `State`s: 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 <resellers@litmus.com> 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 `InboxGuid`@emailtests.com 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](#section-verify-your-test) 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: ```sh WindowImageNoContentBlocking WindowImageContentBlocking FullpageImageNoContentBlocking FullpageImageContentBlocking ``` ```sh WindowImageNoContentBlockingThumb WindowImageContentBlockingThumb FullpageImageNoContentBlockingThumb FullpageImageContentBlockingThumb ``` If SupportsContentBlocking is `false`, you should use the following properties: ```sh WindowImage FullpageImage ``` ```sh 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: ```sh 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`: ```sh 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. | </br> **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: ```sh 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`: ```sh 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. | </br> **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. | </br> **CodeAnalysisHtmlValidation** | Attribute | Description | |-------------|----------------------------------------------------| | LineNumber | The line in the HTML where this problem was found. | | Description | A text description of the problem. | </br> #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](doc:testing-applications) 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 `InboxGuid`@emailtests.com, you will need to send the email to Litmus' spam seed addresses. To receive a list of spam seed addresses follow the steps [here](doc:get-spamseedaddresses) for GET SpamSeedAddresses. If you skip this step your email will not be tested for spam. ##Verify [Verify](#section-verify-your-test) that we have received your test and are processing it. ##Process Results [Process](#section-process-results) your results and provide them to your end user. Once you receive your results via [polling](#section-polling) or [callbacks](#section-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. | </br> ##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 <resellers@litmus.com>. 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: ```cs 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: ```sh curl https://previews-api.litmus.com/api/v1/EmailTests \ -u username:password \ -X POST \ -H "Content-type: application/json" \ -d '{"UserGuid":"SomeGuid"}' ``` ```sh curl https://previews-api.litmus.com/api/v1/EmailTests \ -u username:password \ -X POST \ -H "Content-type: application/json" \ -d '{"UserGuid":"YourUsersGuid", \ "TestingApplications": {["ApplicationName": ...]} }' ```
[block:callout] { "type": "warning", "body": "This is our legacy Previews API, if you're starting a new project and require the fastest captures and a simpler integration consider using our newer [Instant API](doc:instant-api)" } [/block] ##Core Functionality For all Email Previews tests you will follow the same basic process: 1. **[Create](#section-start-your-test)**: Create a new test and get a unique test guid. 2. **[Send](#section-send-us-your-email)**: Send in your email, HTML, or URL. 3. **[Verify](#section-verify-your-test)**: Verify that we have received your test and are processing it. 4. **[Process Results](#section-process-results)**: Once you receive your results via [polling](#section-polling) or [callbacks](#section-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](#section-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](#section-code-analysis)**: The Code Analysis feature provides a compatibility report for your email’s HTML/CSS within several email clients. * **[Spam Testing](#section-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](#section-polling)**: To request information from Litmus. * **[Callbacks](#section-callbacks)**: To receive information from Litmus as soon as your `EmailTests` have completed. * **[Index](doc:index)**: An explanation of some of the most important attributes in the API. * **[Generating and Using User GUIDs](#section-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/ #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](doc:testing-applications) for GET TestingApplications. An example of creating an email preview for all `TestingApplications` looks like this: ```sh 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: ```sh 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 the`InboxGuid`. The `InboxGuid` is a unique identifier for this test. You will use the `InboxGuid` to create and send an email to `InboxGuid`@emailtests.com. 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 `InboxGuid`@emailtests.com 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](#section-start-your-test) 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: ```sh 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 `State`s: 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 <resellers@litmus.com> 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 `InboxGuid`@emailtests.com 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](#section-verify-your-test) 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: ```sh WindowImageNoContentBlocking WindowImageContentBlocking FullpageImageNoContentBlocking FullpageImageContentBlocking ``` ```sh WindowImageNoContentBlockingThumb WindowImageContentBlockingThumb FullpageImageNoContentBlockingThumb FullpageImageContentBlockingThumb ``` If SupportsContentBlocking is `false`, you should use the following properties: ```sh WindowImage FullpageImage ``` ```sh 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: ```sh 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`: ```sh 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. | </br> **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: ```sh 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`: ```sh 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. | </br> **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. | </br> **CodeAnalysisHtmlValidation** | Attribute | Description | |-------------|----------------------------------------------------| | LineNumber | The line in the HTML where this problem was found. | | Description | A text description of the problem. | </br> #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](doc:testing-applications) 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 `InboxGuid`@emailtests.com, you will need to send the email to Litmus' spam seed addresses. To receive a list of spam seed addresses follow the steps [here](doc:get-spamseedaddresses) for GET SpamSeedAddresses. If you skip this step your email will not be tested for spam. ##Verify [Verify](#section-verify-your-test) that we have received your test and are processing it. ##Process Results [Process](#section-process-results) your results and provide them to your end user. Once you receive your results via [polling](#section-polling) or [callbacks](#section-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. | </br> ##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 <resellers@litmus.com>. 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: ```cs 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: ```sh curl https://previews-api.litmus.com/api/v1/EmailTests \ -u username:password \ -X POST \ -H "Content-type: application/json" \ -d '{"UserGuid":"SomeGuid"}' ``` ```sh curl https://previews-api.litmus.com/api/v1/EmailTests \ -u username:password \ -X POST \ -H "Content-type: application/json" \ -d '{"UserGuid":"YourUsersGuid", \ "TestingApplications": {["ApplicationName": ...]} }' ```
{"__v":8,"_id":"566685b67cc81e0d00253f6f","api":{"auth":"required","examples":{"codes":[{"language":"curl","code":"curl https://previews-api.litmus.com/api/v1/EmailTests \\\n  -u username:password \\\n  -X POST \\\n  -H \"Content-type: application/json\" \\\n  -d '{}'","name":""}]},"params":[],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"TestingApplications\": [\n    {\n      \"State\": \"pending\",\n      \"WindowImageContentBlocking\": \"s3.amazonaws.com\",\n      \"FullpageImageThumb\": \"s3.amazonaws.com\",\n      \"BusinessOrPopular\": true,\n      \"WindowImageThumbNoContentBlocking\": \"s3.amazonaws.com\",\n      \"Completed\": false,\n      \"FullpageImage\": \"s3.amazonaws.com\",\n      \"FoundInSpam\": false,\n      \"SupportsSpamScoring\": null,\n      \"Status\": 0,\n      \"WindowImageNoContentBlocking\": \"s3.amazonaws.com\",\n      \"PlatformName\": \"Windows\",\n      \"AverageTimeToProcess\": 38,\n      \"SpamHeaders\": [],\n      \"WindowImageThumb\": \"s3.amazonaws.com\",\n      \"RenderedHtmlUrl\": null,\n      \"PlatformLongName\": \"Microsoft Windows\",\n      \"FullpageImageThumbContentBlocking\": \"s3.amazonaws.com\",\n      \"WindowImage\": \"s3.amazonaws.com\",\n      \"FullpageImageContentBlocking\": \"s3.amazonaws.com\",\n      \"SupportsContentBlocking\": true,\n      \"ApplicationName\": \"OL2010\",\n      \"FullpageImageThumbNoContentBlocking\": \"s3.amazonaws.com\",\n      \"SpamScore\": 0,\n      \"DesktopClient\": true,\n      \"WindowImageThumbContentBlocking\": \"s3.amazonaws.com\",\n      \"Id\": your-result-id-here,\n      \"ResultType\": 0,\n      \"FullpageImageNoContentBlocking\": \"s3.amazonaws.com\",\n      \"ApplicationLongName\": \"Outlook 2010\"\n    }\n  ],\n  \"State\": \"waiting\",\n  \"InboxGuid\": your-inbox-guid-here,\n  \"Id\": your-test-id-here,\n  \"Source\": \"https:\\/\\/s3.amazonaws.com\\/sitevista\\/\",\n  \"Subject\": \"\",\n  \"Html\": \"https:\\/\\/html.litmus.com\\/email\\/?url=\\/sitevista\\/\",\n  \"ZipFile\": \"http:\\/\\/zip.litmus.com\\/resellers\\/?guid=\"your-guid-here,\n  \"TestType\": 0,\n  \"Sandbox\": false,\n  \"UserGuid\": null,\n  \"Error\": false,\n  \"ErrorMessage\": null\n}\n","name":""}]},"settings":"5666858b3360850d00336cf2","url":"/EmailTests"},"body":"Posting an Email Test will return the following:\n\n*  **`State`**: `waiting`, `processing`, or `complete`\n\n*  **`InboxGuid`**:  This is used to send your email to `InboxGuid`@emailtests.com\n\n*  **`Id`**:  You will receive an `Id` for each of the`TestingApplications` and one for the `EmailTests`.  You will need the `Id` to perform GET requests later.\n\n</br>\n\nThe following is the full model for Outlook 2010 serialized to JSON:","category":"565f2d3f7f93280d0052cf11","createdAt":"2015-12-08T07:24:38.641Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":1,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"email-tests","sync_unique":"","title":"Create test","type":"post","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

postCreate test


Posting an Email Test will return the following: * **`State`**: `waiting`, `processing`, or `complete` * **`InboxGuid`**: This is used to send your email to `InboxGuid`@emailtests.com * **`Id`**: You will receive an `Id` for each of the`TestingApplications` and one for the `EmailTests`. You will need the `Id` to perform GET requests later. </br> The following is the full model for Outlook 2010 serialized to JSON:

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Posting an Email Test will return the following: * **`State`**: `waiting`, `processing`, or `complete` * **`InboxGuid`**: This is used to send your email to `InboxGuid`@emailtests.com * **`Id`**: You will receive an `Id` for each of the`TestingApplications` and one for the `EmailTests`. You will need the `Id` to perform GET requests later. </br> The following is the full model for Outlook 2010 serialized to JSON:
{"__v":0,"_id":"566687fb3fcf5a0d000ef1c4","api":{"auth":"required","examples":{"codes":[{"language":"curl","code":"curl  -u username:password https://previews-api.litmus.com/api/v1/EmailTests/{Id}","name":""}]},"params":[{"_id":"566687fb3fcf5a0d000ef1c5","default":"","desc":"","name":"Id","ref":"","required":true,"type":"string","in":"path"}],"results":{"codes":[{"language":"text","code":""}]},"settings":"5666858b3360850d00336cf2","url":"/EmailTests/:Id"},"body":"","category":"565f2d3f7f93280d0052cf11","createdAt":"2015-12-08T07:34:19.276Z","editedParams":true,"editedParams2":true,"excerpt":"For this GET request you will need the `Id` for the entire [POST EmailTests](#post-emailtests) request.  This request will find out the State of your test and provide you with the URLs to the finished images, if the State of your test is complete.\n\nFor the full model of `EmailTests` see POST EmailTests","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":2,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"get-emailtests","sync_unique":"","title":"Retrieve test","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getRetrieve test

For this GET request you will need the `Id` for the entire [POST EmailTests](#post-emailtests) request. This request will find out the State of your test and provide you with the URLs to the finished images, if the State of your test is complete. For the full model of `EmailTests` see POST EmailTests

Path Params

Id:
required
string

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples



{"__v":4,"_id":"566687463360850d00336cf4","api":{"auth":"required","examples":{"codes":[{"language":"curl","code":"curl -u username:password https://previews-api.litmus.com/api/v1/EmailTests/TestingApplications ","name":""}]},"params":[],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"State\": null,\n  \"WindowImageContentBlocking\": null,\n  \"FullpageImageThumb\": null,\n  \"BusinessOrPopular\": true,\n  \"WindowImageThumbNoContentBlocking\": null,\n  \"Completed\": null,\n  \"FullpageImage\": null,\n  \"FoundInSpam\": null,\n  \"SupportsSpamScoring\": null,\n  \"Status\": 0,\n  \"WindowImageNoContentBlocking\": null,\n  \"PlatformName\": \"Windows\",\n  \"AverageTimeToProcess\": 38,\n  \"SpamHeaders\": null,\n  \"WindowImageThumb\": null,\n  \"RenderedHtmlUrl\": null,\n  \"PlatformLongName\": \"Microsoft Windows\",\n  \"FullpageImageThumbContentBlocking\": null,\n  \"WindowImage\": null,\n  \"FullpageImageContentBlocking\": null,\n  \"SupportsContentBlocking\": false,\n  \"ApplicationName\": \"ol2010\",\n  \"FullpageImageThumbNoContentBlocking\": null,\n  \"SpamScore\": 0,\n  \"DesktopClient\": true,\n  \"WindowImageThumbContentBlocking\": null,\n  \"Id\": 0,\n  \"ResultType\": 0,\n  \"FullpageImageNoContentBlocking\": null,\n  \"ApplicationLongName\": \"Outlook 2010\"\n}\n","name":""}]},"settings":"5666858b3360850d00336cf2","url":"/EmailTests/TestingApplications"},"body":"This GET request will produce a list of all of the available `TestingApplications` and the corresponding JSON model.\n\nThe following is the full model serialized to JSON for the Outlook 2010 `TestingApplication`.\n\n###Understanding TestingApplications Results\n\n`ResultType` returns an integer and that integer is associated with a type of test.\n\n| Integer    | Test Type                                                                           |\n|--------------|---------------------------------------------------------------------------------------|\n| 0           | Email Previews                     |\n| 1        | Spam Testing |\n| 2    | Page Testing                                          |\n| 3     | Browser Testing                                                   |","category":"565f2d3f7f93280d0052cf11","createdAt":"2015-12-08T07:31:18.257Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":3,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"testing-applications","sync_unique":"","title":"Testing applications","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getTesting applications


This GET request will produce a list of all of the available `TestingApplications` and the corresponding JSON model. The following is the full model serialized to JSON for the Outlook 2010 `TestingApplication`. ###Understanding TestingApplications Results `ResultType` returns an integer and that integer is associated with a type of test. | Integer | Test Type | |--------------|---------------------------------------------------------------------------------------| | 0 | Email Previews | | 1 | Spam Testing | | 2 | Page Testing | | 3 | Browser Testing |

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This GET request will produce a list of all of the available `TestingApplications` and the corresponding JSON model. The following is the full model serialized to JSON for the Outlook 2010 `TestingApplication`. ###Understanding TestingApplications Results `ResultType` returns an integer and that integer is associated with a type of test. | Integer | Test Type | |--------------|---------------------------------------------------------------------------------------| | 0 | Email Previews | | 1 | Spam Testing | | 2 | Page Testing | | 3 | Browser Testing |
{"__v":1,"_id":"566688f27cc81e0d00253f72","api":{"auth":"required","examples":{"codes":[{"language":"curl","code":"curl -u username:password https://previews-api.litmus.com/api/v1/Result/{Id}","name":""}]},"params":[{"_id":"56668967138d0f0d002d45c1","required":true,"desc":"","default":"","type":"string","name":"Id","in":"path"}],"results":{"codes":[{"language":"text","code":""}]},"settings":"5666858b3360850d00336cf2","url":"/Result/:Id"},"body":"For this GET request you will need the `Id` for the individual `TestingApplications` you want a `Result` for.  See [POST EmailTests](doc:email-tests) for information on how to obtain the `Id`.  \n\nThis request is handy for `TestingApplications` in a `State` of `waiting` or `processing`.\n\nThe result will be the same as found for an individual `ApplicationName` in `TestingApplications`.  See [POST EmailTests](doc:email-tests)  EmailTests for the full model.","category":"565f2d3f7f93280d0052cf11","createdAt":"2015-12-08T07:38:26.425Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"get-result","sync_unique":"","title":"Result","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getResult


Path Params

Id:
required
string
For this GET request you will need the `Id` for the individual `TestingApplications` you want a `Result` for. See [POST EmailTests](doc:email-tests) for information on how to obtain the `Id`. This request is handy for `TestingApplications` in a `State` of `waiting` or `processing`. The result will be the same as found for an individual `ApplicationName` in `TestingApplications`. See [POST EmailTests](doc:email-tests) EmailTests for the full model.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples



For this GET request you will need the `Id` for the individual `TestingApplications` you want a `Result` for. See [POST EmailTests](doc:email-tests) for information on how to obtain the `Id`. This request is handy for `TestingApplications` in a `State` of `waiting` or `processing`. The result will be the same as found for an individual `ApplicationName` in `TestingApplications`. See [POST EmailTests](doc:email-tests) EmailTests for the full model.
{"__v":2,"_id":"566689cf7cc81e0d00253f75","api":{"auth":"required","examples":{"codes":[{"language":"curl","code":"curl -u username:password https://previews-api.litmus.com/api/v1/SpamSeedAddresses","name":""}]},"params":[],"results":{"codes":[{"language":"text","code":""}]},"settings":"5666858b3360850d00336cf2","url":"/SpamSeedAddresses"},"body":"If you would like to send your email to Litmus to perform a Spam Filter analysis you will need to send to seed addresses.  To get a current list of Litmus Spam Seed Addresses perform this GET request.","category":"565f2d3f7f93280d0052cf11","createdAt":"2015-12-08T07:42:07.045Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":5,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"get-spamseedaddresses","sync_unique":"","title":"Spam seed addresses","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getSpam seed addresses


If you would like to send your email to Litmus to perform a Spam Filter analysis you will need to send to seed addresses. To get a current list of Litmus Spam Seed Addresses perform this GET request.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples



If you would like to send your email to Litmus to perform a Spam Filter analysis you will need to send to seed addresses. To get a current list of Litmus Spam Seed Addresses perform this GET request.
{"__v":0,"_id":"56668a5dce8caf0d006018b2","api":{"auth":"required","examples":{"codes":[{"language":"curl","code":"curl -u username:password https://previews-api.litmus.com/api/v1/LinkTests/{Id}","name":""}]},"params":[{"_id":"56668a5dce8caf0d006018b3","default":"","desc":"","name":"Id","ref":"","required":true,"type":"string","in":"path"}],"results":{"codes":[{"language":"text","code":""}]},"settings":"5666858b3360850d00336cf2","url":"/LinkTests/:Id"},"body":"For this request you will need the `Id` from the Link Check Test you performed.  This request will find out the `State` of your test and provide you with the URLs to the finished images, if the State of your test is `Complete`.","category":"565f2d3f7f93280d0052cf11","createdAt":"2015-12-08T07:44:29.194Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":6,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"get-linktests","sync_unique":"","title":"Link tests","type":"get","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

getLink tests


Path Params

Id:
required
string
For this request you will need the `Id` from the Link Check Test you performed. This request will find out the `State` of your test and provide you with the URLs to the finished images, if the State of your test is `Complete`.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples



For this request you will need the `Id` from the Link Check Test you performed. This request will find out the `State` of your test and provide you with the URLs to the finished images, if the State of your test is `Complete`.
{"__v":3,"_id":"565f2db60dc99e1900f24bbc","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"From an API point of view, our mobile email tests work exactly the same way as our regular email tests. Mobile email clients are simply additional 'Testing Applications’- you'll access them using the exact same API calls. The mobile results are returned amongst your regular email test results, and consist of URLs to the screenshots.\n \nHowever, there is one crucial difference. Mobile email tests are interactive, in some cases, even animated. We use a handful of different image files, some CSS magic, and a touch of Javascript to achieve these results. In order to include these types of results in your application, you'll need to add our Javascript to your site, and load in our HTML/CSS code, rather than just the screenshot image. We've tried to make it as easy as possible for you to do- there is a full code sample to download below.\n\n### Code sample\n \nEach mobile device requires different client-side (HTML/CSS/JS) code. Your application should check which mobile device is being viewed and serve up the appropriate client-side code. A list of mobile devices and their associated Application IDs can be found at the end of this document.\n \nSample HTML, CSS, Javascript as well as transparent devices images can be found at: https://github.com/litmus/litmus-mobile-samples\n\n### What are the Application IDs and OS details for these mobile devices?\n\n| Phone Model          | Operating System          | Mail Client | Application ID  |\n|----------------------|---------------------------|-------------|-----------------|\n| HTC Wildfire         | Android 2.3 (Gingerbread) | Default     | android23       |\n| Samsung Galaxy Nexus | Android 4.2.2 (Jellybean) | Default     | android4        |\n| Samsung Galaxy Nexus | Android 4.2.2 (Jellybean) | Gmail App   | androidgmailapp |\n| Blackberry 8900      | Blackberry OS 5 (HTML)    | Default     | blackberryhtml  |\n| iPhone 4S            | iOS 6                     | Default     | iphone4         |\n| iPhone 5             | iOS 6                     | Default     | iphone5         |\n| iPhone 5S            | iOS 7                     | Default     | iphone5s        |\n| iPhone 6             | iOS 8                     | Default     | iphone6         |\n| iPhone 6+            | iOS 8                     | Default     | iphone6plus     |\n| iPad (Retina)        | iOS 7                     | Default     | ipad            |\n| iPad Mini            | iOS 7                     | Default     | ipadmini        |\n| Nokia N96            | Symbian S60               | Default     | symbians60      |\n| Nokia Lumia 810      | Windows Phone 8           | Default     | windowsphone8   |","category":"565f2d3f7f93280d0052cf11","createdAt":"2015-12-02T17:43:18.598Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":7,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"using-mobile-results","sync_unique":"","title":"Using mobile results","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Using mobile results


From an API point of view, our mobile email tests work exactly the same way as our regular email tests. Mobile email clients are simply additional 'Testing Applications’- you'll access them using the exact same API calls. The mobile results are returned amongst your regular email test results, and consist of URLs to the screenshots. However, there is one crucial difference. Mobile email tests are interactive, in some cases, even animated. We use a handful of different image files, some CSS magic, and a touch of Javascript to achieve these results. In order to include these types of results in your application, you'll need to add our Javascript to your site, and load in our HTML/CSS code, rather than just the screenshot image. We've tried to make it as easy as possible for you to do- there is a full code sample to download below. ### Code sample Each mobile device requires different client-side (HTML/CSS/JS) code. Your application should check which mobile device is being viewed and serve up the appropriate client-side code. A list of mobile devices and their associated Application IDs can be found at the end of this document. Sample HTML, CSS, Javascript as well as transparent devices images can be found at: https://github.com/litmus/litmus-mobile-samples ### What are the Application IDs and OS details for these mobile devices? | Phone Model | Operating System | Mail Client | Application ID | |----------------------|---------------------------|-------------|-----------------| | HTC Wildfire | Android 2.3 (Gingerbread) | Default | android23 | | Samsung Galaxy Nexus | Android 4.2.2 (Jellybean) | Default | android4 | | Samsung Galaxy Nexus | Android 4.2.2 (Jellybean) | Gmail App | androidgmailapp | | Blackberry 8900 | Blackberry OS 5 (HTML) | Default | blackberryhtml | | iPhone 4S | iOS 6 | Default | iphone4 | | iPhone 5 | iOS 6 | Default | iphone5 | | iPhone 5S | iOS 7 | Default | iphone5s | | iPhone 6 | iOS 8 | Default | iphone6 | | iPhone 6+ | iOS 8 | Default | iphone6plus | | iPad (Retina) | iOS 7 | Default | ipad | | iPad Mini | iOS 7 | Default | ipadmini | | Nokia N96 | Symbian S60 | Default | symbians60 | | Nokia Lumia 810 | Windows Phone 8 | Default | windowsphone8 |
From an API point of view, our mobile email tests work exactly the same way as our regular email tests. Mobile email clients are simply additional 'Testing Applications’- you'll access them using the exact same API calls. The mobile results are returned amongst your regular email test results, and consist of URLs to the screenshots. However, there is one crucial difference. Mobile email tests are interactive, in some cases, even animated. We use a handful of different image files, some CSS magic, and a touch of Javascript to achieve these results. In order to include these types of results in your application, you'll need to add our Javascript to your site, and load in our HTML/CSS code, rather than just the screenshot image. We've tried to make it as easy as possible for you to do- there is a full code sample to download below. ### Code sample Each mobile device requires different client-side (HTML/CSS/JS) code. Your application should check which mobile device is being viewed and serve up the appropriate client-side code. A list of mobile devices and their associated Application IDs can be found at the end of this document. Sample HTML, CSS, Javascript as well as transparent devices images can be found at: https://github.com/litmus/litmus-mobile-samples ### What are the Application IDs and OS details for these mobile devices? | Phone Model | Operating System | Mail Client | Application ID | |----------------------|---------------------------|-------------|-----------------| | HTC Wildfire | Android 2.3 (Gingerbread) | Default | android23 | | Samsung Galaxy Nexus | Android 4.2.2 (Jellybean) | Default | android4 | | Samsung Galaxy Nexus | Android 4.2.2 (Jellybean) | Gmail App | androidgmailapp | | Blackberry 8900 | Blackberry OS 5 (HTML) | Default | blackberryhtml | | iPhone 4S | iOS 6 | Default | iphone4 | | iPhone 5 | iOS 6 | Default | iphone5 | | iPhone 5S | iOS 7 | Default | iphone5s | | iPhone 6 | iOS 8 | Default | iphone6 | | iPhone 6+ | iOS 8 | Default | iphone6plus | | iPad (Retina) | iOS 7 | Default | ipad | | iPad Mini | iOS 7 | Default | ipadmini | | Nokia N96 | Symbian S60 | Default | symbians60 | | Nokia Lumia 810 | Windows Phone 8 | Default | windowsphone8 |
{"__v":2,"_id":"565f2dc5ea4625170097275d","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Here are some descriptions of the more important attributes you will find in the API.\n\n*  *`Id`*:  The most important property.  This is the unique identifier for your `EmailTests`, `SpamTest`, and individual result from `TestingApplications`.\n\n*  *`ApiId`*: This code references the platform for the specific test result.  It will match the `ApplicationName` property of the results collection.\n\n*  *`SupportsContentBlocking`*: This value indicates true if the requested client supports content blocking and false if it does not.  Content blocking clients, sometimes referred to as image blocking, will return different result images for `ImagesOn` and `ImagesOff`.\n\n*  *`ResultImageSet`*: The ResultImageSet, as the name would suggest, is the collection of images that makes up your completed test.  It consists of two main blocks `ImagesOnUrls` and `ImagesOffUrls`.  Each main block contains two sub blocks for WindowUrls and FullPageUrls.  Further, each capture block contains an `ImageUrl` and `ThumbUrl`.  For clients that do not support content blocking the outerblocks (`ImagesOnUrls` and `ImagesOffUrls`) will be identical.  For clients who do support content blocking (`SupportsContentBlocking` == `true`) the `ImagesOffUrl` will show the blocked versions and `ImagesOnUrl` will show the non-blocked versions.\n\n*  *`State`*: Indicates the current status of your test.  By the time you receive a callback `Completed` will be `true`.  Values include: `pending`, `deferred`, `failed`, `completed`, `canceled`.\n\n*  *`CallbackUrl`*: This is the Url Litmus will post test results to.\n\n*  *`SpamResult`*:\n  *  *`SpamScore`*: Numerical spam indicator returned by the particular Spam filter.\n  *  *`IsSpam`*: Boolean indicating if this particular filter deems the message to be spam or not.\n  *  *`SpamHeaders`*: Each header consists of a key, description and rating indicating it's severity.\n  \n*  *`Status`*: Indicates the current status of the testing application on the Litmus platform.  This will return an integer value of 0,1 or 2.  `0` indicates the application is available and processing tests, `1` indicates we're currently experiencing some issues with the applications and `2` indicates the applications is currently unavailable for testing.  You can also visit https://status.litmus.com/ to find out about any issues affecting our platform.","category":"565f2d3f7f93280d0052cf11","createdAt":"2015-12-02T17:43:33.405Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":8,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"index","sync_unique":"","title":"Index","type":"basic","updates":[],"user":"5658ca325a9e990d004a5ccd","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

Index


Here are some descriptions of the more important attributes you will find in the API. * *`Id`*: The most important property. This is the unique identifier for your `EmailTests`, `SpamTest`, and individual result from `TestingApplications`. * *`ApiId`*: This code references the platform for the specific test result. It will match the `ApplicationName` property of the results collection. * *`SupportsContentBlocking`*: This value indicates true if the requested client supports content blocking and false if it does not. Content blocking clients, sometimes referred to as image blocking, will return different result images for `ImagesOn` and `ImagesOff`. * *`ResultImageSet`*: The ResultImageSet, as the name would suggest, is the collection of images that makes up your completed test. It consists of two main blocks `ImagesOnUrls` and `ImagesOffUrls`. Each main block contains two sub blocks for WindowUrls and FullPageUrls. Further, each capture block contains an `ImageUrl` and `ThumbUrl`. For clients that do not support content blocking the outerblocks (`ImagesOnUrls` and `ImagesOffUrls`) will be identical. For clients who do support content blocking (`SupportsContentBlocking` == `true`) the `ImagesOffUrl` will show the blocked versions and `ImagesOnUrl` will show the non-blocked versions. * *`State`*: Indicates the current status of your test. By the time you receive a callback `Completed` will be `true`. Values include: `pending`, `deferred`, `failed`, `completed`, `canceled`. * *`CallbackUrl`*: This is the Url Litmus will post test results to. * *`SpamResult`*: * *`SpamScore`*: Numerical spam indicator returned by the particular Spam filter. * *`IsSpam`*: Boolean indicating if this particular filter deems the message to be spam or not. * *`SpamHeaders`*: Each header consists of a key, description and rating indicating it's severity. * *`Status`*: Indicates the current status of the testing application on the Litmus platform. This will return an integer value of 0,1 or 2. `0` indicates the application is available and processing tests, `1` indicates we're currently experiencing some issues with the applications and `2` indicates the applications is currently unavailable for testing. You can also visit https://status.litmus.com/ to find out about any issues affecting our platform.
Here are some descriptions of the more important attributes you will find in the API. * *`Id`*: The most important property. This is the unique identifier for your `EmailTests`, `SpamTest`, and individual result from `TestingApplications`. * *`ApiId`*: This code references the platform for the specific test result. It will match the `ApplicationName` property of the results collection. * *`SupportsContentBlocking`*: This value indicates true if the requested client supports content blocking and false if it does not. Content blocking clients, sometimes referred to as image blocking, will return different result images for `ImagesOn` and `ImagesOff`. * *`ResultImageSet`*: The ResultImageSet, as the name would suggest, is the collection of images that makes up your completed test. It consists of two main blocks `ImagesOnUrls` and `ImagesOffUrls`. Each main block contains two sub blocks for WindowUrls and FullPageUrls. Further, each capture block contains an `ImageUrl` and `ThumbUrl`. For clients that do not support content blocking the outerblocks (`ImagesOnUrls` and `ImagesOffUrls`) will be identical. For clients who do support content blocking (`SupportsContentBlocking` == `true`) the `ImagesOffUrl` will show the blocked versions and `ImagesOnUrl` will show the non-blocked versions. * *`State`*: Indicates the current status of your test. By the time you receive a callback `Completed` will be `true`. Values include: `pending`, `deferred`, `failed`, `completed`, `canceled`. * *`CallbackUrl`*: This is the Url Litmus will post test results to. * *`SpamResult`*: * *`SpamScore`*: Numerical spam indicator returned by the particular Spam filter. * *`IsSpam`*: Boolean indicating if this particular filter deems the message to be spam or not. * *`SpamHeaders`*: Each header consists of a key, description and rating indicating it's severity. * *`Status`*: Indicates the current status of the testing application on the Litmus platform. This will return an integer value of 0,1 or 2. `0` indicates the application is available and processing tests, `1` indicates we're currently experiencing some issues with the applications and `2` indicates the applications is currently unavailable for testing. You can also visit https://status.litmus.com/ to find out about any issues affecting our platform.
{"__v":3,"_id":"576ad3447de8223400762ddb","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"[OAuth2](https://tools.ietf.org/html/rfc6749) is a protocol that allows external applications to act on behalf of Litmus users without the user having to reveal their Litmus username, password or API key, instead the user grants permissions to an application.\n\nLitmus currently supports the [OAuth2.0 Web Application Flow](https://tools.ietf.org/html/rfc6749#section-4.1) (also known as \"Authorization Code Grant\" flow).\n\n## Worked example\n\n[A minimal example of a partner app](https://litmus-oauth-example.herokuapp.com) is available which can be used to walk through the flow using your own Litmus account. The [source](https://github.com/litmus/litmus-oauth-example) for this is also provided.\n\n## Before you start\n\n1. Contact resellers@litmus.com to request a new API application.\n   You'll need to provide us:\n   - **application name**\n   - **OAuth callback URI** — whitelist a URI within your application that will handle exchanging an authorization code for a token (must be HTTPS, multiple can be provided)\n\n2. In return we'll provide you:\n   - `client_id`\n   - `client_secret` (must be kept private)\n\n## The Web Application Flow\n\n### 1. Redirect the user to request authorization to access Litmus\n\n```\nGET https://litmus.com/oauth/authorize?\n      response_type=code&\n      client_id=XYZ&\n      redirect_uri=https://yourapp.com/oauth/litmus/callback&\n      state=xxxxxxxx&      # nonce (this should be a random unguessable string)\n      scope=full\n```\n\nWhen logged in to Litmus, the user will be presented with your authorization request, eg\n\n<img src=\"https://cloud.githubusercontent.com/assets/14014/16248832/abb04698-3809-11e6-927e-0a199f338f75.png\" width=\"400px\">\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"A user is only asked to authorize your application once. If you later repeat the flow (eg to get a new token after the last had expired) we skip to the next step, so later token requests should generally be invisible to your user. Because the Litmus session could end it's generally preferable to first try using a refresh token for this purpose.\"\n}\n[/block]\n### 2. Litmus calls back to your application's redirect URI\n\nAssuming the user authorizes your request, Litmus will send a temporary code to your redirect uri (along with relaying the `state` param which you provided, which should be checked to avoid cross site request forgery):\n\n```\nGET https://yourapp.com/oauth/litmus/callback?code=ABCD...&state=xxxxxxxx\n```\n\nIf the user does not approve the request you'll instead receive an error:\n\n```\nGET https://yourapp.com/oauth/litmus/callback?error=access_denied\n```\n\n### 3. Exchange the code for an access token\n\nYour application server should POST using its `client_secret` and the `code` to obtain a token:\n\n```\nPOST https://litmus.com/oauth/token\n```\n\nJSON Post body parameters:\n\nField | Description\n------|------------\n`client_id` | *required*<br><br>The client ID you received from Litmus\n`client_secret` | *required*<br><br>The client secret you received from Litmus\n`code` | *required*<br><br>The code you received in the previous step\n`redirect_uri` | This must match `redirect_uri` provided in step 1, it should be omitted if this was not provided there\n`grant_type` | *required*<br><br>This must be `authorization_code`\n\nJSON Response body\n```javascript\n{\n  \"access_token\": \"XYZ\",\n  \"expires_in\": 7200,     // The remaining lifetime of the token in seconds\n  \"token_type\": \"Bearer\"  // The token type, currently always Bearer\n\n  // More fields may be provided\n}\n```\n\nLike your `client_secret` the token should be stored securely.\n\n### 4. Call Litmus API methods passing the token\n\nMake authenticated calls to our APIs from your application server using the HTTP `Authorization` header:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X \\\"POST\\\" \\\"https://instant-api.litmus.com/v1/emails\\\" \\\\\\n       -H \\\"Content-Type: application/json\\\" \\\\\\n       -H \\\"Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e\\\"\\\\\\n       -d \\\"{\\\\\\\"plain_text\\\\\\\":\\\\\\\"Hello World\\\\\\\"}\\\" -v\\n\\n> POST /v1/emails HTTP/1.1\\n> Host: instant-api.litmus.com\\n> User-Agent: curl/7.43.0\\n> Accept: */*\\n> Content-Type: application/json\\n> Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e\\n> Content-Length: 28\\n>\\n\\n< HTTP/1.1 200 OK\\n< Server: nginx\\n< Date: Tue, 21 Jun 2016 20:10:06 GMT\\n< Content-Type: application/json;charset=utf-8\\n< Content-Length: 58\\n< Connection: keep-alive\\n< Strict-Transport-Security: max-age=3600; includeSubdomains; preload\\n< X-Frame-Options: DENY\\n< X-Content-Type-Options: nosniff\\n<\\n\\n{\\n  \\\"email_guid\\\": \\\"113bdfdf-6d54-4cbe-8d38-dd66157e1751\\\"\\n}\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n## Scopes\n\nCurrently only one scope, `full` (\"Use all Litmus features on your behalf\") is currently provided (this is also the default when none is specified).\n\n\n## Token expiration and refresh\n\nToken expiry should be anticipated (the default token time-to-live is 2hrs, but this may change).\n\nRefresh tokens are supported and are the recommended approach to obtaining a new bearer token. Restarting the flow above will also issue a fresh token where the current litmus user has authorized your application already.\n\n## Token revocation\n\nToken revocation should also be anticipated and handled gracefully by restarting the flow. \n\n## Libraries\n\nA list of battle tested client libraries for simplifying integration can be found on the [OAuth project site](http://oauth.net/2/#client-libraries).\n\nFor integrating with ruby applications we also provide an [omniauth-litmus strategy](https://github.com/litmus/omniauth-litmus).","category":"576ad28e27d6252b000852ec","createdAt":"2016-06-22T18:04:52.816Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":0,"parentDoc":null,"project":"5658ca695a9e990d004a5cce","slug":"oauth-integration-guide","sync_unique":"","title":"OAuth Integration Guide","type":"basic","updates":[],"user":"566869d006039e0d00c4ecf3","version":"5658ca6a5a9e990d004a5cd1","childrenPages":[]}

OAuth Integration Guide


[OAuth2](https://tools.ietf.org/html/rfc6749) is a protocol that allows external applications to act on behalf of Litmus users without the user having to reveal their Litmus username, password or API key, instead the user grants permissions to an application. Litmus currently supports the [OAuth2.0 Web Application Flow](https://tools.ietf.org/html/rfc6749#section-4.1) (also known as "Authorization Code Grant" flow). ## Worked example [A minimal example of a partner app](https://litmus-oauth-example.herokuapp.com) is available which can be used to walk through the flow using your own Litmus account. The [source](https://github.com/litmus/litmus-oauth-example) for this is also provided. ## Before you start 1. Contact resellers@litmus.com to request a new API application. You'll need to provide us: - **application name** - **OAuth callback URI** — whitelist a URI within your application that will handle exchanging an authorization code for a token (must be HTTPS, multiple can be provided) 2. In return we'll provide you: - `client_id` - `client_secret` (must be kept private) ## The Web Application Flow ### 1. Redirect the user to request authorization to access Litmus ``` GET https://litmus.com/oauth/authorize? response_type=code& client_id=XYZ& redirect_uri=https://yourapp.com/oauth/litmus/callback& state=xxxxxxxx& # nonce (this should be a random unguessable string) scope=full ``` When logged in to Litmus, the user will be presented with your authorization request, eg <img src="https://cloud.githubusercontent.com/assets/14014/16248832/abb04698-3809-11e6-927e-0a199f338f75.png" width="400px"> [block:callout] { "type": "info", "body": "A user is only asked to authorize your application once. If you later repeat the flow (eg to get a new token after the last had expired) we skip to the next step, so later token requests should generally be invisible to your user. Because the Litmus session could end it's generally preferable to first try using a refresh token for this purpose." } [/block] ### 2. Litmus calls back to your application's redirect URI Assuming the user authorizes your request, Litmus will send a temporary code to your redirect uri (along with relaying the `state` param which you provided, which should be checked to avoid cross site request forgery): ``` GET https://yourapp.com/oauth/litmus/callback?code=ABCD...&state=xxxxxxxx ``` If the user does not approve the request you'll instead receive an error: ``` GET https://yourapp.com/oauth/litmus/callback?error=access_denied ``` ### 3. Exchange the code for an access token Your application server should POST using its `client_secret` and the `code` to obtain a token: ``` POST https://litmus.com/oauth/token ``` JSON Post body parameters: Field | Description ------|------------ `client_id` | *required*<br><br>The client ID you received from Litmus `client_secret` | *required*<br><br>The client secret you received from Litmus `code` | *required*<br><br>The code you received in the previous step `redirect_uri` | This must match `redirect_uri` provided in step 1, it should be omitted if this was not provided there `grant_type` | *required*<br><br>This must be `authorization_code` JSON Response body ```javascript { "access_token": "XYZ", "expires_in": 7200, // The remaining lifetime of the token in seconds "token_type": "Bearer" // The token type, currently always Bearer // More fields may be provided } ``` Like your `client_secret` the token should be stored securely. ### 4. Call Litmus API methods passing the token Make authenticated calls to our APIs from your application server using the HTTP `Authorization` header: [block:code] { "codes": [ { "code": "$ curl -X \"POST\" \"https://instant-api.litmus.com/v1/emails\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e\"\\\n -d \"{\\\"plain_text\\\":\\\"Hello World\\\"}\" -v\n\n> POST /v1/emails HTTP/1.1\n> Host: instant-api.litmus.com\n> User-Agent: curl/7.43.0\n> Accept: */*\n> Content-Type: application/json\n> Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e\n> Content-Length: 28\n>\n\n< HTTP/1.1 200 OK\n< Server: nginx\n< Date: Tue, 21 Jun 2016 20:10:06 GMT\n< Content-Type: application/json;charset=utf-8\n< Content-Length: 58\n< Connection: keep-alive\n< Strict-Transport-Security: max-age=3600; includeSubdomains; preload\n< X-Frame-Options: DENY\n< X-Content-Type-Options: nosniff\n<\n\n{\n \"email_guid\": \"113bdfdf-6d54-4cbe-8d38-dd66157e1751\"\n}", "language": "shell" } ] } [/block] ## Scopes Currently only one scope, `full` ("Use all Litmus features on your behalf") is currently provided (this is also the default when none is specified). ## Token expiration and refresh Token expiry should be anticipated (the default token time-to-live is 2hrs, but this may change). Refresh tokens are supported and are the recommended approach to obtaining a new bearer token. Restarting the flow above will also issue a fresh token where the current litmus user has authorized your application already. ## Token revocation Token revocation should also be anticipated and handled gracefully by restarting the flow. ## Libraries A list of battle tested client libraries for simplifying integration can be found on the [OAuth project site](http://oauth.net/2/#client-libraries). For integrating with ruby applications we also provide an [omniauth-litmus strategy](https://github.com/litmus/omniauth-litmus).
[OAuth2](https://tools.ietf.org/html/rfc6749) is a protocol that allows external applications to act on behalf of Litmus users without the user having to reveal their Litmus username, password or API key, instead the user grants permissions to an application. Litmus currently supports the [OAuth2.0 Web Application Flow](https://tools.ietf.org/html/rfc6749#section-4.1) (also known as "Authorization Code Grant" flow). ## Worked example [A minimal example of a partner app](https://litmus-oauth-example.herokuapp.com) is available which can be used to walk through the flow using your own Litmus account. The [source](https://github.com/litmus/litmus-oauth-example) for this is also provided. ## Before you start 1. Contact resellers@litmus.com to request a new API application. You'll need to provide us: - **application name** - **OAuth callback URI** — whitelist a URI within your application that will handle exchanging an authorization code for a token (must be HTTPS, multiple can be provided) 2. In return we'll provide you: - `client_id` - `client_secret` (must be kept private) ## The Web Application Flow ### 1. Redirect the user to request authorization to access Litmus ``` GET https://litmus.com/oauth/authorize? response_type=code& client_id=XYZ& redirect_uri=https://yourapp.com/oauth/litmus/callback& state=xxxxxxxx& # nonce (this should be a random unguessable string) scope=full ``` When logged in to Litmus, the user will be presented with your authorization request, eg <img src="https://cloud.githubusercontent.com/assets/14014/16248832/abb04698-3809-11e6-927e-0a199f338f75.png" width="400px"> [block:callout] { "type": "info", "body": "A user is only asked to authorize your application once. If you later repeat the flow (eg to get a new token after the last had expired) we skip to the next step, so later token requests should generally be invisible to your user. Because the Litmus session could end it's generally preferable to first try using a refresh token for this purpose." } [/block] ### 2. Litmus calls back to your application's redirect URI Assuming the user authorizes your request, Litmus will send a temporary code to your redirect uri (along with relaying the `state` param which you provided, which should be checked to avoid cross site request forgery): ``` GET https://yourapp.com/oauth/litmus/callback?code=ABCD...&state=xxxxxxxx ``` If the user does not approve the request you'll instead receive an error: ``` GET https://yourapp.com/oauth/litmus/callback?error=access_denied ``` ### 3. Exchange the code for an access token Your application server should POST using its `client_secret` and the `code` to obtain a token: ``` POST https://litmus.com/oauth/token ``` JSON Post body parameters: Field | Description ------|------------ `client_id` | *required*<br><br>The client ID you received from Litmus `client_secret` | *required*<br><br>The client secret you received from Litmus `code` | *required*<br><br>The code you received in the previous step `redirect_uri` | This must match `redirect_uri` provided in step 1, it should be omitted if this was not provided there `grant_type` | *required*<br><br>This must be `authorization_code` JSON Response body ```javascript { "access_token": "XYZ", "expires_in": 7200, // The remaining lifetime of the token in seconds "token_type": "Bearer" // The token type, currently always Bearer // More fields may be provided } ``` Like your `client_secret` the token should be stored securely. ### 4. Call Litmus API methods passing the token Make authenticated calls to our APIs from your application server using the HTTP `Authorization` header: [block:code] { "codes": [ { "code": "$ curl -X \"POST\" \"https://instant-api.litmus.com/v1/emails\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e\"\\\n -d \"{\\\"plain_text\\\":\\\"Hello World\\\"}\" -v\n\n> POST /v1/emails HTTP/1.1\n> Host: instant-api.litmus.com\n> User-Agent: curl/7.43.0\n> Accept: */*\n> Content-Type: application/json\n> Authorization: Bearer a66841f0a212c0afb6344c6377df4dde0389922511540d9e3c1d11e2ab811a2e\n> Content-Length: 28\n>\n\n< HTTP/1.1 200 OK\n< Server: nginx\n< Date: Tue, 21 Jun 2016 20:10:06 GMT\n< Content-Type: application/json;charset=utf-8\n< Content-Length: 58\n< Connection: keep-alive\n< Strict-Transport-Security: max-age=3600; includeSubdomains; preload\n< X-Frame-Options: DENY\n< X-Content-Type-Options: nosniff\n<\n\n{\n \"email_guid\": \"113bdfdf-6d54-4cbe-8d38-dd66157e1751\"\n}", "language": "shell" } ] } [/block] ## Scopes Currently only one scope, `full` ("Use all Litmus features on your behalf") is currently provided (this is also the default when none is specified). ## Token expiration and refresh Token expiry should be anticipated (the default token time-to-live is 2hrs, but this may change). Refresh tokens are supported and are the recommended approach to obtaining a new bearer token. Restarting the flow above will also issue a fresh token where the current litmus user has authorized your application already. ## Token revocation Token revocation should also be anticipated and handled gracefully by restarting the flow. ## Libraries A list of battle tested client libraries for simplifying integration can be found on the [OAuth project site](http://oauth.net/2/#client-libraries). For integrating with ruby applications we also provide an [omniauth-litmus strategy](https://github.com/litmus/omniauth-litmus).