Skip to content

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": []
            }
          ]
        }
      ]
    }
  }
}