Check
Learn more about how to use the Check endpoints.
Overview
The Check group consists of three endpoints that scan a template's JSON or a row's JSON, to identify and report critical design elements that are missing. With these endpoints, you can bring design QA functionality into your application. They automatically check a design for common mistakes (including missing links, missing alt text, overly large images, or HTML file sizes that might cause your users' emails to get clipped in Gmail). This is possible through a POST
request where you define the language
, types of checks
to perform, and the template
or row
JSON to check. The response will report any instances within the JSON where an item is missing, a limit is exceeded, and so on. It’ll also include the location (called target
in the response body) of the item that needs attention within the JSON. For example, the uuid
of an image module that is missing alt text.
When coupled with Frontend Commands, these endpoints act as a core pillar of an interactive feedback experience for your end users. Frontend Commands work by displaying visual cues within the user interface. These cues navigate end users to the part of the design and builder that requires their attention. From there, they can easily apply the changes, perform an additional check if they’d like, and export their designs.
Overall, the Check endpoints identify critical design elements, while Frontend Commands help your end users navigate to the elements that need fixing. Together, they create a tool kit that helps your end users create error-free designs, and support them in ensuring their content is complete and ready for their audiences to consume and enjoy.
For a comprehensive list of all the available checks, reference the Available Checks section of this page.
How the Endpoints Work
The Check endpoints accept three parameters in the request body: languages
, checks
, and template
or row
. Reference the descriptions for each parameter below:
languages
: Define the language of the template.checks
: Define the checks you want to perform on the template or row JSON. Do this by adding the category, the check, and the details for the check if applicable. The following code snippet displays an example of this.
template
orrow
: Include the JSON for either an email template, a page template, or a row. This is the JSON that will be checked in ways defined in the checks section of thePOST
request.
Authentication
To use these endpoints, authenticate by creating a Content Services API key in the Beefree SDK Developer Console. For steps on how to obtain a Content Services API key, visit the Content Services API Authentication page.
Available Checks
Reference the available checks you can perform using the Check endpoints in this section. You can perform checks on:
Email template JSON: Use the
v1/message/check
endpoint to perform a check on email template JSON.Page template JSON: Use the
v1/page/check
endpoint to perform a check on page template JSON.Row JSON within a template: Use the
v1/row/check
endpoint to perform a check on row JSON within a template.
This section covers the available checks you can perform using these endpoints. Each check listed in this section will include which endpoints it applies to, how it looks in an example API request, and how it looks in an example response. It also explains each field and includes its corresponding data type and description.
Comprehensively, across all endpoints, the available checks are the following:
Missing alt text: Shown as
missingAltText
in requests and responses.Missing link on copy: Shown as
missingCopyLink
in requests and responses.Missing link on images: Shown as
missingImageLink
in requests and responses.Image overage weight: Shown as
overageImageWeight
in requests and responses.Missing email details: Shown as
missingEmailDetail
in requests and responses.Missing page details: Shown as
missingDetailsPage
in requests and responsesHTML overage size: Shown as
overageHtmlWeight
in requests and responses.
Missing Alt Text
This section covers the Missing Alt Text check, detailing the process of adding the check to the POST
API call, and how it appears in example responses. It includes examples of both a successful check and one that returns a warning.
Type
Warning
Available for
Email and page messages, email and page templates, rows
Applicable widgets
Image, gif, sticker, icon, social
Perform this check by adding {"category":"missingAltText"}
to your API call's request body.
Example response for a check that passed
The following JSON response shows an example of a missing alt text check that passed. This means that within the email, page, or row JSON, an instance of missing alt text was not identified, and the end user can confidently export their design knowing alt text is where it should be.
Example response for a check that returned a warning
The following JSON response shows an example of a missing alt text check that resulted in a warning. This means that within the email, page, or row JSON, an instance of missing alt text was identified, and the end user should resolve the missing alt text in the corresponding target prior to exporting their design.
The following table lists and defines all the fields related to the missingAltText
check.
type
string
Check type, equal to missingAltText
targetsCount
integer
The number of widgets missing alt text
checkStatus
string
The status of this check: passed
or warning
targets
array
The list of widgets missing alt text
locked
boolean
If the widget missing alt text is in a locked row
synced
boolean
If the widget missing alt text is in a synced row
uuid
string
uuid
of the row containing this widget
widgetLabel
string
Label of the widget missing alt text: filename for icon
, url for image
, gif
and sticker
and name for social
widgetType
string
Type of the widget missing alt text: image
, gif
, sticker
, icon
, social
Missing Link on Copy
This section covers the Missing Link on Copy check, detailing the process of adding the check to the POST
API call, and how it appears in example responses. It includes examples of both a successful check and one that returns a warning.
Type
Warning
Available for
Email and page messages, email and page templates, rows
Applicable widgets
Button, social, menu
Perform this check by adding {"category":"missingCopyLink"}
to your API call's request body.
Example response for a check that passed
The following JSON response shows an example of a missing copy link check that passed. This means that within the email, page, or row JSON, an instance of a missing copy link was not identified, and the end user can confidently export their design knowing copy links are where they should be.
Example response for a check that returned a warning
The following JSON response shows an example of a missing copy link check that resulted in a warning. This means that within the email, page, or row JSON, an instance of a missing copy link was identified, and the end user should resolve the missing copy link in the corresponding target prior to exporting their design.
The following table lists and defines all the fields related to the missingCopyLink
check.
type
string
Check type, equal to missingCopyLink
targetsCount
integer
The number of widgets missing a link
checkStatus
string
The status of this check: passed
or warning
targets
array
The list of widgets miss link
locked
boolean
If the widget missing link is in a locked row
synced
boolean
If the widget missing link is in a synced row
uuid
string
uuid
of the row containing this widget
widgetLabel
string
Label of the widget missing link
widgetType
string
Type of the widget missing alt text: button
, menu
, social
Missing Link on Images
This section covers the Missing Link on Images check, detailing the process of adding the check to the POST
API call, and how it appears in example responses. It includes examples of both a successful check and one that returns a warning.
Type
Suggestion
Available for
Email and page messages, email and page templates, rows
Applicable widgets
Image, gif, sticker, icon
Perform this check by adding {"category":"missingImageLink"}
to your API call's request body.
Example response for a check that passed
The following JSON response shows an example of a missing image link check that passed. This means that within the email, page, or row JSON, an instance of a missing image link was not identified, and the end user can confidently export their design knowing image links are where they should be.
Example response for a check that returned a warning
The following JSON response shows an example of a missing image link check that resulted in a warning. This means that within the email, page, or row JSON, an instance of a missing image link was identified, and the end user should resolve the missing image link in the corresponding target prior to exporting their design.
The following table lists and defines all the fields related to the missingImageLink
check.
type
string
Check type, equal to missingImageLink
targetsCount
integer
The number of widgets miss link
checkStatus
string
The status of this check: passed
or suggestion
targets
array
The list of widgets miss link
locked
boolean
If the widget missing link is in a locked row
synced
boolean
If the widget missing link is in a synced row
uuid
string
uuid
of the row containing this widget
widgetLabel
string
Label of the widget missing link: filename for icon
, url for image
, gif
and sticker
widgetType
string
Type of the widget missing alt text: image
, gif
, sticker
, icon
Image Overage Weight
This section covers the Image Overage Weight check, detailing the process of adding the check to the POST
API call, and how it appears in example responses. It includes examples of both a successful check and one that returns a warning.
In the example detailed in this section, the weight limit is set to 500KB for emails and rows, and 700KB for pages. The "Content-Length" header in the response of HEAD requests from image, gif, sticker, icon, and social URLs is used to determine if the content size exceeds the specified limits. If the header is missing or the URL cannot be evaluated within 20 seconds, it is considered an error, and the URL is logged for review.
Type
Suggestion
Available for
Email and page messages, email and page templates, rows
Applicable widgets
Image, gif, sticker, icon, social
Perform this check by adding {"category":"overageImageWeight", "limit": 500}
to your API call's request body.
limit
int
Other such limit the image weight is considered overage in KB
Example response for a check that passed
The following JSON response shows an example of an image weight overage check that passed. This means that within the email, page, or row JSON, an instance of a limit overage was not identified, and the end user can confidently export their design.
Example response for a check that returned a warning
The following JSON response shows an example of an image weight overage check that resulted in a warning. This means that within the email, page, or row JSON, an instance of an image weight overages was identified, and the end user should resolve the overage prior to exporting their design.
The following table lists and defines all the fields related to the overageImageWeight
check.
type
string
Check type, equal to overageImageWeight
targetsCount
integer
The number of widgets miss alt text
checkStatus
string
The status of this check: passed
or warning
limit
integer
The limit given in the request
evaluated
integer
The number of evaluated images
errored
integer
The number of images impossible to get the content-length in head requests
targets
array
The list of widgets miss alt text
locked
boolean
if the widget missing alt text is in a locked row
synced
boolean
If the widget missing alt text is in a synced row
weight
float
The weight of the image in KB
uuid
string
uuid
of the row containing this widget
widgetLabel
string
Label of the widget missing alt text
widgetType
string
Type of the widget missing alt text: image
, gif
, sticker
, icon
, social
Missing Email Details
This section covers the Missing Email Details check, detailing the process of adding the check to the POST
API call, and how it appears in example responses. It includes examples of both a successful check and one that returns a warning.
Type
Suggestion
Available for
Email messages
Use general features in JSON
Head
Perform this check by adding {"category": "missingDetailsEmail"}
to your API call's request body.
Example response for a check that passed
The following JSON response shows an example of a missing email details check that passed. This means that within the email, an instance of missing email details was not identified, and the end user can confidently export their design.
Example response for a check that returned a warning
The following JSON response shows an example of a missing email details check that resulted in a warning. This means that within the email, an instance of a missing email details was identified, and the end user should resolve the missing email details prior to exporting their design.
The following table lists and defines all the fields related to the missingDetailsEmail
check.
type
string
Check type, equal to missingDetailsEmail
targetsCount
integer
The number of missing email details
checkStatus
string
The status of this check: passed
or suggestion
targets
array
The list of missing details
detailType
string
Type of the widget missing alt text: subject
, preheader
Missing Page Details
This section covers the Missing Page Details check, detailing the process of adding the check to the POST
API call, and how it appears in example responses. It includes examples of both a successful check and one that returns a warning.
Type
Suggestion
Available for
Page messages
Use general features in JSON
Head
Perform this check by adding {"category": "missingDetailsPage"}
to your API call's request body.
Example response for a check that passed
The following JSON response shows an example of a missing page details check that passed. This means that within the page, an instance of missing page details was not identified, and the end user can confidently export their design.
Example response for a check that returned a warning
The following JSON response shows an example of a missing page details check that resulted in a warning. This means that within the page, an instance of a missing page details was identified, and the end user should resolve the missing details prior to exporting their design.
The following table lists and defines all the fields related to the missingDetailsPage
check.
type
string
Check type, equal to missingDetailsPage
targetsCount
integer
The number of missing page details
checkStatus
string
The status of this check: passed
or suggestion
targets
array
The list of missing details
detailType
string
Type of the widget missing text: title
, description
HTML Overage Size
This section covers the HTML Overage Weight check, detailing the process of adding the check to the POST
API call, and how it appears in example responses. It includes examples of both a successful check and one that returns a warning.
In the example detailed in this section, the weight limit is set to 80KB for emails and rows, and 700KB for pages. The given JSON HTML is translated and the weight is checked against the specified limit, with the "beautified" boolean determining whether the check applies to the beautified HTML or not. If the weight exceeds the limit, it is considered an error and should be flagged for review.
Type
Warning
Available for
Email messages
Use general features in JSON
displayConditions
Perform this check by adding {"category":"overageHtmlWeight", "limit": 20, "beautified": true}
to your API call's request body.
limit
int
Other such limit the image weight is considered overage in KB.
beautified
string
Optional, default true
The weight is considered on beautified html or minified HTML
Example response for a check that passed
The following JSON response shows an example of an HTML weight overage check that passed. This means that within the email, an instance of a limit overage was not identified, and the end user can confidently export their design.
Example response for a check that returned a warning
The following JSON response shows an example of an HTML weight overage check that resulted in a warning. This means that within the email, an instance of an HTML weight overages was identified, and the end user should resolve the overage prior to exporting their design.
The following table lists and defines all the fields related to the overageHtmlWeight
check.
type
string
Check type, equal to overageHtmlWeight
targetsCount
integer
The number of widgets miss alt text
checkStatus
string
The status of this check: passed
or warning
maxWeight
float or null
The max weight on the generated html files. null if the parser does not response
displayConditions
boolean
If the given json includes display conditions
processed
boolean
If the check has been processed. It is false
when the parser does not response
limit
integer
The limit given in the request
targets
array
The list of html files generated if the parser is responding and at least 1 has the weight other the limit
weight
float
The weight of the generated HTML in KB
beautified
boolean
If the coupled weight is related on beautified HTML
Frontend Visual Feedback and Cues
This page discusses how to perform API calls on the backend in order to run checks again email, page, and row JSON. An important part of connecting the backend API calls to frontend feedback is the response body of these API calls. When a check is performed against the JSON, if an issue is identified, the target
in the API response specifies the element that needs attention. This target is what connects to Frontend Commands, the execCommand
method and actions (select
, highlight
, scroll
, and focus
), and provides feedback visually to the end users on the frontend.
The following code snippet provides an example email check response from an API call to the v1/message/check
endpoint.
Check Endpoints
This section lists and describes each of the Check endpoints. You can use this section to learn about endpoint and how they work. You can also test each endpoint in the interactive testing environment available by clicking Test it.
Email
This section includes details on how to make an API call using the email check endpoint. In the following environment, you can reference comprehensive endpoint details and use the interactive testing environment to get started with the endpoint.
Page
This section includes details on how to make an API call using the page check endpoint. In the following environment, you can reference comprehensive endpoint details and use the interactive testing environment to get started with the endpoint.
Row
This section includes details on how to make an API call using the row check endpoint. In the following environment, you can reference comprehensive endpoint details and use the interactive testing environment to get started with the endpoint.
Last updated
Was this helpful?