Email layouts mAPI reference
Complete reference documentation for the Email layouts resource.
Email layouts
#Email layouts wrap email message templates to share consistent design components between the email notifications that your recipients receive.
You can create and update email layouts in your development environment, as well as retrieve or list all layouts in a given environment.
List email layouts
#Returns a paginated list of email layouts available in a given environment.
Endpoint
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Whether to annotate the resource. Only used in the Knock CLI.
Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
The cursor to fetch entries after.
The cursor to fetch entries before.
The number of entries to fetch per-page.
Returns
A paginated list of EmailLayout. Contains a list of entries and page information.
A list of entries.
Overrides to apply against account branding variables in an email layout, including dark mode-specific values.
A URL for a dark mode icon override.
A URL for a dark mode logo override.
The dark mode primary brand color in hex format.
The dark mode contrast color for the primary brand color in hex format.
A URL for a light mode icon override.
A URL for a light mode logo override.
The light mode primary brand color in hex format.
The light mode contrast color for the primary brand color in hex format.
The light mode primary text color in hex format.
The light mode secondary text color in hex format.
The timestamp of when the email layout was created.
The environment of the email layout.
A list of one or more items to show in the footer of the email layout.
The text to display as the link.
The URL to link to.
The complete HTML or MJML content of the email layout.
Whether this layout uses MJML format. When true, html_layout must contain <mjml> tags.
The unique key for this email layout.
The human-readable name of this email layout.
The SHA of the email layout.
The complete plaintext content of the email layout.
The timestamp of when the email layout was last updated.
The information about a paginated result.
The cursor to fetch entries after. Will only be present if there are more entries to fetch.
The cursor to fetch entries before. Will only be present if there are more entries to fetch before the current page.
The number of entries to fetch per-page.
Get email layout
#Retrieve an email layout by its key, in a given environment.
Endpoint
Path parameters
The key of the email layout to show.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Whether to annotate the resource. Only used in the Knock CLI.
Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
Returns
A versioned email layout used within an environment.
Overrides to apply against account branding variables in an email layout, including dark mode-specific values.
A URL for a dark mode icon override.
A URL for a dark mode logo override.
The dark mode primary brand color in hex format.
The dark mode contrast color for the primary brand color in hex format.
A URL for a light mode icon override.
A URL for a light mode logo override.
The light mode primary brand color in hex format.
The light mode contrast color for the primary brand color in hex format.
The light mode primary text color in hex format.
The light mode secondary text color in hex format.
The timestamp of when the email layout was created.
The environment of the email layout.
A list of one or more items to show in the footer of the email layout.
The text to display as the link.
The URL to link to.
The complete HTML or MJML content of the email layout.
Whether this layout uses MJML format. When true, html_layout must contain <mjml> tags.
The unique key for this email layout.
The human-readable name of this email layout.
The SHA of the email layout.
The complete plaintext content of the email layout.
The timestamp of when the email layout was last updated.
Upsert email layout
#Updates an email layout, or creates a new one if it does not yet exist.
Note: this endpoint only operates in the "development" environment.
Endpoint
Path parameters
The key of the email layout to upsert.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Whether to annotate the resource. Only used in the Knock CLI.
When set to true, forces the upsert to override existing content regardless of environment restrictions. This bypasses the development-only environment check and origin environment checks.
Whether to commit the resource at the same time as modifying it.
The message to commit the resource with, only used if commit is true.
When used with commit, creates a new version with identical content and commits it if there are no unpublished changes.
Request body
A request to update or create an email layout.
Overrides to apply against account branding variables in an email layout, including dark mode-specific values.
A URL for a dark mode icon override.
A URL for a dark mode logo override.
The dark mode primary brand color in hex format.
The dark mode contrast color for the primary brand color in hex format.
A URL for a light mode icon override.
A URL for a light mode logo override.
The light mode primary brand color in hex format.
The light mode contrast color for the primary brand color in hex format.
The light mode primary text color in hex format.
The light mode secondary text color in hex format.
A list of one or more items to show in the footer of the email layout.
The text to display as the link.
The URL to link to.
The complete HTML or MJML content of the email layout.
Whether this layout uses MJML format. When true, html_layout must contain <mjml> tags.
The friendly name of this email layout.
The complete plain text content of the email layout.
Returns
Wraps the EmailLayout response under the email_layout key.
A versioned email layout used within an environment.
Overrides to apply against account branding variables in an email layout, including dark mode-specific values.
A URL for a dark mode icon override.
A URL for a dark mode logo override.
The dark mode primary brand color in hex format.
The dark mode contrast color for the primary brand color in hex format.
A URL for a light mode icon override.
A URL for a light mode logo override.
The light mode primary brand color in hex format.
The light mode contrast color for the primary brand color in hex format.
The light mode primary text color in hex format.
The light mode secondary text color in hex format.
The timestamp of when the email layout was created.
The environment of the email layout.
A list of one or more items to show in the footer of the email layout.
The text to display as the link.
The URL to link to.
The complete HTML or MJML content of the email layout.
Whether this layout uses MJML format. When true, html_layout must contain <mjml> tags.
The unique key for this email layout.
The human-readable name of this email layout.
The SHA of the email layout.
The complete plaintext content of the email layout.
The timestamp of when the email layout was last updated.
Validate email layout
#Validates an email layout payload without persisting it.
Note: this endpoint only operates in the "development" environment.
Endpoint
Path parameters
The key of the email layout to validate.
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Request body
A request to update or create an email layout.
Overrides to apply against account branding variables in an email layout, including dark mode-specific values.
A URL for a dark mode icon override.
A URL for a dark mode logo override.
The dark mode primary brand color in hex format.
The dark mode contrast color for the primary brand color in hex format.
A URL for a light mode icon override.
A URL for a light mode logo override.
The light mode primary brand color in hex format.
The light mode contrast color for the primary brand color in hex format.
The light mode primary text color in hex format.
The light mode secondary text color in hex format.
A list of one or more items to show in the footer of the email layout.
The text to display as the link.
The URL to link to.
The complete HTML or MJML content of the email layout.
Whether this layout uses MJML format. When true, html_layout must contain <mjml> tags.
The friendly name of this email layout.
The complete plain text content of the email layout.
Returns
Wraps the EmailLayout response under the email_layout key.
A versioned email layout used within an environment.
Overrides to apply against account branding variables in an email layout, including dark mode-specific values.
A URL for a dark mode icon override.
A URL for a dark mode logo override.
The dark mode primary brand color in hex format.
The dark mode contrast color for the primary brand color in hex format.
A URL for a light mode icon override.
A URL for a light mode logo override.
The light mode primary brand color in hex format.
The light mode contrast color for the primary brand color in hex format.
The light mode primary text color in hex format.
The light mode secondary text color in hex format.
The timestamp of when the email layout was created.
The environment of the email layout.
A list of one or more items to show in the footer of the email layout.
The text to display as the link.
The URL to link to.
The complete HTML or MJML content of the email layout.
Whether this layout uses MJML format. When true, html_layout must contain <mjml> tags.
The unique key for this email layout.
The human-readable name of this email layout.
The SHA of the email layout.
The complete plaintext content of the email layout.
The timestamp of when the email layout was last updated.
Preview an email layout
#Renders an email layout preview, without requiring a layout to be persisted within Knock. This is useful for previewing layouts in isolation, before saving them.
Endpoint
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Request body
The data to pass to the layout for rendering.
A request to update or create an email layout.
Overrides to apply against account branding variables in an email layout, including dark mode-specific values.
A URL for a dark mode icon override.
A URL for a dark mode logo override.
The dark mode primary brand color in hex format.
The dark mode contrast color for the primary brand color in hex format.
A URL for a light mode icon override.
A URL for a light mode logo override.
The light mode primary brand color in hex format.
The light mode contrast color for the primary brand color in hex format.
The light mode primary text color in hex format.
The light mode secondary text color in hex format.
A list of one or more items to show in the footer of the email layout.
The text to display as the link.
The URL to link to.
The complete HTML or MJML content of the email layout.
Whether this layout uses MJML format. When true, html_layout must contain <mjml> tags.
The friendly name of this email layout.
The complete plain text content of the email layout.
A recipient reference, used when referencing a recipient by either their ID (for a user), or by a reference for an object.
The tenant to associate with the preview. Must not contain whitespace.
Optional workflow context for variable hydration. When provided, recipient/actor/tenant are resolved via Knock.
Workflow categories.
The workflow key.
Returns
A response to an email layout preview request.
A list of errors encountered during rendering. Present when result is "error".
The layout field that caused the error, if available.
The line number where the error occurred, if available.
A human-readable description of the error.
The rendered email layout, ready to be previewed.
The fully rendered HTML body of the email layout.
The fully rendered plain text body of the email layout.
The result of the preview.
EmailLayout
#A versioned email layout used within an environment.
Attributes
Overrides to apply against account branding variables in an email layout, including dark mode-specific values.
A URL for a dark mode icon override.
A URL for a dark mode logo override.
The dark mode primary brand color in hex format.
The dark mode contrast color for the primary brand color in hex format.
A URL for a light mode icon override.
A URL for a light mode logo override.
The light mode primary brand color in hex format.
The light mode contrast color for the primary brand color in hex format.
The light mode primary text color in hex format.
The light mode secondary text color in hex format.
The timestamp of when the email layout was created.
The environment of the email layout.
A list of one or more items to show in the footer of the email layout.
The text to display as the link.
The URL to link to.
The complete HTML or MJML content of the email layout.
Whether this layout uses MJML format. When true, html_layout must contain <mjml> tags.
The unique key for this email layout.
The human-readable name of this email layout.
The SHA of the email layout.
The complete plaintext content of the email layout.
The timestamp of when the email layout was last updated.
EmailLayoutRequest
#A request to update or create an email layout.
Attributes
Overrides to apply against account branding variables in an email layout, including dark mode-specific values.
A URL for a dark mode icon override.
A URL for a dark mode logo override.
The dark mode primary brand color in hex format.
The dark mode contrast color for the primary brand color in hex format.
A URL for a light mode icon override.
A URL for a light mode logo override.
The light mode primary brand color in hex format.
The light mode contrast color for the primary brand color in hex format.
The light mode primary text color in hex format.
The light mode secondary text color in hex format.
A list of one or more items to show in the footer of the email layout.
The text to display as the link.
The URL to link to.
The complete HTML or MJML content of the email layout.
Whether this layout uses MJML format. When true, html_layout must contain <mjml> tags.
The friendly name of this email layout.
The complete plain text content of the email layout.
BrandingOverrides
#Overrides to apply against account branding variables in an email layout, including dark mode-specific values.
Attributes
A URL for a dark mode icon override.
A URL for a dark mode logo override.
The dark mode primary brand color in hex format.
The dark mode contrast color for the primary brand color in hex format.
A URL for a light mode icon override.
A URL for a light mode logo override.
The light mode primary brand color in hex format.
The light mode contrast color for the primary brand color in hex format.
The light mode primary text color in hex format.
The light mode secondary text color in hex format.