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

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.com/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

Field	Description
`integration_user_id`	REQUIRED The ID of your user you are acting on behalf of

Attributes

Field	Description
`html`	REQUIRED The raw HTML of the email to monitor

Examples

cURL

## 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.com/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

Field	Description
`integration_user_id`	REQUIRED The ID of your user you are acting on behalf of
`email_id`	REQUIRED The ID number of the email you want to unenroll

Examples

cURL

## 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

List all enrolled emails

GET https://api.litmus.com/v3/email_guardian/emails

Examples

cURL

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

Result Format

200 OK

json

{
  "data": [
    {
      "id": "4",
      "type": "emails",
      "links": {
        "self": "https://api.litmus.com/api/v3/email-guardian/emails/4"
      },
      "attributes": {
        "html": null
      }
    }
  ],
  "links": {
    "first": "https://api.litmus.com/api/v3/email-guardian/emails?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "last": "https://api.litmus.com/api/v3/email-guardian/emails?page%5Bnumber%5D=1&page%5Bsize%5D=20",
  }
}

List all enrolled emails belonging to a particular integration user

GET https://api.litmus.com/v3/email_guardian/integration-users/{integration_user_id}/emails

URL parameters

Field	Description
`integration_user_id`	REQUIRED The ID of your user you are acting on behalf of

Examples

cURL

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

Result Format

200 OK

json

{
  "data": [
    {
      "id": "4",
      "type": "emails",
      "links": {
        "self": "https://api.litmus.com/api/v3/email-guardian/emails/4"
      },
      "attributes": {
        "html": null
      }
    }
  ],
  "links": {
    "first": "https://api.litmus.com/api/v3/email-guardian/emails?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "last": "https://api.litmus.com/api/v3/email-guardian/emails?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

View latest monitoring result for an email

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

URL parameters

Field	Description
`email_id`	REQUIRED The ID number of the email you want to unenroll

Examples

cURL

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

Field	Description
`url`	REQUIRED The URL of your webhook

Examples

cURL

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

Field	Description
`webhook_id`	REQUIRED The ID number of the notification webhook you want to test

Examples

cURL

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

Email Guardian Early Access ​

Create an anonymous integration user ​

Examples ​

cURL ​

Result Format ​

Enroll an email into Email Guardian ​

URL parameters ​

Attributes ​

Examples ​

cURL ​

Result Format ​

Unenroll an email from Email Guardian ​

URL parameters ​

Examples ​

cURL ​

Result Format ​

List all enrolled emails ​

Examples ​

cURL ​

Result Format ​

List all enrolled emails belonging to a particular integration user ​

URL parameters ​

Examples ​

cURL ​

Result Format ​

View latest monitoring result for an email ​

URL parameters ​

Examples ​

cURL ​

Result Format ​

Register a notification webhook ​

Attributes ​

Examples ​

cURL ​

Result Format ​

Unregister a notification webhook ​

Receiving a notification ​

Test a notification webhook ​

URL parameters ​

Examples ​

cURL ​

Result Format ​

Email Guardian Early Access

Create an anonymous integration user

Examples

cURL

Result Format

Enroll an email into Email Guardian

URL parameters

Attributes

Examples

cURL

Result Format

Unenroll an email from Email Guardian

URL parameters

Examples

cURL

Result Format

List all enrolled emails

Examples

cURL

Result Format

List all enrolled emails belonging to a particular integration user

URL parameters

Examples

cURL

Result Format

View latest monitoring result for an email

URL parameters

Examples

cURL

Result Format

Register a notification webhook

Attributes

Examples

cURL

Result Format

Unregister a notification webhook

Receiving a notification

Test a notification webhook

URL parameters

Examples

cURL

Result Format