Appearance

Email Guardian Early Access ​

TIP

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

Use Litmus's Email Guardian feature to actively monitor your users' emails for changes in client rendering, link availability, and image availability.

This API uses the JSON:API specification.

Create an anonymous integration user ​

POST https://api.litmus.com/v3/integration-users

Examples ​

cURL ​

sh
curl -X "POST" "https://api.litmus.com/v3/integration-users" \
     -H 'Authorization: Bearer abcdef' \
     -H 'Content-Type: application/vnd.api+json' \
     -d $'{
  "data": {
    "type": "integration-users"
  }
}'

Result Format ​

201 Created

json
{
  "data" : {
    "id" : "1",
    "type" : "integration-users",
    "links" : {
      "self" : "https://api.litmus.localhost/api/v3/integration-users/1"
    }
  }
}

Enroll an email into Email Guardian ​

POST https://api.litmus.com/v3/email_guardian/emails?integration_user_id={integration_user_id}

URL parameters ​

FieldDescription
integration_user_idREQUIRED

The ID of your user you are acting on behalf of

Attributes ​

FieldDescription
htmlREQUIRED

The raw HTML of the email to monitor

Examples ​

cURL ​

sh
## Enroll email
curl -X "POST" "https://api.litmus.com/v3/email_guardian/emails?integration_user_id=1" \
     -H 'Authorization: Bearer abcdef' \
     -H 'Content-Type: application/vnd.api+json' \
     -d $'{
  "data": {
    "type": "emails",
    "attributes": {
      "html": "<html><body><h1>My HTML email</h1></body></html>"
    }
  }
}'

Result Format ​

201 Created

json
{
  "data" : {
    "id" : "11",
    "type" : "emails",
    "links" : {
      "self" : "https://api.litmus.localhost/api/v3/email-guardian/emails/11"
    }
    "attributes" : {
      "html" : "<html><body><h1>My HTML email</h1></body></html>"
    }
  }
}

Unenroll an email from Email Guardian ​

DELETE https://api.litmus.com/v3/email_guardian/emails/{email_id}?integration_user_id={integration_user_id}

URL parameters ​

FieldDescription
integration_user_idREQUIRED

The ID of your user you are acting on behalf of
email_idREQUIRED

The ID number of the email you want to unenroll

Examples ​

cURL ​

sh
## Unenroll email
curl -X "DELETE" "https://api.litmus.com/v3/email_guardian/emails/23?integration_user_id=1" \
     -H 'Authorization: Bearer abcdef' \
     -H 'Content-Type: application/vnd.api+json' \
     -d $'{}'

Result Format ​

204 No Content

View latest monitoring result for an email ​

GET https://api.litmus.com/v3/email_guardian/emails/{email_id}/result

URL parameters ​

FieldDescription
email_idREQUIRED

The ID number of the email you want to unenroll

Examples ​

cURL ​

sh
curl "https://api.litmus.com/v3/email_guardian/emails/15/result" \
     -H 'Authorization: Bearer abcdef' \
     -H 'Content-Type: application/vnd.api+json'

Result Format ​

200 OK

