Appearance

Accessibility 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

This API supports both Web Application and Client Credential OAuth flows.

Accessibility Checks ​

Our accessibility checks API analyzes a supplied email against a number of accessibility-related criteria specific to HTML emails.

Due to the nature of how we perform accessibility checks, these may take several seconds to complete. The process to submit an email and retrieve the check results is two-step:

  • Send a request for accessiblity checks against a given email.
  • Send a follow up request to retrieve the check results.

Submit an email for Accessiblity checks ​

POST https://api.litmus.com/v3/accessibility/checks

bash
curl -X "POST" "https://api.litmus.com/v3/accessibility/checks" \
     -H 'Authorization: Bearer example-auth-token' \
     -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": {
    "type": "emails",
    "id": "example-email-guid"
  }
}

Retrieve Accessibility Check results ​

GET https://api.litmus.com/v3/accessibility/checks/:email-guid

IMPORTANT

Polling for accessibility check results is excluded from rate limiting while results are in a pending state.

Examples ​

cURL ​
bash
curl "https://api.litmus.com/v3/accessibility/checks/example-email-guid"\
 -H "Authorization: Bearer example-auth-token"

Result Format ​

Invalid email GUID has been supplied ​

404 Not Found

json
{
  "errors": [
    {
      "status": "404",
      "title": "Not Found"
    }
  ]
}

Checks are not complete ​

202 Accepted

json
{
  "data": [],
  "meta": {
    "state": "pending"
  }
}
Checks have been completed ​

200 OK

json
{
  "meta": {
    "state": "complete"
  },
  "data": {
    "id": "example-email-guid",
    "type": "checks",
    "attributes": {
      "numberOfChecks": 41,
      "passes": [
        {
          "rule": "Aria hidden body",
          "description": "Ensures aria-hidden='true' is not present on the document body.",
          "standards": ["WCAG 2A"]
        },
        {
          "rule": "Color contrast",
          "description": "Ensures the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds",
          "standards": ["WCAG 2AA"]
        }
      ],
      "failures":[
        {
          "rule": "Email has heading one",
          "description": "Ensure that the email, or at least one of its frames contains a level-one heading",
          "standards": ["Best practice"],
          "impact": "moderate",
          "instances": [
            {
              "htmlSnippet": "\u003chtml\u003e\u003chead\u003e\u003cmeta name=\"color-scheme\" content=\"light dark\"\u003e\u003c/head\u003e\u003cbody\u003e\u003cpre style=\"word-wrap: break-word; white-space: pre-wrap;\"\u003ehtml\u003c/pre\u003e\u003c/body\u003e\u003c/html\u003e",
              "satisfyAll": ["Page must have a level-one heading"],
              "satisfyAny": []
            }
          ]
        }
      ]
    }
  }
}