json
{
  "data": {
    "id": "15",
    "type": "results",
    "links": {
      "self": "https://api.litmus.com/api/v3/email-guardian/results"
    },
    "attributes": {
      "clients": [
        {
          "client_name": "Outlook.com",
          "screenshot_url": "https://storage.capture.litmus.com/api/emails/f2956477-843e-4a55-9226-09c9c6db9f5f/monitored-captures/chromeoutlookcom/full?images=allowed&orientation=vertical&width=1366",
          "change": "major"
        },
        {
          "client_name": "Yahoo! Mail",
          "screenshot_url": "https://storage.capture.litmus.com/api/emails/f2956477-843e-4a55-9226-09c9c6db9f5f/monitored-captures/chromeyahoo/full?images=allowed&orientation=vertical&width=1366",
          "change": "minor"
        },
        {
          "client_name": "Outlook Office 365",
          "screenshot_url": "https://storage.capture.litmus.com/api/emails/f2956477-843e-4a55-9226-09c9c6db9f5f/monitored-captures/ol365/full?images=allowed&orientation=vertical&width=1366",
          "change": "noChange"
        }
      ],
      "links": [
        {
          "link_url": "https://litmus.com/",
          "destination_url": "https://www.litmus.com/",
          "destination_screenshot_url": "https://storage.capture.litmus.com/api/linkcheckscreenshots/fc29124b-2277-4f2f-a5a3-4be774260c5d/thumbnail",
          "status": "ok"
        },
        {
          "link_url": "https://brokenexample.com/broken-link",
          "destination_url": null,
          "error_message": "ERR_NAME_NOT_RESOLVED",
          "status": "broken"
        }
      ],
      "checked-at": "2024-02-05T13:58:39.000+00:00"
    }
  }
}

Register a notification webhook ​

POST https://api.litmus.com/v3/email_guardian/webhooks

Attributes ​

FieldDescription
urlREQUIRED

The URL of your webhook

Examples ​

cURL ​

sh
curl -X "POST" "https://api.litmus.com/v3/email_guardian/webhooks" \
     -H 'Authorization: Bearer abcdef' \
     -H 'Content-Type: application/vnd.api+json' \
     -d $'{
  "data": {
    "type": "webhooks",
    "attributes": {
      "url": "https://example.com/webhook"
    }
  }
}'

Result Format ​

201 Created

json
{
  "data": {
    "id": "1",
    "type": "webhooks",
    "links": {
      "self": "https://api.litmus.com/api/v3/email-guardian/webhooks/1"
    },
    "attributes": { "url": "https://example.com/webhook" }
  }
}

Unregister a notification webhook ​

Coming soon.

Receiving a notification ​

When we detect a major change in either the client rendering or the link availablity of one of your emails, we will send a POST request to your webhook(s). This request will contain a JSON:API document similar to the Result resource, but only containing data for the single client or links where we have detected a change.

Example document with a client change:

json
{
  "data": {
    "id": "15",
    "type": "results",
    "links": {
      "self": "https://api.litmus.com/api/v3/email-guardian/results"
    },
    "attributes": {
      "clients": [
        {
          "client_name": "Outlook.com",
          "screenshot_url": "https://storage.capture.litmus.com/api/emails/f2956477-843e-4a55-9226-09c9c6db9f5f/monitored-captures/chromeoutlookcom/full?images=allowed&orientation=vertical&width=1366",
          "change": "major"
        }
      ],
      "links": [],
      "checked-at": "2024-02-05T13:58:39.000+00:00"
    }
  }
}

Example document with a link change:

json
{
  "data": {
    "id": "15",
    "type": "results",
    "links": {
      "self": "https://api.litmus.com/api/v3/email-guardian/results"
    },
    "attributes": {
      "clients": [],
      "links": [
        {
          "link_url": "https://brokenexample.com/broken-link",
          "destination_url": null,
          "error_message": "ERR_NAME_NOT_RESOLVED",
          "status": "broken"
        }
      ],
      "checked-at": "2024-02-05T13:58:39.000+00:00"
    }
  }
}

Test a notification webhook ​

Send an empty POST request to one of the following URLs, and we will make a request to your webhook with a sample notification document similar to the ones you would receive in a real notification.

POST https://api.litmus.com/v3/email_guardian/webhooks/{webhook_id}/tests/link_change

POST https://api.litmus.com/v3/email_guardian/webhooks/{webhook_id}/tests/client_change

URL parameters ​

FieldDescription
webhook_idREQUIRED

The ID number of the notification webhook you want to test

Examples ​

cURL ​

sh
curl -X "POST" "https://api.litmus.com/v3/email_guardian/webhooks/7/tests/link_change" \
     -H 'Authorization: Bearer abcdef' \
     -H 'Content-Type: application/vnd.api+json'

Result Format ​

204 No Content