Backend API
The Stripo Plugin Backend API allows for various operations related to compiling and managing email templates, including inlining CSS styles into HTML tags to provide the final HTML code ready to be sent to recipients. Please take a look at the available methods below.
Compiling Email Templates
This API call allows inlining CSS styles into HTML tags and provides the final HTML code of email templates that are ready to be sent to recipients.
OpenAPI Specification
Reference
yaml
openapi: 3.0.3
info:
title: Compiling Email Templates
description: |
This API call allows inlining CSS styles into HTML tags and provides the final HTML code of email templates that are ready to be sent to recipients.
version: 1.0.0
servers:
- url: https://plugins.stripo.email
description: Stripo API server
paths:
/coediting/v1/email/compilation:
get:
tags:
- Methods
summary: Get compiled email
description: Get compiled inline CSS into HTML email templates.
parameters:
- name: minimize
in: query
required: false
description: >-
If true then html code will be in a format of a single line without
line breaks
schema:
type: boolean
example: false
- name: inlineCss
in: query
required: false
description: >
Allows you to select the type of code in the received compiled
email.
inlineCss: true - by default. This means that we will see CSS placed inside tags when we make a compiled form of HTML.
inlineCss: false - editor will not inline the CSS in the tags, but rather write it at the head of the email.
schema:
type: boolean
example: false
- name: ES-PLUGIN-AUTH
in: header
required: true
description: Stripo plugin auth token in the format - Bearer ${AUTH_TOKEN}
schema:
type: string
- name: ES-PLUGIN-UI-DATA
in: header
required: true
description: >
JSON string with parameters to identify email (Same as metadata param in UI editor). For example: {"emailId": "id1"}
schema:
type: string
responses:
'200':
description: Compiled email
content:
application/json:
schema:
$ref: '#/components/schemas/CompiledEmail'
components:
schemas:
CompiledEmail:
type: object
properties:
html:
type: string
description: Compiled HTML
ampHtml:
type: string
description: Compiled AMP version of HTML
ampErrors:
type: array
description: List of AMP errors inside AMP HTML email template
items:
type: string
syncModules:
type: array
description: List of IDs of sync modules what was found in the HTML
items:
type: integer
format: int64
conditions:
type: array
description: List of AMP errors inside AMP HTML email template
items:
$ref: '#/components/schemas/Condition'
Condition:
type: object
properties:
id:
type: string
description: Condition ID
name:
type: string
description: Condition name
description:
type: string
description: Condition description
beforeScript:
type: string
description: Content of beforeScript section
afterScript:
type: string
description: Content of afterScript sectionRaw HTML Compilation
This API call allows you to compile raw HTML and CSS into export-ready email HTML by passing the source directly in the request body. Inlines CSS styles, resolves synchronizable modules, applies display conditions, adds UTM parameters, and generates AMP HTML when AMP markup is detected.
Use this method for legacy integrations or external workflows where email content is managed outside the Stripo editor.
OpenAPI Specification
Reference
yaml
openapi: 3.0.3
info:
title: Raw HTML Compilation
version: 1.0.0
servers:
- url: https://plugins.stripo.email
description: Stripo plugin host
paths:
/api/v1/cleaner/v1/compress:
post:
summary: Compile raw HTML and CSS
description: |
Accepts raw email HTML and CSS directly and returns compiled, export-ready HTML.
Unlike the session-based compilation endpoint, this method does not require an active
editor session or email ID — it processes whatever HTML and CSS you provide.
Suitable for legacy integrations and external workflows where email content is managed
outside the Stripo editor. Performs the same compilation pipeline: inlines CSS styles,
resolves synchronizable modules, applies display conditions, adds UTM parameters,
and generates AMP HTML when AMP markup is detected.
operationId: compileTemplateHtml
tags:
- Methods
security:
- ESPluginAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompressRequest'
example:
html: "<!DOCTYPE html><html><head><title>Subject</title></head><body><p>Hello</p></body></html>"
css: "p { color: red; }"
minimize: true
utmSource: "newsletter"
utmMedium: "email"
utmCampaign: "spring_sale"
responses:
'200':
description: HTML was compiled successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CompressResponse'
example:
html: "<!DOCTYPE html><html><head></head><body><p style=\"color:red\">Hello</p></body></html>"
subject: "Subject"
'400':
description: Bad request, unsupported content type, missing body, missing `html`, or validation error.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
examples:
missingHtml:
value:
message: "'html' param is required"
missingBody:
value:
message: "Required request body is missing"
cssTooLarge:
value:
message: "'css' must not be greater than 5 000 000 symbols"
htmlTooLarge:
value:
message: "'html' must not be greater than 9 000 000 symbols"
'401':
description: Missing, invalid, or expired plugin authentication token.
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseText'
example:
message: "ES-PLUGIN-AUTH header is invalid or token is expired. Set header 'ES-PLUGIN-AUTH: Bearer YOUR_AUTH_TOKEN'"
'429':
description: Rate limit reached.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
example:
error: RATE_LIMIT_REACHED
'500':
description: Unexpected service error.
components:
securitySchemes:
ESPluginAuth:
type: apiKey
in: header
name: ES-PLUGIN-AUTH
description: Plugin JWT authentication header. Expected format is `Bearer YOUR_AUTH_TOKEN`.
schemas:
CompressRequest:
type: object
required:
- html
additionalProperties: false
description: |
Request body for compiling email template HTML.
Only `html` is required by runtime validation.
properties:
html:
type: string
maxLength: 9000000
description: Source email template HTML to compile.
css:
type: string
description: |
CSS to inline into the HTML. If absent or empty, HTML is returned without CSS inlining.
Non-blank CSS is rejected only when both the raw CSS and the CSS after comment removal exceed 5,000,000 characters.
minimize:
type: boolean
nullable: true
default: false
description: When true, removes unnecessary whitespace and compresses the regular HTML output.
utmSource:
type: string
description: Value to add as the `utm_source` query parameter on links.
utmMedium:
type: string
description: Value to add as the `utm_medium` query parameter on links.
utmCampaign:
type: string
description: Value to add as the `utm_campaign` query parameter on links.
utmContent:
type: string
description: Value to add as the `utm_content` query parameter on links.
utmTerm:
type: string
description: Value to add as the `utm_term` query parameter on links.
customUtms:
type: array
description: Custom query parameters to add to links along with standard UTM parameters.
items:
$ref: '#/components/schemas/CustomUtm'
paramsBeforeRef:
type: boolean
default: false
description: |
Where UTM parameters are placed in links that contain an anchor (`#`).
`false` (default) appends them after the anchor: `https://example.com/page#section?utm_source=...`.
`true` places them before the anchor: `https://example.com/page?utm_source=...#section`.
Links without an anchor are not affected.
mergeTags:
type: array
description: Merge tag placeholders to preserve while processing links and UTM parameters.
items:
type: string
apiRequestData:
type: string
description: |
Plugin request data, encoded as a JSON string, passed to synchronizable module replacement.
In the editor UI this is derived from plugin `apiRequestData` only when synchronizable modules are enabled.
Pass it only if the HTML contains synchronizable modules that must be resolved.
CompressResponse:
type: object
required:
- html
additionalProperties: false
properties:
html:
type: string
description: Compiled HTML.
subject:
type: string
description: Email subject extracted from the HTML title.
preheader:
type: string
description: Hidden email preheader extracted from the HTML.
ampHtml:
type: string
description: Generated AMP HTML. Returned only when AMP markup is detected in source HTML.
ampErrors:
type: array
description: AMP validation errors. Empty array means AMP validation passed; absent when AMP HTML was not generated.
items:
type: string
syncModules:
type: array
description: Synchronizable module IDs.
items:
type: integer
format: int64
conditions:
type: array
description: Display conditions extracted from the source HTML.
items:
$ref: '#/components/schemas/Condition'
Condition:
type: object
additionalProperties: false
properties:
id:
type: string
description: Condition identifier.
name:
type: string
description: Condition name.
description:
type: string
description: Condition description.
beforeScript:
type: string
description: Script inserted before the conditional content.
afterScript:
type: string
description: Script inserted after the conditional content.
CustomUtm:
type: object
additionalProperties: false
properties:
name:
type: string
description: Custom query parameter name.
value:
type: string
description: Custom query parameter value.
APIError:
type: object
additionalProperties: true
properties:
message:
type: string
description: Human-readable error message.
traceId:
type: string
description: Trace identifier, when available.
code:
type: string
description: Application error code, when available.
params:
description: Additional error parameters.
error:
description: Structured internal error data, when available.
detailedError:
type: string
description: Detailed error description, when available.
date:
type: string
format: date-time
description: Error timestamp, when available.
ResponseText:
type: object
additionalProperties: false
properties:
message:
type: string
description: Error message returned by the API gateway auth filter.
RateLimitError:
type: object
additionalProperties: false
properties:
error:
type: string
description: Rate limit error code.
example: RATE_LIMIT_REACHEDRetrieving HTML and CSS (Legacy Compatibility)
This API call allows you to retrieve HTML and CSS from the “reference email” in Stripo’s database. This is particularly useful for maintaining compatibility with older versions of the Stripo editor.
OpenAPI Specification
Reference
yaml
openapi: 3.0.3
info:
title: Retrieving HTML and CSS (Legacy Compatibility)
description: |
Returns HTML with developer markup and classes, along with CSS, to be stored within your database. This method ensures that when a customer wants to open an email with the editor (old plugin) next time, the stored HTML and CSS can be sent to the editor, maintaining compatibility with legacy systems and preserving the email's design and structure.
version: 1.0.0
servers:
- url: https://plugins.stripo.email
description: Stripo API server
paths:
/coediting/v1/email/html-css:
get:
tags:
- Methods
summary: Get HTML and CSS of email template
description: Get HTML with developer markup and classes, along with CSS
parameters:
- name: ES-PLUGIN-AUTH
in: header
required: true
description: Stripo plugin auth token in the format - Bearer ${AUTH_TOKEN}
schema:
type: string
- name: ES-PLUGIN-UI-DATA
in: header
required: true
description: >
JSON string with parameters to identify email (Same as metadata param in UI editor). For example: {"emailId": "id1"}
schema:
type: string
responses:
'200':
description: HTML and CSS of email template
content:
application/json:
schema:
$ref: '#/components/schemas/HtmlCss'
components:
schemas:
HtmlCss:
type: object
properties:
html:
type: string
description: HTML of email template
css:
type: string
description: CSS of email template
emailId:
type: integer
format: int64
description: ID of email
syncModules:
type: array
description: List of IDs of sync modules what was found in the HTML (only in case you've activated the Synchronized Modules)
items:
type: integer
format: int64
utm:
$ref: '#/components/schemas/UtmParams'
description: UTM params of email template
UtmParams:
type: object
properties:
source:
type: string
description: UTM source
medium:
type: string
description: UTM medium
campaign:
type: string
description: UTM campaign
content:
type: string
description: UTM content
term:
type: string
description: UTM term
custom:
description: UTM custom properties
additionalProperties:
type: string
nullable: trueCloning an Email Model
Create a copy of an existing email model programmatically.
This API method allows you to clone an existing email model, creating a new, independent model with a unique identifier. The original email model is not modified. Use this endpoint to duplicate email models when you need to reuse structure or content in automation, integrations, or editorial workflows.
OpenAPI Specification
Reference
yaml
openapi: 3.0.3
info:
title: Email Model Clone API
description: |
This API method allows you to clone an existing email model and create a new one
based on its structure and content.
The cloned email model is created as a separate entity with a new identifier,
while the original email model remains unchanged.
This method is useful when you need to duplicate an email model programmatically
and continue working with the copied version independently.
version: 1.0.0
servers:
- url: https://plugins.stripo.email
description: Stripo API server
paths:
/coediting/v1/email/copy:
post:
tags:
- Methods
summary: Clone email model
description: |
Clone an existing email model and create a new email model based on it.
The method copies the structure and content of the source email model
and creates a new email model with a new unique identifier.
The response contains the identifier of the newly created email model,
which can be used for further operations in the editor or via API.
To copy a specific historical version of the source email, pass the optional patchId — see the [Restore a Version as a New Email](/plugin-invocations/javascript-api#restore-a-version-as-a-new-email) guide.
parameters:
- name: ES-PLUGIN-AUTH
in: header
required: true
description: Stripo plugin auth token in the format - Bearer ${AUTH_TOKEN}
schema:
type: string
- name: ES-PLUGIN-UI-DATA
in: header
required: true
description: >
JSON string with parameters to identify email
(same as metadata parameter in the UI editor).
For example: {"emailId": "id1"}
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CopyEmailRequest'
responses:
'200':
description: |
Email model cloned successfully.
Returns the ID of the newly created email model.
content:
application/json:
schema:
$ref: '#/components/schemas/CopyEmailResponse'
components:
schemas:
CopyEmailRequest:
type: object
properties:
sourceId:
type: string
description: Source email ID
destinationId:
type: string
description: Destination email ID
patchId:
type: string
format: uuid
nullable: true
description: >-
Optional. UUID of a version (patch) of the source email. When provided, the destination model is created from the content of this historical version instead of the current state of the source model. The value must identify a visible, non-technical version of the source email -- an invalid, unknown, foreign, hidden, or technical patchId returns 400 Bad Request and the destination model is not created. The initial version ID 00000000-0000-0000-0000-000000000001 is supported. Note: if the source email uses a Template Theme, the destination is bound to the latest version of that theme -- the historical theme state is not restored.
CopyEmailResponse:
type: object
properties:
destinationId:
type: string
description: Destination email IDCreating Email Models and Managing Document State
Create an email model from HTML and CSS, read its current content, and change it programmatically, all without opening the editor.
The document state is the JSON representation of the email content and styles, the same structure the editor works with. Use these methods to generate emails from your backend, apply changes to an existing email (for example, replace texts, links, or images), or keep an external system in sync with the email content.
The API provides four methods:
| Method | Purpose |
|---|---|
POST /coediting/v1/email/create | Create the initial model of an email from HTML and CSS. |
GET /coediting/v1/email/document-state | Get the current document state of an email. |
PUT /coediting/v1/email/document-state | Apply changes to the document state of an email. |
GET /coediting/v1/document-state/schema | Get the JSON Schema that describes the document state. |
All methods require a plugin token of the API role, passed in the ES-PLUGIN-AUTH header. The email is identified by the ES-PLUGIN-UI-DATA header: a URL-encoded JSON object with the emailId, the same value you pass in metadata on editor initialization. For example, {"emailId":"123"} is sent as %7B%22emailId%22%3A%22123%22%7D. The schema method does not need this header.
The emailId must be a JSON string, not a number.
A typical flow:
- Get the schema with
GET /coediting/v1/document-state/schemaand validate your document states against it. The schema changes together with the editor, so fetch it rather than storing a copy. - Create the email with
POST /coediting/v1/email/create, passing its HTML and CSS. The method is idempotent: if the email already has a model, the response returns its modelId and the existing model is left unchanged. - Read the current state with
GET /coediting/v1/email/document-state. - Change the state and send it with
PUT /coediting/v1/email/document-state. Pass the state you read asbaseDocumentStateand your changed state astargetDocumentState: only the differences between them are applied, so changes that users make in the editor in the meantime are preserved. The changes are saved to the model and delivered to open editor sessions.
Use the unchanged documentStateResult returned in step 3 as baseDocumentState, and make your changes to a copy of it. Without baseDocumentState, the current state is used as the base, so a stale targetDocumentState can overwrite changes made after you read the state.
If both the current state and targetDocumentState changed the same value relative to baseDocumentState to different values, the whole update is rejected with 409 REVISION_CONFLICT and nothing is applied. If both changes produced the same value, there is no conflict for that value. On conflict, read the current state, reconcile your changes and repeat steps 3–4 with a new base/target pair.
The server checks more than the schema describes, so a state that matches the schema can still be rejected with 422 VALIDATION_ERROR. The details.errors field of the response lists the invalid fields.
Example: create an email
bash
curl https://plugins.stripo.email/coediting/v1/email/create \
--request POST \
--header 'ES-PLUGIN-AUTH: Bearer YOUR_API_ROLE_TOKEN' \
--header 'ES-PLUGIN-UI-DATA: %7B%22emailId%22%3A%22NEW_EMAIL_ID%22%7D' \
--header 'Content-Type: application/json' \
--data '{
"html": "<!doctype html><html><body><p>Hello</p></body></html>",
"css": "p { color: #123456; }",
"author": "backend@example.com"
}'Example response
json
{
"modelId": "7_NEW_EMAIL_ID"
}The HTML and CSS are converted on the server. When the email is opened in the editor for the first time, the editor may apply its usual updates to it, so the document state can change slightly after that. For emails with AMP content, pass the HTML and CSS through the html and css initialization parameters of the editor instead.
Example: update an email
Get the current state:
bash
curl https://plugins.stripo.email/coediting/v1/email/document-state \
--header 'ES-PLUGIN-AUTH: Bearer YOUR_API_ROLE_TOKEN' \
--header 'ES-PLUGIN-UI-DATA: %7B%22emailId%22%3A%22NEW_EMAIL_ID%22%7D' \
--output state.jsonPrepare the update. This example uses jq to change the content width of the email and keeps the state you got as the base:
js
jq '{
baseDocumentState: .documentStateResult,
targetDocumentState: (.documentStateResult | .settings.general.messageContentWidth = 640)
}' state.json > update.jsonSend the update:
bash
curl https://plugins.stripo.email/coediting/v1/email/document-state \
--request PUT \
--header 'ES-PLUGIN-AUTH: Bearer YOUR_API_ROLE_TOKEN' \
--header 'ES-PLUGIN-UI-DATA: %7B%22emailId%22%3A%22NEW_EMAIL_ID%22%7D' \
--header 'Content-Type: application/json' \
--data @update.jsonExample response
json
{
"appliedActions": 4,
"generatedPatchesCount": 1
}Creating a model does not trigger an Email Change Notification webhook for the new email. If your application stores email content in its own database, retrieve the HTML and CSS explicitly after creating the email.
An update that saves changes triggers the Email Change Notification webhook, if it is set up in your plugin settings, in the same way as an autosave in the editor. The userId in this notification is empty.
Please be advised: when the Email Resources Permissions API is enabled in your plugin settings, Stripo asks your endpoint for an EMAIL permission before every email operation: READ for reading the document state, MODIFY for updating it and for creating an email. The request contains the emailId in uiData and the key <pluginId>_<emailId>. MODIFY does not imply READ.
If your endpoint does not grant the required EMAIL permission, the method returns 403. Make sure your endpoint handles the EMAIL type before you start using these methods.
OpenAPI Specification
Reference
yaml
openapi: 3.0.3
info:
title: Email Document State API
version: 1.0.0
description: |
Create an email model from HTML and CSS, read and update its document state,
and get the JSON Schema of the document state, all without opening the editor.
The document state is the JSON representation of the email content and styles,
the same structure the editor works with. Fetch the schema from the schema
method and validate your document states against it instead of relying on a
fixed copy: the schema evolves together with the editor.
All methods require a plugin token with the `API` role. The email is identified
by the `ES-PLUGIN-UI-DATA` header, which carries a URL-encoded JSON object with
the `emailId`, the same value you pass in `metadata` on editor initialization.
The schema method does not need this header.
When the Email Resources Permissions API is enabled in your plugin settings,
Stripo asks your endpoint for an `EMAIL` permission before every email operation:
`READ` for reading the document state and `MODIFY` for updating it and for creating
an email. `MODIFY` does not imply `READ`.
contact:
name: Stripo Support
url: https://stripo.email
servers:
- url: https://plugins.stripo.email
description: Stripo Plugin API server
security:
- pluginAuth: []
tags:
- name: Methods
description: Create emails and work with their document state.
paths:
/coediting/v1/email/create:
post:
tags: [Methods]
operationId: createPluginEmail
summary: Create an email model from HTML and CSS
description: |
Creates the initial model of an email from HTML and CSS. The email is identified
by the `emailId` from the `ES-PLUGIN-UI-DATA` header; the model is created for your
plugin under this ID.
The method is idempotent: if a model with this ID already exists, the response is
`200` with the same `modelId`, and the existing model is neither regenerated nor
overwritten, even if the request carries different HTML or CSS.
The HTML and CSS are converted into the model on the server. When the email is
opened in the editor for the first time, the editor may additionally normalize
the model, as it does for any email.
AMP content is not processed on creation the way the editor processes it. For
emails with AMP content, pass the HTML and CSS through the `html` and `css`
initialization parameters of the editor instead.
Creating an email does not send an Email Change Notification.
Unknown fields in the request body are rejected. Limits: request body up to 32 MiB,
`html` up to 18 MiB, `css` up to 4 MiB, `variables` up to 8 MiB, `author` up to 254 bytes,
`utm` up to 256 KiB. All limits are byte limits.
Requires the `EMAIL` `MODIFY` permission when the Email Resources Permissions API is enabled,
including for repeated requests for an existing model.
parameters:
- $ref: '#/components/parameters/EmailUIData'
- $ref: '#/components/parameters/TraceId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailRequest'
example:
html: '<!doctype html><html><body><p>Hello</p></body></html>'
css: 'p { color: #123456; }'
author: backend@example.com
responses:
'200':
description: The model was created, or an existing model was found and left unchanged.
content:
application/json:
schema:
type: object
required: [modelId]
properties:
modelId:
type: string
description: Identifier of the model in the format `<pluginId>_<emailId>`.
example: {modelId: '7_123'}
'400':
description: |
Invalid header, content type or request body, or `MODEL_CREATION_INVALID_REQUEST`.
`INVALID_CONTENT_TYPE` — `Content-Type` is not `application/json`.
`INVALID_REQUEST` — invalid JSON, an unknown field, or a missing or invalid field value.
`MODEL_RESOLUTION_BAD_REQUEST` — invalid `ES-PLUGIN-UI-DATA` header.
`INVALID_TRACE_ID` — the `X-Trace-ID` header is too long.
`MODEL_CREATION_INVALID_REQUEST` — the HTML or CSS could not be converted into a model.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailError'
'401':
description: Missing or invalid plugin token.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailError'
example: {code: UNAUTHORIZED, message: Model source authentication failed, stage: model_resolution, retryable: false}
'403':
description: The token does not have the `API` role, or the `EMAIL` `MODIFY` permission was not granted.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailError'
example: {code: FORBIDDEN, message: Access to the model source is forbidden, stage: model_resolution, retryable: false}
'409':
description: The email with this `emailId` is being deleted by a Delete Email Models job (`MODEL_DELETING`). Wait until the deletion finishes and send the request again.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailError'
example: {code: MODEL_DELETING, message: Model is being deleted, stage: existence_check, retryable: false}
'413':
description: The request body or one of its fields exceeds the limit (`PAYLOAD_TOO_LARGE`).
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailError'
'422':
description: |
The CSS cannot be parsed (`MODEL_CREATION_CSS_PARSE_ERROR`) or the model could not be built (`PATCH_APPLICATION_HANGS`). The model is not saved.
For `MODEL_CREATION_CSS_PARSE_ERROR`, `location` points to the error in the CSS.
`PATCH_APPLICATION_HANGS` means processing exceeded the time limit. Retry when
`retryable` is `true`; if the error repeats, simplify the HTML or contact support.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailError'
example:
code: MODEL_CREATION_CSS_PARSE_ERROR
message: Model CSS could not be parsed
stage: parse_css
source: input-css
retryable: false
location: {startLine: 4, startColumn: 2, endLine: 4, endColumn: 12}
'429':
$ref: '#/components/responses/RateLimited'
'503':
description: A dependent service is temporarily unavailable (`MODEL_RESOLUTION_UNAVAILABLE`, `DOWNSTREAM_UNAVAILABLE`). Retry when `retryable` is `true`.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailError'
'504':
description: The operation timed out (`REQUEST_TIMEOUT`).
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailError'
'500':
description: Internal error (`PERSISTENCE_FAILED`, `INVALID_RESPONSE`, `INTERNAL`).
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailError'
/coediting/v1/email/document-state:
parameters:
- $ref: '#/components/parameters/EmailUIData'
- $ref: '#/components/parameters/TraceId'
get:
tags: [Methods]
operationId: getPluginEmailDocumentState
summary: Get the current document state
description: |
Returns the current document state of the email. The method does not create a
model for an email that has never been opened or created: such an email returns `404`.
Requires the `EMAIL` `READ` permission when the Email Resources Permissions API is enabled.
responses:
'200':
description: The current document state of the email.
content:
application/json:
schema:
type: object
required: [documentStateResult]
properties:
documentStateResult:
$ref: '#/components/schemas/DocumentState'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: The email has no model yet (`MODEL_NOT_FOUND`).
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentStateError'
example: {code: MODEL_NOT_FOUND, message: Model not found, stage: service, retryable: false}
'429':
$ref: '#/components/responses/RateLimited'
default:
$ref: '#/components/responses/DocumentStateFailure'
put:
tags: [Methods]
operationId: setPluginEmailDocumentState
summary: Update the document state
description: |
Applies changes to the document state of the email.
`targetDocumentState` is the state you want the email to have. When you also pass
`baseDocumentState`, the state you read before making your changes, only the differences
between the base and the target are applied to the current model. Values that users have
changed in the editor in the meantime and that your changes do not touch are preserved.
When `baseDocumentState` is omitted, the current state of the model is used as the base.
This can overwrite changes made after you read the state. To preserve those changes,
pass the unchanged `documentStateResult` from the get method as `baseDocumentState`.
If a node or parent that the changes refer to no longer exists in the model, the whole
update fails and nothing is applied. An empty difference succeeds without changes.
The server performs additional checks, so a state that matches the JSON Schema can
still be rejected with `422` `VALIDATION_ERROR`; `details.errors` lists the invalid fields.
A successful response means the changes are saved to the model and queued for delivery
to open editor sessions; it does not wait for the sessions to receive them.
An update that saves changes also triggers the Email Change Notification, if configured
in your plugin settings, with an empty `userId`.
If an error response contains `committed: true`, part of the operation was already saved:
read the current state and reconcile instead of repeating the request. Use `operationId`
when contacting support.
The request body is limited to 20 MiB. Requires the `EMAIL` `MODIFY` permission when
the Email Resources Permissions API is enabled.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [targetDocumentState]
properties:
targetDocumentState:
$ref: '#/components/schemas/DocumentState'
baseDocumentState:
$ref: '#/components/schemas/DocumentState'
responses:
'200':
description: The differences were applied and saved.
content:
application/json:
schema:
type: object
required: [appliedActions, generatedPatchesCount]
properties:
appliedActions:
type: integer
minimum: 0
description: Number of changes applied to the model.
generatedPatchesCount:
type: integer
minimum: 0
description: Number of patches saved to the model history.
example: {appliedActions: 4, generatedPatchesCount: 1}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
default:
$ref: '#/components/responses/DocumentStateFailure'
/coediting/v1/document-state/schema:
get:
tags: [Methods]
operationId: getPluginDocumentStateSchema
summary: Get the document state JSON Schema
description: |
Returns the JSON Schema that describes the document state for the current version
of the editor. Use it to validate document states before sending them with the update
method. The schema changes together with the editor, so fetch it rather than storing a copy.
Requires only a plugin token with the `API` role. The `ES-PLUGIN-UI-DATA` header is not
needed and is ignored if sent.
parameters:
- $ref: '#/components/parameters/TraceId'
responses:
'200':
description: The current document state schema.
content:
application/json:
schema:
type: object
required: [documentStateSchema]
properties:
documentStateSchema:
type: object
additionalProperties: true
example:
documentStateSchema: {$schema: 'http://json-schema.org/draft-07/schema#', type: object}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
default:
$ref: '#/components/responses/DocumentStateFailure'
components:
securitySchemes:
pluginAuth:
type: apiKey
in: header
name: ES-PLUGIN-AUTH
description: Bearer plugin token with the API role, for example `Bearer YOUR_AUTH_TOKEN`. The header is limited to 2000 bytes.
parameters:
EmailUIData:
name: ES-PLUGIN-UI-DATA
in: header
required: true
description: |
URL-encoded JSON object with the `emailId` of the email, the same value you pass in
`metadata` on editor initialization. For example, `{"emailId":"123"}` is sent as
`%7B%22emailId%22%3A%22123%22%7D`. The `emailId` must be a non-blank string of at most
100 bytes; the encoded header is limited to 3000 bytes. Other string values of the
object are passed to the Email Resources Permissions API callback as `uiData`.
schema: {type: string}
example: '%7B%22emailId%22%3A%22123%22%7D'
TraceId:
name: X-Trace-ID
in: header
required: false
description: Optional trace ID of your request, at most 100 bytes. Include it when contacting support.
schema: {type: string}
responses:
RateLimited:
description: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.
headers:
Retry-After:
schema: {type: integer, minimum: 0}
content:
text/plain:
schema: {type: string}
example: Too Many Requests
BadRequest:
description: |
Invalid `ES-PLUGIN-UI-DATA` or `X-Trace-ID` header, invalid content type or JSON body, missing `targetDocumentState`, or a document state body over 20 MiB.
Depending on the check, the body is a JSON error object with the `BAD_REQUEST` code
or a text response with a message.
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentStateError'
text/plain:
schema: {type: string}
example: '{"Message":"Content-Type must be application/json"}'
Unauthorized:
description: Missing or invalid plugin token.
content:
text/plain:
schema: {type: string}
example: '{"Message":"Unauthorized"}'
Forbidden:
description: The token does not have the `API` role, or the required `EMAIL` permission was not granted. `MODIFY` does not imply `READ`.
content:
text/plain:
schema: {type: string}
example: '{"Message":"Forbidden"}'
DocumentStateFailure:
description: |
Other errors: `404` the email has no model; `405` wrong HTTP method; `408` `CANCELED`;
`409` `REVISION_CONFLICT` or `STALE_DOCUMENT_STATE` (the model changed while the update
was being applied: read the current state and repeat); `413` the payload is too large;
`422` `VALIDATION_ERROR`, `PARSE_ERROR`, `SIDE_EFFECT_UNAVAILABLE`, `MERGE_ERROR` or
`PATCH_APPLICATION_HANGS`; `500` `INTERNAL`; `504` `TIMEOUT`.
Retry only when `retryable` is `true`.
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentStateError'
schemas:
DocumentState:
type: object
additionalProperties: true
description: Document state of the email. Get the full structure from the schema method; it is not duplicated here.
CreateEmailRequest:
type: object
additionalProperties: false
required: [html, author]
properties:
html:
type: string
minLength: 1
description: HTML of the email. Required, non-empty.
css:
type: string
default: ''
description: CSS of the email. Optional; omitted means an empty string. `null` is not allowed.
author:
type: string
minLength: 1
description: Author recorded in the version history of the email, for example an email address. Required, non-blank, at most 254 bytes.
variables:
type: object
additionalProperties: true
default: {}
description: Email variables (CSS custom properties) as a JSON object. Scalars, arrays and `null` are rejected.
supportOutlookButtonsByDefault:
type: boolean
default: true
description: |
Whether buttons are exported with Outlook (VML) markup by default. Pass `false` to disable it for the new email.
The default here is `true`, while the default of the corresponding
`supportOutlookButtonsByDefault` editor initialization parameter is `false`.
utm:
$ref: '#/components/schemas/UTM'
UTM:
type: object
nullable: true
additionalProperties: false
description: UTM parameters stored with the email. Omitted or `null` means no UTM configuration. Standard values default to an empty string and cannot be `null`; each value is limited to 2 KiB.
properties:
utmSource: {type: string, default: ''}
utmMedium: {type: string, default: ''}
utmCampaign: {type: string, default: ''}
utmContent: {type: string, default: ''}
utmTerm: {type: string, default: ''}
customUtms:
type: array
maxItems: 100
default: []
description: Custom UTM parameters. Names must be unique (case-sensitive) and at most 256 bytes. `null` is not allowed.
items:
type: object
additionalProperties: false
required: [name, value]
properties:
name: {type: string, minLength: 1}
value: {type: string}
DocumentStateError:
type: object
required: [code, message]
properties:
code: {type: string}
message: {type: string}
stage:
type: string
description: Processing step where the error occurred.
retryable: {type: boolean}
committed:
type: boolean
description: '`true` when part of the update was already saved before the error. Read the current state and reconcile instead of repeating the request.'
operationId:
type: string
description: Identifier of the operation. Include it when contacting support.
details:
type: object
additionalProperties: true
description: |
Bounded diagnostics, for example validation or parse errors. `truncated` indicates that some records were omitted.
Lists contain at most 100 entries: `errors` for `VALIDATION_ERROR` (entries with
`path` and `message`), `parseErrors` for `PARSE_ERROR`, and
`unavailableSideEffects` for `SIDE_EFFECT_UNAVAILABLE`.
CreateEmailError:
type: object
required: [code, message, stage, retryable]
properties:
code: {type: string}
message: {type: string}
stage:
type: string
description: Processing step where the error occurred. For diagnostics only; the values may change.
source:
type: string
description: Part of the request that the error relates to, when known, for example `author` or `input-css`.
retryable: {type: boolean}
location:
type: object
description: Position in the CSS for parse errors.
properties:
startLine: {type: integer}
startColumn: {type: integer}
endLine: {type: integer}
endColumn: {type: integer}Deleting Email Models
Delete one or multiple email models programmatically. This API method creates a background deletion job for the email models you select, either by their unique identifiers, by a prefix of the identifier, or both. Up to 1000 explicit identifiers can be passed per call. A prefix pattern such as qaautomation1-* selects every model of your plugin whose identifier starts with the given prefix; the number of models matched by a pattern is not limited. Deleted models are permanently removed and cannot be restored. Use this endpoint to manage email model lifecycle in automation pipelines, integrations, or bulk cleanup workflows, for example, to clear test models created across several environments without keeping a list of their identifiers. A pattern must contain exactly one * at the end, preceded by at least three literal characters. Matching is case-sensitive and limited to the plugin's authenticated models in the request. The 202 response confirms that the job was accepted; check the job status and per-model results to confirm that deletion finished.
OpenAPI Specification
Reference
yaml
openapi: 3.0.3
info:
title: Asynchronous Email Model Deletion API
version: 1.1.0
description: |
Delete emails by submitting their IDs, literal
email-ID prefixes, or their union. Requests require a plugin token with the API role
and apply only to emails belonging to that plugin.
A 202 response confirms that a deletion job was stored, not that deletion finished.
If needed, poll the job and inspect its item results before considering the request complete.
Deleted data cannot be restored.
contact:
name: Stripo Support
url: https://stripo.email
servers:
- url: https://plugins.stripo.email
description: Stripo Plugin API server
security:
- pluginAuth: []
tags:
- name: Methods
description: Email model deletion jobs
paths:
/coediting/v1/emails/delete-jobs:
post:
tags: [Methods]
operationId: createEmailDeleteJob
summary: Create an email deletion job
description: |
Accepts `emailIds`, `emailIdPatterns`, or both. At least one array must be
nonempty. A field may be omitted or empty when the other is nonempty;
explicit null, non-array values, invalid elements, and unknown fields
return 400 before a job is created. The request body is limited to 1 MiB.
`emailIds` are literal IDs, including any `*`.
At most 1000 distinct explicit IDs are accepted.
Duplicate IDs and overlapping selections are processed once.
Each pattern must contain exactly one `*`, at the end, after at least
three literal Unicode code points. Matching preserves case and treats
`%`, `_`, and `!` in the prefix as literal characters.
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDeleteJobRequest'
examples:
singleEmail:
summary: Delete one email model
value:
emailIds: [email-123]
multipleEmails:
summary: Delete multiple email models
value:
emailIds: [email-123, email-456]
prefixOnly:
summary: Delete models matching either literal prefix
value:
emailIdPatterns: ['qaautomation1-*', 'gluautomation2-*']
mixedSelection:
summary: Combine literal IDs and prefixes with deduplication
value:
emailIds: [email-123, 'literal*']
emailIdPatterns: ['qaautomation1-*', 'QA_%!*']
emptyIdsWithPrefix:
summary: An empty emailIds array is valid with a nonempty pattern array
value:
emailIds: []
emailIdPatterns: ['qaautomation1-*']
idsWithEmptyPatterns:
summary: An empty pattern array is valid with nonempty emailIds
value:
emailIds: [email-123]
emailIdPatterns: []
responses:
'202':
description: Job persisted. Deletion may still be pending or running.
headers:
Location:
description: Relative URL of the job status endpoint.
schema:
type: string
example: /coediting/v1/emails/delete-jobs/gcj_0123456789abcdef0123456789abcdef
X-Trace-Id:
$ref: '#/components/headers/TraceId'
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteJob'
examples:
queued:
$ref: '#/components/examples/QueuedJob'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'409':
$ref: '#/components/responses/Conflict'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
'500':
$ref: '#/components/responses/InternalServerError'
/coediting/v1/emails/delete-jobs/{jobId}:
get:
tags: [Methods]
operationId: getEmailDeleteJob
summary: Get deletion job status and progress
description: |
Returns the current state. The `total`, `remaining`, and `percentage`
progress fields are null until discovery finishes. `discovered` counts
unique candidates across both selector arrays.
parameters:
- $ref: '#/components/parameters/JobId'
responses:
'200':
description: Current job status and progress.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteJob'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
'500':
$ref: '#/components/responses/InternalServerError'
/coediting/v1/emails/delete-jobs/{jobId}/items:
get:
tags: [Methods]
operationId: listEmailDeleteJobItems
summary: List per-email results
description: |
Returns one page of results for the authenticated plugin's job.
Follow `nextCursor` until it is absent. The cursor is opaque.
Results may change while the job is running; inspect them again after
a terminal job status if a final accounting is required.
parameters:
- $ref: '#/components/parameters/JobId'
- name: cursor
in: query
required: false
description: Opaque `nextCursor` returned by the previous page.
schema:
type: string
- name: pageSize
in: query
required: false
description: Items per page; defaults to 50.
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: status
in: query
required: false
description: Optional case-insensitive item-status filter.
schema:
$ref: '#/components/schemas/ItemStatus'
responses:
'200':
description: Page of per-email results.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteJobItemsPage'
examples:
firstPage:
value:
items:
- emailId: email-123
status: SUCCEEDED
attempt: 1
error: null
- emailId: email-456
status: FAILED
attempt: 1
error:
code: ROW_TOO_LARGE
message: The email could not be processed
nextCursor: "2"
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
$ref: '#/components/responses/ServiceUnavailable'
'500':
$ref: '#/components/responses/InternalServerError'
components:
securitySchemes:
pluginAuth:
type: apiKey
in: header
name: ES-PLUGIN-AUTH
description: Bearer plugin token with the API role, for example `Bearer YOUR_AUTH_TOKEN`.
parameters:
JobId:
name: jobId
in: path
required: true
description: Job ID returned by the create endpoint.
schema:
type: string
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: |
Retry key scoped to the plugin and DELETE operation. The same key and
normalized selector arrays return the existing job. Order and duplicate
selectors do not change the selection identity; both `emailIds` and
`emailIdPatterns` participate. Reusing the key with a different selector
set returns 409. Keep the returned job ID for subsequent reads;
idempotency is limited by the lifetime of the stored job.
schema:
type: string
headers:
TraceId:
description: Trace identifier for support and diagnostics.
schema:
type: string
schemas:
CreateDeleteJobRequest:
type: object
additionalProperties: false
description: |
Provide a nonempty emailIds array, a nonempty emailIdPatterns array,
or both. Either field may be omitted or empty when the other is
nonempty. Neither field nor its elements may be null.
anyOf:
- required: [emailIds]
properties:
emailIds:
minItems: 1
- required: [emailIdPatterns]
properties:
emailIdPatterns:
minItems: 1
properties:
emailIds:
type: array
description: |
Literal email IDs in this plugin's namespace; `*` has no wildcard
meaning in this array. At most 1000 distinct IDs are accepted,
subject to a potentially lower server-configured limit. Each ID must be
nonblank and at most 100 UTF-8 bytes, and the composed plugin model
ID must also fit its server limit. Double quotes, backslashes, tabs,
carriage returns, and newlines are rejected in IDs. Duplicates are
accepted and processed once. maxLength is a Unicode-code-point
upper bound; the server additionally enforces the UTF-8 byte limit.
items:
type: string
minLength: 1
maxLength: 100
pattern: '^[^"\\\r\n\t]+$'
not:
anyOf:
- pattern: '^[\u0009-\u000d \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]*$'
- pattern: '["\\\r\n\t]'
example: [email-123, email-456]
emailIdPatterns:
type: array
description: |
Literal email-ID prefixes in this plugin's namespace, each followed
by one terminal wildcard. Duplicate and overlapping patterns are
accepted; every discovered email is processed once. There is no
per-pattern result count or limit of 1000 discovered candidates.
items:
$ref: '#/components/schemas/EmailIDPattern'
example: ['qaautomation1-*', 'gluautomation2-*']
EmailIDPattern:
type: string
minLength: 4
maxLength: 101
pattern: '^[^*"\\\r\n\t]{3,}\*$'
not:
anyOf:
- pattern: '^[\u0009-\u000d \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]*\*$'
- pattern: '["\\\r\n\t]'
description: |
Exactly one `*` is required at the end, preceded by at least three
literal Unicode code points. The prefix must not consist entirely of
whitespace and must fit 100 UTF-8 bytes; the composed plugin model-ID
prefix must also fit its server limit. maxLength is a Unicode-code-point
upper bound; the server additionally enforces the UTF-8 byte limit.
Double quotes, backslashes, tabs, carriage returns, and newlines are
forbidden in the prefix. Matching is case-sensitive; `%`, `_`, and `!`
are literal. IDs and prefixes are not trimmed or lowercased.
example: 'qaautomation1-*'
JobStatus:
type: string
enum:
- QUEUED
- SCANNING
- RUNNING
- PAUSE_REQUESTED
- PAUSED
- STOP_REQUESTED
- STOPPED
- COMPLETED
- COMPLETED_WITH_ERRORS
- FAILED
ItemStatus:
type: string
enum:
- PENDING
- RUNNING
- SUCCEEDED
- SKIPPED
- FAILED
- NOT_PROCESSED
DeleteJob:
type: object
additionalProperties: false
required: [jobId, status, createdAt, startedAt, finishedAt, expiresAt, progress]
properties:
jobId:
type: string
status:
$ref: '#/components/schemas/JobStatus'
createdAt:
type: string
format: date-time
startedAt:
type: string
format: date-time
nullable: true
finishedAt:
type: string
format: date-time
nullable: true
expiresAt:
type: string
format: date-time
description: Time after which the job and its items may no longer be available.
progress:
$ref: '#/components/schemas/DeleteJobProgress'
DeleteJobProgress:
type: object
additionalProperties: false
required: [total, discovered, processed, running, succeeded, skipped, failed, remaining, percentage]
properties:
total:
type: integer
format: int64
nullable: true
description: Final unique candidate count; null until discovery finishes.
discovered:
type: integer
format: int64
description: Unique candidates recorded so far across IDs and patterns.
processed:
type: integer
format: int64
description: Sum of succeeded, skipped, and failed items.
running:
type: integer
format: int64
succeeded:
type: integer
format: int64
skipped:
type: integer
format: int64
failed:
type: integer
format: int64
remaining:
type: integer
format: int64
nullable: true
percentage:
type: number
format: double
nullable: true
DeleteJobItemsPage:
type: object
additionalProperties: false
required: [items]
properties:
items:
type: array
items:
$ref: '#/components/schemas/DeleteJobItem'
nextCursor:
type: string
description: Omitted when there is no next page.
DeleteJobItem:
type: object
additionalProperties: false
required: [emailId, status, attempt, error]
properties:
emailId:
type: string
status:
$ref: '#/components/schemas/ItemStatus'
attempt:
type: integer
minimum: 0
error:
$ref: '#/components/schemas/ItemError'
ItemError:
type: object
nullable: true
additionalProperties: false
required: [code, message]
properties:
code:
type: string
description: Machine-readable reason; possible codes can evolve.
example: ROW_TOO_LARGE
message:
type: string
description: Human-readable explanation.
ErrorResponse:
type: object
required: [Message]
properties:
Message:
type: string
examples:
QueuedJob:
value:
jobId: gcj_0123456789abcdef0123456789abcdef
status: QUEUED
createdAt: '2026-09-29T08:00:00Z'
startedAt: null
finishedAt: null
expiresAt: '2026-09-30T08:00:00Z'
progress:
total: null
discovered: 0
processed: 0
running: 0
succeeded: 0
skipped: 0
failed: 0
remaining: null
percentage: null
responses:
ControlAccepted:
description: Control accepted; the returned job state may still be transitional.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteJob'
BadRequest:
description: |
Invalid body, empty combined selection, null or malformed selector
arrays, invalid email IDs or patterns, excess distinct explicit IDs,
unknown request fields, cursor, status filter, or page size.
content:
text/plain:
schema:
type: string
example: '{"Message":"emailIds or emailIdPatterns must be nonempty"}'
Unauthorized:
description: Missing or invalid plugin authentication.
content:
text/plain:
schema:
type: string
example: '{"Message":"Unauthorized"}'
Forbidden:
description: The plugin token does not have the API role.
content:
text/plain:
schema:
type: string
example: '{"Message":"Forbidden: insufficient permissions"}'
NotFound:
description: Job not found, expired, owned by another plugin, or for another operation.
content:
text/plain:
schema:
type: string
example: '{"Message":"Not Found"}'
MethodNotAllowed:
description: HTTP method is not supported for this path.
content:
text/plain:
schema:
type: string
example: '{"Message":"Method Not Allowed"}'
Conflict:
description: Idempotency key reused for another selection or invalid control transition.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
Message: Conflict
TooManyRequests:
description: Rate limit exceeded. Retry after the indicated delay.
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-Rate-Limit-Reset:
description: Unix timestamp when the limit resets.
schema:
type: integer
format: int64
content:
text/plain:
schema:
type: string
example: Too Many Requests
ServiceUnavailable:
description: The service is temporarily unavailable. Try again later.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
Message: Service Unavailable
InternalServerError:
description: Unexpected server error; include the X-Trace-Id in support requests.
content:
text/plain:
schema:
type: string
example: '{"Message":"Internal server error, lookup traceId in headers for more information"}'Retrieving Plugin Modules
This API call allows you to retrieve a list of email template modules (also known as custom blocks) created within your Stripo Plugin environment.
You can use this endpoint to fetch all modules associated with your plugin, including their metadata, icons, HTML/CSS content, categories, and synchronization status.
For faster response, modules are returned without HTML/CSS content by default. If you need to include it, set the withContent parameter to true
OpenAPI Specification
Reference
yaml
openapi: 3.0.3
info:
title: Retrieving Plugin Modules API
description: |
This API specification describes the endpoint for retrieving plugin modules
from the Stripo Email Editor plugin backend service.
The endpoint allows authenticated plugins to list and filter their custom email
template modules (blocks) with advanced filtering, pagination, and sorting capabilities.
**Authentication**: Plugin-based authentication using the `ES-PLUGIN-AUTH` header.
The authentication token must have the role set to "API" to access this endpoint.
**Authorization**: Only modules belonging to the authenticated plugin are returned.
Cross-plugin access is not permitted.
**Performance Optimization**: Use the `withContent` parameter to include HTML and CSS
content in responses. By default, content is excluded for optimal performance.
**Filtering Capabilities**: Support for filtering by key, category, tags, synchronization
status, and full-text search on module names.
**Pagination**: Flexible pagination using either offset-based or page-based approaches
with configurable page sizes.
version: 1.0.0
contact:
name: Stripo Support
url: https://stripo.email
servers:
- url: https://plugins.stripo.email
description: Plugin Backend Service
security:
- pluginAuth: []
paths:
/api/v1/customblocks/v4/modules/list:
get:
summary: List plugin modules
tags:
- Methods
operationId: getModulesList
description: |
Retrieve a paginated and filterable list of all plugin modules belonging to
the authenticated plugin.
**Authorization**: Only modules associated with the plugin identified by the
provided authentication token are returned. The token must have "API" role.
**Performance**: By default, HTML and CSS content are excluded for optimal performance.
Set `withContent=true` to include HTML and CSS content in the response.
**Filtering**: Combine multiple filters (key, query, categories, tags, id,
synchronizable) to narrow down results. All filters are applied with AND logic.
**Sorting**: Results can be sorted by `id` or `name` in ascending or descending order.
**Pagination**: Use either `offset` for cursor-based pagination or `page` for
page-based pagination. The `limit` parameter controls the page size (default: 20).
security:
- pluginAuth: []
parameters:
- in: header
name: ES-PLUGIN-AUTH
description: |
Plugin authentication token with "API" role. Must be in Bearer token format.
required: true
schema:
type: string
example: Bearer YOUR_AUTH_TOKEN
- in: query
name: key
description: |
Filter by module key (folder name). Returns modules matching the specified key.
required: false
schema:
type: string
example: "header-templates"
- in: query
name: query
description: |
Full-text search query for module name.
required: false
schema:
type: string
example: "newsletter"
- in: query
name: categories
description: |
Filter by one or more category IDs. Returns modules belonging to any of the
specified categories.
required: false
schema:
type: array
items:
type: integer
format: int64
example: [1, 2, 5]
- in: query
name: tags
description: |
Filter by one or more tag values. Returns modules that have any of the
specified tags.
required: false
schema:
type: array
items:
type: string
example: ["promotional", "seasonal"]
- in: query
name: id
description: |
Filter by specific module ID. When provided, returns only the module with
this exact ID (if it belongs to the authenticated plugin).
required: false
schema:
type: integer
format: int64
example: 12345
- in: query
name: synchronizable
description: |
Filter by synchronizable status. Set to `true` for synchronizable modules only,
`false` for non-synchronizable modules only, or omit for all modules.
required: false
schema:
type: boolean
example: true
- in: query
name: withContent
description: |
Performance optimization flag. When set to `true`, the `html` and `css` fields
will be included in the response. By default (`false`), content is excluded
to reduce response size when only module metadata is needed.
required: false
schema:
type: boolean
default: false
example: false
- in: query
name: sortingColumn
description: |
Column to sort results by. Options are `id` (module ID) or `name` (module name).
required: false
schema:
type: string
enum: [id, name]
default: id
example: "name"
- in: query
name: sortingAsc
description: |
Sort direction. Set to `true` for ascending order, `false` for descending order.
required: false
schema:
type: boolean
default: false
example: true
- in: query
name: offset
description: |
Zero-based pagination offset. Specifies the starting position in the result set.
Takes precedence over the `page` parameter when both are provided.
required: false
schema:
type: integer
minimum: 0
default: 0
example: 0
- in: query
name: page
description: |
One-based page number for pagination. Used only if `offset` is not provided.
Calculated as: offset = (page - 1) * limit
required: false
schema:
type: integer
minimum: 1
example: 1
- in: query
name: limit
description: |
Maximum number of modules to return per page. Controls the page size for pagination.
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
example: 20
responses:
'200':
description: |
Modules list retrieved successfully. Returns a paginated list of modules
with metadata and optionally HTML/CSS content.
content:
application/json:
schema:
$ref: '#/components/schemas/ModulesListResponseDto'
examples:
basicList:
summary: Basic module list with content (withContent=true)
value:
modules:
- id: 12345
key: "header-templates"
name: "Modern Header"
html: "<table>...</table>"
css: ".header { padding: 20px; }"
blockType: "BASIC"
scope: "HEADER"
icon: "https://example.com/icon.png"
croppedIcon: "https://example.com/icon-cropped.png"
description: "A modern header template"
synchronizable: true
tags: ["modern", "responsive"]
tagObjects:
- id: 1
value: "modern"
- id: 2
value: "responsive"
category:
key: 1
name: "Headers"
createdOn: "2024-01-15T10:30:00Z"
updatedOn: "2024-01-20T14:45:00Z"
total: 1
offset: 0
limit: 20
metadataOnly:
summary: Module list without content (default, withContent=false)
value:
modules:
- id: 12345
key: "header-templates"
name: "Modern Header"
html: null
css: null
blockType: "BASIC"
scope: "HEADER"
icon: "https://example.com/icon.png"
croppedIcon: "https://example.com/icon-cropped.png"
description: "A modern header template"
synchronizable: true
tags: ["modern", "responsive"]
category:
key: 1
name: "Headers"
createdOn: "2024-01-15T10:30:00Z"
updatedOn: "2024-01-20T14:45:00Z"
total: 1
offset: 0
limit: 20
emptyList:
summary: Empty result set
value:
modules: []
total: 0
offset: 0
limit: 20
'401':
description: |
Unauthorized - Authentication failed. This can occur when:
- The authentication token is missing or invalid
- The token has expired
- The token does not have "API" role
content:
application/json:
schema:
type: object
'403':
description: |
Forbidden - The authenticated plugin does not have permissions to access modules.
This typically indicates an authorization configuration issue.
content:
application/json:
schema:
type: object
components:
securitySchemes:
pluginAuth:
type: apiKey
in: header
name: ES-PLUGIN-AUTH
description: |
Plugin authentication using Bearer token in the ES-PLUGIN-AUTH header.
The token must have "API" role to access this endpoint.
schemas:
ModulesListResponseDto:
type: object
description: Response containing a paginated list of plugin modules with metadata
properties:
modules:
type: array
items:
$ref: '#/components/schemas/ModuleListItemDto'
description: |
Array of module objects. Each module contains metadata and optionally
HTML/CSS content (depending on the `withContent` parameter).
total:
type: integer
format: int64
description: |
Total count of modules matching the filter criteria (across all pages).
Used for calculating pagination metadata.
minimum: 0
example: 42
offset:
type: integer
description: |
Current pagination offset (starting position in the result set).
Corresponds to the `offset` parameter from the request.
minimum: 0
example: 0
limit:
type: integer
description: |
Maximum number of modules returned in this page.
Corresponds to the `limit` parameter from the request.
minimum: 1
example: 20
ModuleListItemDto:
type: object
description: Represents a single plugin module with all its metadata and optional content
properties:
id:
type: integer
format: int64
description: |
Unique identifier of the module within the plugin.
example: 12345
key:
type: string
description: |
Module key (folder name). Used for organizing modules into logical groups.
example: "header-templates"
name:
type: string
description: |
Human-readable name of the module. Displayed in the editor's module library.
example: "Modern Header"
html:
type: string
nullable: true
description: |
HTML content of the module. Contains the email template markup.
This field will be `null` when `withContent=false` (default) or not specified.
example: "<table>...</table>"
css:
type: string
nullable: true
description: |
CSS styles for the module. Applied to the HTML content when rendered.
This field will be `null` when `withContent=false` (default) or not specified.
example: ".header { padding: 20px; }"
blockType:
type: string
description: |
Type of block. Determines how the module behaves in the editor.
example: "STRUCTURE"
scope:
type: string
description: |
Defines the section of the email where this module can be used.
Modules are organized by scope in the editor's module library.
enum: [INFO_AREA, HEADER, MENU, CONTENT, FOOTER]
example: "HEADER"
icon:
type: string
description: |
URL to the module's icon image. Displayed as thumbnail in the module library.
example: "https://example.com/icons/header-modern.png"
croppedIcon:
type: string
description: |
URL to the cropped version of the module's icon. Used for optimized display.
example: "https://example.com/icons/header-modern-cropped.png"
description:
type: string
description: |
Textual description of the module. Provides additional context about the
module's purpose and design.
example: "A modern, responsive header template with logo and navigation"
synchronizable:
type: boolean
description: |
Indicates whether this module supports synchronization. Synchronized modules
can be updated across multiple email templates automatically.
example: true
tags:
type: array
items:
type: string
description: |
List of tag values associated with the module. Tags provide additional
categorization and filtering capabilities. This is a simplified array
of string values.
example: ["modern", "responsive", "promotional"]
tagObjects:
type: array
items:
type: object
properties:
id:
type: integer
format: int64
description: Unique identifier of the tag
example: 1
value:
type: string
description: Tag value (name)
example: "modern"
description: |
List of tag objects with full details including tag IDs. Provides more
complete information than the `tags` array.
category:
type: object
properties:
key:
type: integer
format: int64
description: |
Unique identifier of the category.
example: 1
name:
type: string
description: |
Human-readable name of the category.
example: "Headers"
description: |
Category information for the module. Categories provide high-level
organization of modules in the editor's library.
createdOn:
type: string
format: date-time
description: |
ISO 8601 timestamp indicating when the module was created.
example: "2024-01-15T10:30:00Z"
updatedOn:
type: string
format: date-time
description: |
ISO 8601 timestamp indicating when the module was last updated.
example: "2024-01-20T14:45:00Z"
tags:
- name: Methods
description: Plugin module management operationsDeleting Plugin Modules
Soft-delete one or multiple plugin modules programmatically. This API method allows you to mark multiple plugin modules as deleted by their unique identifiers in a single request. Deleted modules are not physically removed from the database — they are marked as deleted and will no longer appear in the module library or API responses.
Each module ID in the request is validated against the authenticated plugin — if any module does not belong to the plugin or does not exist, the entire request is rejected with a 403 Forbidden response and no modules are deleted.
Use this endpoint to manage the module lifecycle in automation pipelines, integrations, or bulk cleanup workflows.
OpenAPI Specification
Reference
yaml
openapi: 3.0.3
info:
title: Delete Plugin Modules API
description: |
This API call bulk soft-deletes plugin modules from the module library.
Modules are marked as deleted and are not physically removed from the database.
**Authentication**: Plugin-based authentication using custom headers.
Requires a valid plugin authentication token.
**Authorization**: Only users with "API" role are permitted to use this endpoint.
Other roles will receive a 403 Forbidden response.
**Ownership Validation**: Each module ID in the request is validated to ensure it
belongs to the authenticated plugin. If any module belongs to a different plugin,
the entire request is rejected with 403 and no modules are deleted.
**Behaviour**:
- Modules that belong to the plugin are soft-deleted (marked as `deleted = true`).
- If any `moduleId` belongs to another plugin, the request is rejected with 403
and no module is deleted.
- Non-existent `moduleIds` are silently skipped.
version: 1.0.0
contact:
name: Stripo Support
url: https://stripo.email
servers:
- url: https://plugins.stripo.email
description: Stripo Plugin API server
security:
- pluginAuth: []
paths:
/api/v1/customblocks/v4/modules/bulk-delete:
post:
summary: Bulk soft-delete modules
description: |
Soft-deletes a list of plugin modules by their IDs. Requires a token with the "API" role.
Each module ID is verified to belong to the plugin identified by the authentication token.
operationId: bulkDeleteModules
tags:
- Methods
security:
- pluginAuth: []
parameters:
- name: ES-PLUGIN-AUTH
in: header
required: true
description: "Stripo plugin auth token in the format — Bearer ${AUTH_TOKEN}. Must have the 'API' role."
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkDeleteModulesRequest'
examples:
singleModule:
summary: Delete a single module
value:
moduleIds: [101]
multipleModules:
summary: Delete multiple modules
value:
moduleIds: [101, 102, 103]
bulkDeletion:
summary: Bulk deletion of modules
value:
moduleIds:
- 101
- 102
- 103
- 104
- 105
responses:
'204':
description: |
All modules soft-deleted successfully. No response body is returned.
'400':
description: |
Bad request — moduleIds must not be empty or array too large.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
noModuleIds:
summary: No module IDs provided
value:
message: "moduleIds must not be empty"
tooManyIds:
summary: Too many module IDs in request
value:
message: "Too many module IDs (max 1000)"
'401':
description: |
Unauthorized — ES-PLUGIN-AUTH header is missing or the token is invalid or expired.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
authFailed:
summary: Authentication failed
value:
message: "Unauthorized"
'403':
description: |
Forbidden — either the token does not have the "API" role, or at least one
of the provided moduleIds belongs to another plugin. In the latter case no
module is deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
insufficientPermissions:
summary: User lacks required role
value:
message: "Forbidden: insufficient permissions"
foreignModule:
summary: Module belongs to another plugin
value:
message: "Forbidden: one or more modules do not belong to the authenticated plugin"
'500':
description: |
Internal server error — Failed to delete modules.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
deleteFailed:
summary: Deletion operation failed
value:
message: "Internal server error, lookup traceId in headers for more information"
components:
securitySchemes:
pluginAuth:
type: apiKey
in: header
name: ES-PLUGIN-AUTH
description: |
Plugin authentication using Bearer token in the ES-PLUGIN-AUTH header.
The token must have "API" role to access this endpoint.
schemas:
BulkDeleteModulesRequest:
type: object
description: Request body containing module IDs to soft-delete.
required:
- moduleIds
properties:
moduleIds:
type: array
description: |
List of module IDs to soft-delete. Min: 1, max: 1000.
All IDs must belong to the plugin identified by the authentication token.
Non-existent IDs are silently skipped.
items:
type: integer
format: int64
minItems: 1
maxItems: 1000
example: [101, 102, 103]
ErrorResponse:
type: object
properties:
message:
type: string
description: Human-readable error description
example: "moduleIds must not be empty"
tags:
- name: Methods
description: Plugin module management operationsTemplate Themes
Manage Template Themes from your backend: list, create, update, and delete themes, get the list of emails linked to a theme, apply a theme to one email or to many emails in one request, and detach a theme from an email. These methods require a plugin token of the API role and Template Themes enabled in your plugin settings. None of them requires an open editor.
All methods resolve the themes key from the Themes key template of your plugin settings. If the template contains variables, pass their values in the Es-Plugin-Ui-Data header as a URL-encoded JSON object with string values, the same values you pass in metadata on editor initialization. If the key template is empty, the header is not needed. The request body carries only the data of the operation itself, such as the theme name and settings or the IDs of the emails to change.
Applying a theme links it to the email immediately; the HTML and CSS of the email are compiled with the theme on the next compilation (next open, export, or an HTML request through the API). This is the same behavior as applying a theme in the editor.
OpenAPI Specification
Reference
yaml
openapi: 3.0.3
info:
title: Template Themes API
version: 1.0.0
description: >-
A template theme is a reusable set of email design settings, such as colors, fonts, spacing
and button styles. Use this API to create and manage themes, apply a theme to one or more
emails, and see which emails use it.
Enable Template Themes in your plugin settings and authenticate requests with a plugin token
that has the API role. You can use this API without opening the editor. Unlinking an email
from a theme is also available when Template Themes is disabled.
Themes can be shared across your plugin or separated by brand, customer or another value
using the plugin's `keyTemplate` setting. If that setting contains placeholders, supply their
values in the `Es-Plugin-Ui-Data` header. See that header's description for details and an
example. Send the data for the operation itself in the request body where one is required.
contact:
name: Stripo Support
url: https://stripo.email
servers:
- url: https://plugins.stripo.email
description: Stripo Plugin API server
security:
- pluginAuth: []
tags:
- name: Methods
description: Create, manage and apply reusable email themes.
- name: Resource permissions
description: Control access to themes and other plugin resources through your own application.
paths:
/coediting/v1/template-themes:
get:
tags:
- Methods
operationId: listTemplateThemes
summary: List template themes
description: >-
Returns the themes available for your plugin and the values supplied in Es-Plugin-Ui-Data.
Requires READ permission for TEMPLATE_THEMES.
parameters:
- $ref: "#/components/parameters/PluginMetadata"
- $ref: "#/components/parameters/WithPreview"
responses:
"200":
description: The list of available themes.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/TemplateTheme"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"405":
$ref: "#/components/responses/MethodNotAllowed"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
post:
tags:
- Methods
operationId: createTemplateTheme
summary: Create a template theme
description: >-
Creates a reusable theme without changing any email. Requires MODIFY permission for
TEMPLATE_THEMES. The theme limit applies to the whole plugin, including themes separated
by brand, customer or other values. Sending the same request again may create another theme.
parameters:
- $ref: "#/components/parameters/PluginMetadata"
- $ref: "#/components/parameters/WithPreview"
responses:
"200":
description: The newly created theme.
content:
application/json:
schema:
$ref: "#/components/schemas/TemplateTheme"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"405":
$ref: "#/components/responses/MethodNotAllowed"
"409":
description: The maximum number of themes allowed for your plugin has been reached.
content:
application/json:
schema:
$ref: "#/components/schemas/ThemeQuotaError"
example:
code: TEMPLATE_THEMES_LIMIT_REACHED
maxEnabled: 10
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateTemplateThemeRequest"
examples:
canonicalSettings:
$ref: "#/components/examples/CreateTheme"
/coediting/v1/template-themes/{themeId}:
patch:
tags:
- Methods
operationId: updateTemplateTheme
summary: Update a template theme
description: >-
Changes a theme's name, design settings or both. Requires MODIFY permission for
TEMPLATE_THEMES. Set expectedVersion to the theme's current version and provide name,
json or both. The json field must contain the complete design settings as a JSON string.
Changing a setting increases the version. Renaming the theme or changing only JSON
formatting does not. If expectedVersion no longer matches, the request returns HTTP 409.
Retrieve the theme list again, review the latest settings and retry with the current version.
parameters:
- $ref: "#/components/parameters/PluginMetadata"
- $ref: "#/components/parameters/ThemeId"
- $ref: "#/components/parameters/WithPreview"
responses:
"200":
description: The theme after the update.
content:
application/json:
schema:
$ref: "#/components/schemas/TemplateTheme"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"405":
$ref: "#/components/responses/MethodNotAllowed"
"409":
description: expectedVersion does not match the theme's current version. Retrieve the latest theme before retrying.
content:
text/plain:
schema:
type: string
example: |
Conflict
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateTemplateThemeRequest"
example:
expectedVersion: 1
name: Updated theme
delete:
tags:
- Methods
operationId: deleteTemplateTheme
summary: Delete a template theme
description: >-
Deletes the theme and unlinks all emails that use it. Requires MODIFY permission for
TEMPLATE_THEMES.
parameters:
- $ref: "#/components/parameters/PluginMetadata"
- $ref: "#/components/parameters/ThemeId"
responses:
"204":
description: The theme was deleted. There is no response body.
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"405":
$ref: "#/components/responses/MethodNotAllowed"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/coediting/v1/template-themes/{themeId}/emails:
get:
tags:
- Methods
operationId: listTemplateThemeEmails
summary: List emails using a theme
description: >-
Returns the IDs of emails currently using this theme, in the same form as the email IDs
in your application. Emails that are still being copied are not included. If no emails
use the theme, returns an empty array. Requires READ permission for TEMPLATE_THEMES.
This request does not accept a body.
parameters:
- $ref: "#/components/parameters/PluginMetadata"
- $ref: "#/components/parameters/ThemeId"
responses:
"200":
description: The email IDs using this theme, or an empty array if there are none.
content:
application/json:
schema:
$ref: "#/components/schemas/ThemeEmailIds"
example:
- Welcome_2026
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"405":
$ref: "#/components/responses/MethodNotAllowed"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/coediting/v1/model/theme:
put:
tags:
- Methods
operationId: applyTemplateTheme
summary: Apply a template theme
description: >-
Selects a theme for the specified email. Requires READ permission for TEMPLATE_THEMES and
access to that email. The selection is saved when the request succeeds. The new design
appears the next time the email's HTML and CSS are generated. Repeating the request with
the same theme and version does not make further changes.
parameters:
- $ref: "#/components/parameters/PluginMetadata"
- $ref: "#/components/parameters/WithPreview"
responses:
"200":
description: The theme selected for the email.
content:
application/json:
schema:
$ref: "#/components/schemas/TemplateTheme"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"405":
$ref: "#/components/responses/MethodNotAllowed"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ApplyTemplateThemeRequest"
example:
emailId: qa-theme-1
themeId: a37dc20f-f2ce-4c4f-938a-57fc3e27e0be
delete:
tags:
- Methods
operationId: unlinkTemplateTheme
summary: Unlink a template theme
description: >-
Stops an email from using a theme while keeping the design settings already applied to
that email. Requires access to the email, but no TEMPLATE_THEMES permission or
Es-Plugin-Ui-Data header. This operation is available even if Template Themes is disabled
or the theme is no longer available.
responses:
"204":
description: The email is no longer linked to a theme.
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"405":
$ref: "#/components/responses/MethodNotAllowed"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UnlinkTemplateThemeRequest"
example:
emailId: qa-theme-1
/coediting/v1/model/theme/bulk-apply:
post:
tags:
- Methods
operationId: bulkApplyTemplateTheme
summary: Apply a template theme to multiple emails
description: >-
Applies one theme to multiple existing emails. Requires READ permission for TEMPLATE_THEMES
and access to the target emails. The Es-Plugin-Ui-Data header selects the available themes
for the entire request. The emailIds list must meet the request requirements before any
emails are changed. Duplicate IDs are handled once. Missing emails are not created.
Each email has its own result. HTTP 200 can include failed emails, even if none succeeded.
Check successfulEmailIds and failedEmails to see the outcome. A failure does not undo
successful changes. If the request is interrupted, completed changes are kept and you can
retry the same batch.
The new design appears the next time each email's HTML and CSS are generated. If an email
is open in the editor, you may need to reopen it to see the change.
parameters:
- $ref: "#/components/parameters/PluginMetadata"
responses:
"200":
description: Results for each email. Check both successfulEmailIds and failedEmails; HTTP 200 does not mean every email succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/BulkApplyThemeResult"
example:
successfulEmailIds:
- qa-theme-1
failedEmails:
- emailId: qa-theme-2
code: MODEL_NOT_FOUND
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"405":
$ref: "#/components/responses/MethodNotAllowed"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/BulkApplyThemeRequest"
example:
themeId: a37dc20f-f2ce-4c4f-938a-57fc3e27e0be
emailIds:
- qa-theme-1
- qa-theme-2
/:
servers:
- url: https://{YOUR_RESOURCE_PERMISSIONS_CHECKER_URL}
variables:
YOUR_RESOURCE_PERMISSIONS_CHECKER_URL:
default: ""
post:
tags:
- Resource permissions
summary: Check access to plugin resources
description: >-
This endpoint belongs to your application. When the Permissions API is enabled, Stripo
calls it to ask whether an operation is allowed. Protect the endpoint with HTTP Basic
authentication.
To allow access to a theme, return a grantPermissions entry with exactly the same type,
action and key as the requested permission. READ and MODIFY are separate permissions;
granting MODIFY does not also grant READ. Any permission not explicitly granted is denied.
Access is also denied if your endpoint cannot be reached, returns a response outside the
HTTP 2xx range or returns an invalid response. This check is not used when the Permissions
API is disabled in your plugin settings.
For TEMPLATE_THEMES, READ allows opening the editor with themes, listing themes, listing
emails that use a theme and applying a theme to one or more emails. MODIFY allows creating,
updating and deleting themes. Unlinking requires access to the email only. keyTemplate
explains how themes are grouped; you do not need to include it in grantPermissions.
security:
- basicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ResourcePermissionsRequest"
example:
pluginId: "123"
uiData:
brandId: acme
requestPermissions:
- type: TEMPLATE_THEMES
action: READ
key: pluginId123_brand_acme
keyTemplate: brand_${brandId}
responses:
"200":
description: The permissions your application grants for this request.
content:
application/json:
schema:
$ref: "#/components/schemas/ResourcePermissionsResponse"
example:
grantPermissions:
- type: TEMPLATE_THEMES
action: READ
key: pluginId123_brand_acme
components:
securitySchemes:
pluginAuth:
type: apiKey
in: header
name: ES-PLUGIN-AUTH
description: >-
Set the `ES-PLUGIN-AUTH` header to `Bearer <plugin JWT>`. Use a token for your plugin with
the `API` role.
basicAuth:
type: http
scheme: basic
parameters:
PluginMetadata:
name: Es-Plugin-Ui-Data
in: header
required: false
description: >-
Values used to select a group of themes, such as themes for a particular brand or customer.
Send a URL-encoded JSON object with string values. This header is required only if your
plugin's `keyTemplate` setting contains placeholders that need these values. For example,
`tenant_${tenantId}` needs a `tenantId` value identifying the customer. All placeholders
must have values, and the resulting key may contain only ASCII letters, digits, underscores
and hyphens.
To access the same themes as the editor, use the same values supplied in `uiData` when
opening the editor. If `keyTemplate` uses `${emailId}`, supply `emailId` here as well. An
`emailId` in this header selects the group of themes; `emailId` or `emailIds` in the request
body selects the emails to change.
The example is the URL-encoded form of `{"tenantId":"qa-theme-api"}`.
schema:
type: string
example: "%7B%22tenantId%22%3A%22qa-theme-api%22%7D"
WithPreview:
name: withPreview
in: query
required: false
description: >-
Set to true to include a theme preview as SVG markup in the response. Omit this parameter,
set it to false or leave its value empty to exclude the preview. Only true, false or an
empty value is accepted. Include this parameter at most once.
schema:
type: boolean
default: false
ThemeId:
name: themeId
in: path
required: true
description: The theme's id returned when you create or list themes.
schema:
type: string
minLength: 1
schemas:
TemplateTheme:
type: object
required:
- id
- name
- json
- version
- updatedAt
properties:
id:
type: string
format: uuid
description: Unique theme ID assigned by Stripo. Use this value as themeId in other requests.
name:
type: string
description: The theme's name, including any spaces supplied at the beginning or end.
json:
type: string
description: >-
Email design settings encoded as a JSON string. Numeric values are preserved when
creating a theme. Later responses may use different JSON formatting, so read this
value as JSON rather than comparing the text character by character.
version:
type: integer
format: int64
description: >-
Theme version, starting at 1. Increases when design settings change. Renaming the
theme or changing only JSON formatting does not increase it. Use this value as
expectedVersion when updating the theme.
minimum: 1
preview:
type: string
description: A preview of the theme as SVG markup. Included only when withPreview=true.
updatedAt:
type: integer
format: int64
description: When the theme was last updated, as milliseconds since January 1, 1970, 00:00:00 UTC.
ThemeQuotaError:
type: object
required:
- code
- maxEnabled
properties:
code:
type: string
enum:
- TEMPLATE_THEMES_LIMIT_REACHED
maxEnabled:
type: integer
format: int64
description: Maximum number of themes allowed across your entire plugin.
CreateTemplateThemeRequest:
type: object
required:
- name
- json
description: >-
Provide a name and a complete set of email design settings in a single JSON object.
The json field accepts either a JSON object or a string containing that object.
properties:
name:
type: string
minLength: 1
maxLength: 100
pattern: \S
x-stripo-maxUtf16CodeUnits: 100
description: >-
Theme name. It cannot be empty or contain only spaces or other whitespace. The length
limit is 100 UTF-16 code units; most letters count as one, while characters such as
emoji can count as two. Leading and trailing spaces are kept.
example: QA API theme
json:
description: >-
Complete email design settings, using the structure shown below. Supply either the
object itself or a JSON string containing the same object. Include all required
fields; a partial set of settings is not accepted. This field does not accept email
content, HTML, CSS or other brand information.
oneOf:
- $ref: "#/components/schemas/CanonicalSettings"
- type: string
description: A JSON string containing the complete email design settings shown in the object option.
CanonicalSettings:
title: Email design settings
type: object
description: >-
Complete design settings for the email as a whole, its sections, headings and buttons.
The `lightTheme` and `darkTheme` sections contain settings for light and dark display modes.
Include all required fields in both. If a required field allows `null` and you do not set
a value, include that field with `null`. Missing required values are not filled in
automatically. The create-theme example provides a complete object.
Use fixed CSS color values, such as `#ffffff` or `rgb(255, 255, 255)`, rather than CSS variables.
Background fields also accept a gradient followed by a fallback color for email clients
that cannot display the gradient. Image paths and background image sizes must be nonempty
strings without leading or trailing whitespace. Font names must not be blank.
properties:
general:
type: object
description: Settings for the whole email, including its width, alignment, spacing and background.
properties:
defaultStyles:
type: boolean
hideImageDownloadIcons:
type: boolean
underlineLinks:
type: boolean
responsiveDesign:
type: boolean
messageAlignment:
type: string
enum:
- left
- center
- right
messageContentWidth:
type: integer
minimum: 320
maximum: 900
backgroundImage:
type: object
properties:
path:
type: string
x-stripo-semantic: normalized-nonempty-string
repeat:
type: boolean
x:
type: string
y:
type: string
sizeX:
type: string
x-stripo-semantic: normalized-nonempty-string
sizeY:
type: string
x-stripo-semantic: normalized-nonempty-string
required:
- path
- repeat
- x
- y
- sizeX
- sizeY
additionalProperties: false
nullable: true
rightToLeftTextDirection:
type: boolean
marginsAroundMessage:
type: object
properties:
desktop:
type: object
properties:
top:
type: number
right:
type: number
bottom:
type: number
left:
type: number
required:
- top
- right
- bottom
- left
additionalProperties: false
mobile:
type: object
properties:
top:
type: number
right:
type: number
bottom:
type: number
left:
type: number
required:
- top
- right
- bottom
- left
additionalProperties: false
required:
- desktop
- mobile
additionalProperties: false
defaultStructurePadding:
type: object
properties:
desktop:
type: object
properties:
top:
type: number
right:
type: number
bottom:
type: number
left:
type: number
required:
- top
- right
- bottom
- left
additionalProperties: false
mobile:
type: object
properties:
top:
type: number
right:
type: number
bottom:
type: number
left:
type: number
required:
- top
- right
- bottom
- left
additionalProperties: false
required:
- desktop
- mobile
additionalProperties: false
customListStyles:
type: object
properties:
leftIndent:
type: number
minimum: 0
maximum: 300
listItemsBottomSpace:
type: number
minimum: 0
maximum: 100
listTopBottomMargin:
type: number
minimum: 0
maximum: 100
required:
- leftIndent
- listItemsBottomSpace
- listTopBottomMargin
additionalProperties: false
nullable: true
lightTheme:
type: object
properties:
backgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
customListStyles:
type: object
properties:
listMarkerColor:
type: string
x-stripo-semantic: static-color-transparent
listNumberMarkerColor:
type: string
x-stripo-semantic: static-color-transparent
required:
- listMarkerColor
- listNumberMarkerColor
additionalProperties: false
required:
- backgroundColor
- customListStyles
additionalProperties: false
darkTheme:
type: object
properties:
backgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
nullable: true
customListStyles:
type: object
properties:
listMarkerColor:
type: string
x-stripo-semantic: static-color-transparent
nullable: true
listNumberMarkerColor:
type: string
x-stripo-semantic: static-color-transparent
nullable: true
required:
- listMarkerColor
- listNumberMarkerColor
additionalProperties: false
backgroundImage:
type: string
nullable: true
x-stripo-semantic: normalized-nonempty-string
required:
- backgroundColor
- customListStyles
additionalProperties: false
required:
- defaultStyles
- hideImageDownloadIcons
- underlineLinks
- responsiveDesign
- messageAlignment
- messageContentWidth
- backgroundImage
- rightToLeftTextDirection
- marginsAroundMessage
- defaultStructurePadding
- customListStyles
- lightTheme
- darkTheme
additionalProperties: false
stripes:
type: object
description: Text and background styles for email sections, such as the header, main content and footer.
properties:
letterSpacing:
type: object
properties:
value:
type: number
unit:
type: string
enum:
- px
- em
required:
- value
- unit
additionalProperties: false
lineHeight:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 5
mobile:
type: number
minimum: 0
maximum: 5
required:
- desktop
- mobile
additionalProperties: false
fontFamily:
type: string
minLength: 1
x-stripo-semantic: nonblank-string
fontWeight:
type: integer
minimum: 100
maximum: 900
multipleOf: 100
header:
type: object
properties:
fontSize:
type: object
properties:
desktop:
type: number
minimum: 8
maximum: 72
mobile:
type: number
minimum: 8
maximum: 72
required:
- desktop
- mobile
additionalProperties: false
paragraphBottomSpace:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 100
mobile:
type: number
minimum: 0
maximum: 100
required:
- desktop
- mobile
additionalProperties: false
nullable: true
backgroundImage:
type: object
properties:
path:
type: string
x-stripo-semantic: normalized-nonempty-string
repeat:
type: boolean
x:
type: string
y:
type: string
sizeX:
type: string
x-stripo-semantic: normalized-nonempty-string
sizeY:
type: string
x-stripo-semantic: normalized-nonempty-string
required:
- path
- repeat
- x
- y
- sizeX
- sizeY
additionalProperties: false
nullable: true
required:
- fontSize
- paragraphBottomSpace
- backgroundImage
additionalProperties: false
content:
type: object
properties:
fontSize:
type: object
properties:
desktop:
type: number
minimum: 8
maximum: 72
mobile:
type: number
minimum: 8
maximum: 72
required:
- desktop
- mobile
additionalProperties: false
paragraphBottomSpace:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 100
mobile:
type: number
minimum: 0
maximum: 100
required:
- desktop
- mobile
additionalProperties: false
nullable: true
required:
- fontSize
- paragraphBottomSpace
additionalProperties: false
footer:
type: object
properties:
fontSize:
type: object
properties:
desktop:
type: number
minimum: 8
maximum: 72
mobile:
type: number
minimum: 8
maximum: 72
required:
- desktop
- mobile
additionalProperties: false
paragraphBottomSpace:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 100
mobile:
type: number
minimum: 0
maximum: 100
required:
- desktop
- mobile
additionalProperties: false
nullable: true
backgroundImage:
type: object
properties:
path:
type: string
x-stripo-semantic: normalized-nonempty-string
repeat:
type: boolean
x:
type: string
y:
type: string
sizeX:
type: string
x-stripo-semantic: normalized-nonempty-string
sizeY:
type: string
x-stripo-semantic: normalized-nonempty-string
required:
- path
- repeat
- x
- y
- sizeX
- sizeY
additionalProperties: false
nullable: true
required:
- fontSize
- paragraphBottomSpace
- backgroundImage
additionalProperties: false
infoArea:
type: object
properties:
fontSize:
type: object
properties:
desktop:
type: number
minimum: 8
maximum: 72
mobile:
type: number
minimum: 8
maximum: 72
required:
- desktop
- mobile
additionalProperties: false
paragraphBottomSpace:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 100
mobile:
type: number
minimum: 0
maximum: 100
required:
- desktop
- mobile
additionalProperties: false
nullable: true
required:
- fontSize
- paragraphBottomSpace
additionalProperties: false
lightTheme:
type: object
properties:
header:
type: object
properties:
stripeBackgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
contentBackgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
fontColor:
type: string
x-stripo-semantic: static-color-opaque
linkColor:
type: string
x-stripo-semantic: static-color-opaque
linkColorHover:
type: string
x-stripo-semantic: static-color-opaque
required:
- stripeBackgroundColor
- contentBackgroundColor
- fontColor
- linkColor
- linkColorHover
additionalProperties: false
content:
type: object
properties:
contentBackgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
fontColor:
type: string
x-stripo-semantic: static-color-opaque
linkColor:
type: string
x-stripo-semantic: static-color-opaque
linkColorHover:
type: string
x-stripo-semantic: static-color-opaque
required:
- contentBackgroundColor
- fontColor
- linkColor
- linkColorHover
additionalProperties: false
footer:
type: object
properties:
stripeBackgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
contentBackgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
fontColor:
type: string
x-stripo-semantic: static-color-opaque
linkColor:
type: string
x-stripo-semantic: static-color-opaque
linkColorHover:
type: string
x-stripo-semantic: static-color-opaque
required:
- stripeBackgroundColor
- contentBackgroundColor
- fontColor
- linkColor
- linkColorHover
additionalProperties: false
infoArea:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
linkColor:
type: string
x-stripo-semantic: static-color-opaque
linkColorHover:
type: string
x-stripo-semantic: static-color-opaque
required:
- fontColor
- linkColor
- linkColorHover
additionalProperties: false
required:
- header
- content
- footer
- infoArea
additionalProperties: false
darkTheme:
type: object
properties:
header:
type: object
properties:
stripeBackgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
nullable: true
contentBackgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
nullable: true
fontColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
linkColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
linkColorHover:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
required:
- stripeBackgroundColor
- contentBackgroundColor
- fontColor
- linkColor
- linkColorHover
additionalProperties: false
content:
type: object
properties:
contentBackgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
nullable: true
fontColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
linkColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
linkColorHover:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
required:
- contentBackgroundColor
- fontColor
- linkColor
- linkColorHover
additionalProperties: false
footer:
type: object
properties:
stripeBackgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
nullable: true
contentBackgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
nullable: true
fontColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
linkColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
linkColorHover:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
required:
- stripeBackgroundColor
- contentBackgroundColor
- fontColor
- linkColor
- linkColorHover
additionalProperties: false
infoArea:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
linkColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
linkColorHover:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
required:
- fontColor
- linkColor
- linkColorHover
additionalProperties: false
required:
- header
- content
- footer
- infoArea
additionalProperties: false
required:
- letterSpacing
- lineHeight
- fontFamily
- fontWeight
- header
- content
- footer
- infoArea
- lightTheme
- darkTheme
additionalProperties: false
headings:
type: object
description: Font, size, spacing and color settings for heading levels h1 through h6.
properties:
letterSpacing:
type: object
properties:
value:
type: number
unit:
type: string
enum:
- px
- em
required:
- value
- unit
additionalProperties: false
fontFamily:
type: string
minLength: 1
x-stripo-semantic: nonblank-string
h1:
type: object
properties:
textAlign:
type: object
properties:
mobile:
type: string
enum:
- left
- center
- right
nullable: true
required:
- mobile
additionalProperties: false
textStyle:
type: object
properties:
italic:
type: boolean
required:
- italic
additionalProperties: false
fontWeight:
type: integer
minimum: 100
maximum: 900
multipleOf: 100
nullable: true
fontSize:
type: object
properties:
desktop:
type: number
minimum: 8
maximum: 72
nullable: true
mobile:
type: number
minimum: 8
maximum: 72
nullable: true
required:
- desktop
- mobile
additionalProperties: false
lineHeight:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 5
nullable: true
mobile:
type: number
minimum: 0
maximum: 5
nullable: true
required:
- desktop
- mobile
additionalProperties: false
paragraphBottomSpace:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 100
mobile:
type: number
minimum: 0
maximum: 100
required:
- desktop
- mobile
additionalProperties: false
nullable: true
required:
- textAlign
- textStyle
- fontWeight
- fontSize
- lineHeight
- paragraphBottomSpace
additionalProperties: false
h2:
type: object
properties:
textAlign:
type: object
properties:
mobile:
type: string
enum:
- left
- center
- right
nullable: true
required:
- mobile
additionalProperties: false
textStyle:
type: object
properties:
italic:
type: boolean
required:
- italic
additionalProperties: false
fontWeight:
type: integer
minimum: 100
maximum: 900
multipleOf: 100
nullable: true
fontSize:
type: object
properties:
desktop:
type: number
minimum: 8
maximum: 72
nullable: true
mobile:
type: number
minimum: 8
maximum: 72
nullable: true
required:
- desktop
- mobile
additionalProperties: false
lineHeight:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 5
nullable: true
mobile:
type: number
minimum: 0
maximum: 5
nullable: true
required:
- desktop
- mobile
additionalProperties: false
paragraphBottomSpace:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 100
mobile:
type: number
minimum: 0
maximum: 100
required:
- desktop
- mobile
additionalProperties: false
nullable: true
required:
- textAlign
- textStyle
- fontWeight
- fontSize
- lineHeight
- paragraphBottomSpace
additionalProperties: false
h3:
type: object
properties:
textAlign:
type: object
properties:
mobile:
type: string
enum:
- left
- center
- right
nullable: true
required:
- mobile
additionalProperties: false
textStyle:
type: object
properties:
italic:
type: boolean
required:
- italic
additionalProperties: false
fontWeight:
type: integer
minimum: 100
maximum: 900
multipleOf: 100
nullable: true
fontSize:
type: object
properties:
desktop:
type: number
minimum: 8
maximum: 72
nullable: true
mobile:
type: number
minimum: 8
maximum: 72
nullable: true
required:
- desktop
- mobile
additionalProperties: false
lineHeight:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 5
nullable: true
mobile:
type: number
minimum: 0
maximum: 5
nullable: true
required:
- desktop
- mobile
additionalProperties: false
paragraphBottomSpace:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 100
mobile:
type: number
minimum: 0
maximum: 100
required:
- desktop
- mobile
additionalProperties: false
nullable: true
required:
- textAlign
- textStyle
- fontWeight
- fontSize
- lineHeight
- paragraphBottomSpace
additionalProperties: false
h4:
type: object
properties:
textAlign:
type: object
properties:
mobile:
type: string
enum:
- left
- center
- right
nullable: true
required:
- mobile
additionalProperties: false
textStyle:
type: object
properties:
italic:
type: boolean
required:
- italic
additionalProperties: false
fontWeight:
type: integer
minimum: 100
maximum: 900
multipleOf: 100
nullable: true
fontSize:
type: object
properties:
desktop:
type: number
minimum: 8
maximum: 72
nullable: true
mobile:
type: number
minimum: 8
maximum: 72
nullable: true
required:
- desktop
- mobile
additionalProperties: false
lineHeight:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 5
nullable: true
mobile:
type: number
minimum: 0
maximum: 5
nullable: true
required:
- desktop
- mobile
additionalProperties: false
paragraphBottomSpace:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 100
mobile:
type: number
minimum: 0
maximum: 100
required:
- desktop
- mobile
additionalProperties: false
nullable: true
required:
- textAlign
- textStyle
- fontWeight
- fontSize
- lineHeight
- paragraphBottomSpace
additionalProperties: false
h5:
type: object
properties:
textAlign:
type: object
properties:
mobile:
type: string
enum:
- left
- center
- right
nullable: true
required:
- mobile
additionalProperties: false
textStyle:
type: object
properties:
italic:
type: boolean
required:
- italic
additionalProperties: false
fontWeight:
type: integer
minimum: 100
maximum: 900
multipleOf: 100
nullable: true
fontSize:
type: object
properties:
desktop:
type: number
minimum: 8
maximum: 72
nullable: true
mobile:
type: number
minimum: 8
maximum: 72
nullable: true
required:
- desktop
- mobile
additionalProperties: false
lineHeight:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 5
nullable: true
mobile:
type: number
minimum: 0
maximum: 5
nullable: true
required:
- desktop
- mobile
additionalProperties: false
paragraphBottomSpace:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 100
mobile:
type: number
minimum: 0
maximum: 100
required:
- desktop
- mobile
additionalProperties: false
nullable: true
required:
- textAlign
- textStyle
- fontWeight
- fontSize
- lineHeight
- paragraphBottomSpace
additionalProperties: false
h6:
type: object
properties:
textAlign:
type: object
properties:
mobile:
type: string
enum:
- left
- center
- right
nullable: true
required:
- mobile
additionalProperties: false
textStyle:
type: object
properties:
italic:
type: boolean
required:
- italic
additionalProperties: false
fontWeight:
type: integer
minimum: 100
maximum: 900
multipleOf: 100
nullable: true
fontSize:
type: object
properties:
desktop:
type: number
minimum: 8
maximum: 72
nullable: true
mobile:
type: number
minimum: 8
maximum: 72
nullable: true
required:
- desktop
- mobile
additionalProperties: false
lineHeight:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 5
nullable: true
mobile:
type: number
minimum: 0
maximum: 5
nullable: true
required:
- desktop
- mobile
additionalProperties: false
paragraphBottomSpace:
type: object
properties:
desktop:
type: number
minimum: 0
maximum: 100
mobile:
type: number
minimum: 0
maximum: 100
required:
- desktop
- mobile
additionalProperties: false
nullable: true
required:
- textAlign
- textStyle
- fontWeight
- fontSize
- lineHeight
- paragraphBottomSpace
additionalProperties: false
lightTheme:
type: object
properties:
h1:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
required:
- fontColor
additionalProperties: false
h2:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
required:
- fontColor
additionalProperties: false
h3:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
required:
- fontColor
additionalProperties: false
h4:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
required:
- fontColor
additionalProperties: false
h5:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
required:
- fontColor
additionalProperties: false
h6:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
required:
- fontColor
additionalProperties: false
required:
- h1
- h2
- h3
- h4
- h5
- h6
additionalProperties: false
darkTheme:
type: object
properties:
h1:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
required:
- fontColor
additionalProperties: false
h2:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
required:
- fontColor
additionalProperties: false
h3:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
required:
- fontColor
additionalProperties: false
h4:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
required:
- fontColor
additionalProperties: false
h5:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
required:
- fontColor
additionalProperties: false
h6:
type: object
properties:
fontColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
required:
- fontColor
additionalProperties: false
required:
- h1
- h2
- h3
- h4
- h5
- h6
additionalProperties: false
required:
- letterSpacing
- fontFamily
- h1
- h2
- h3
- h4
- h5
- h6
- lightTheme
- darkTheme
additionalProperties: false
buttons:
type: object
description: Button appearance, including text, background, borders, spacing and hover styles.
properties:
outlookSupport:
type: boolean
textStyle:
type: object
properties:
bold:
type: boolean
italic:
type: boolean
required:
- bold
- italic
additionalProperties: false
textTransform:
type: string
enum:
- none
- uppercase
- capitalize
- lowercase
fontFamily:
type: string
minLength: 1
x-stripo-semantic: nonblank-string
letterSpacing:
type: object
properties:
value:
type: number
unit:
type: string
enum:
- px
- em
required:
- value
- unit
additionalProperties: false
fontSize:
type: object
properties:
desktop:
type: number
minimum: 8
maximum: 72
mobile:
type: number
minimum: 8
maximum: 72
required:
- desktop
- mobile
additionalProperties: false
borderRadius:
type: object
properties:
topLeft:
type: number
minimum: 0
maximum: 1000
topRight:
type: number
minimum: 0
maximum: 1000
bottomRight:
type: number
minimum: 0
maximum: 1000
bottomLeft:
type: number
minimum: 0
maximum: 1000
required:
- topLeft
- topRight
- bottomRight
- bottomLeft
additionalProperties: false
fitContainer:
type: object
properties:
desktop:
type: boolean
mobile:
type: boolean
required:
- desktop
- mobile
additionalProperties: false
border:
type: object
properties:
top:
type: object
properties:
width:
type: number
minimum: 0
maximum: 100
required:
- width
additionalProperties: false
right:
type: object
properties:
width:
type: number
minimum: 0
maximum: 100
required:
- width
additionalProperties: false
bottom:
type: object
properties:
width:
type: number
minimum: 0
maximum: 100
required:
- width
additionalProperties: false
left:
type: object
properties:
width:
type: number
minimum: 0
maximum: 100
required:
- width
additionalProperties: false
style:
type: string
enum:
- solid
- dashed
- dotted
required:
- top
- right
- bottom
- left
- style
additionalProperties: false
hoverButtonStyles:
type: boolean
padding:
type: object
properties:
desktop:
type: object
properties:
top:
type: number
right:
type: number
bottom:
type: number
left:
type: number
required:
- top
- right
- bottom
- left
additionalProperties: false
mobile:
type: object
properties:
top:
type: number
right:
type: number
bottom:
type: number
left:
type: number
required:
- top
- right
- bottom
- left
additionalProperties: false
required:
- desktop
- mobile
additionalProperties: false
lightTheme:
type: object
properties:
buttonColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
fontColor:
type: string
x-stripo-semantic: static-color-opaque
hoverButtonStyles:
type: object
properties:
backgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
fontColor:
type: string
x-stripo-semantic: static-color-opaque
borderColor:
type: object
properties:
top:
type: string
x-stripo-semantic: static-color-transparent
right:
type: string
x-stripo-semantic: static-color-transparent
bottom:
type: string
x-stripo-semantic: static-color-transparent
left:
type: string
x-stripo-semantic: static-color-transparent
required:
- top
- right
- bottom
- left
additionalProperties: false
required:
- backgroundColor
- fontColor
- borderColor
additionalProperties: false
borderColor:
type: object
properties:
top:
type: string
x-stripo-semantic: static-color-transparent
right:
type: string
x-stripo-semantic: static-color-transparent
bottom:
type: string
x-stripo-semantic: static-color-transparent
left:
type: string
x-stripo-semantic: static-color-transparent
required:
- top
- right
- bottom
- left
additionalProperties: false
required:
- buttonColor
- fontColor
- hoverButtonStyles
- borderColor
additionalProperties: false
darkTheme:
type: object
properties:
buttonColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
nullable: true
fontColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
hoverButtonStyles:
type: object
properties:
backgroundColor:
type: string
description: >-
Background color, or a gradient followed by a fallback color. For example,
`#ffffff` or `linear-gradient(90deg, #ffffff, #000000), #ffffff`. The fallback
color is used by email clients that cannot display the gradient.
x-stripo-semantic: canonical-theme-background
nullable: true
fontColor:
type: string
x-stripo-semantic: static-color-opaque
nullable: true
borderColor:
type: object
properties:
top:
type: string
x-stripo-semantic: static-color-transparent
nullable: true
right:
type: string
x-stripo-semantic: static-color-transparent
nullable: true
bottom:
type: string
x-stripo-semantic: static-color-transparent
nullable: true
left:
type: string
x-stripo-semantic: static-color-transparent
nullable: true
required:
- top
- right
- bottom
- left
additionalProperties: false
required:
- backgroundColor
- fontColor
- borderColor
additionalProperties: false
borderColor:
type: object
properties:
top:
type: string
x-stripo-semantic: static-color-transparent
nullable: true
right:
type: string
x-stripo-semantic: static-color-transparent
nullable: true
bottom:
type: string
x-stripo-semantic: static-color-transparent
nullable: true
left:
type: string
x-stripo-semantic: static-color-transparent
nullable: true
required:
- top
- right
- bottom
- left
additionalProperties: false
required:
- buttonColor
- fontColor
- hoverButtonStyles
- borderColor
additionalProperties: false
required:
- outlookSupport
- textStyle
- textTransform
- fontFamily
- letterSpacing
- fontSize
- borderRadius
- fitContainer
- border
- hoverButtonStyles
- padding
- lightTheme
- darkTheme
additionalProperties: false
required:
- general
- stripes
- headings
- buttons
additionalProperties: false
UpdateTemplateThemeRequest:
type: object
description: Provide the current theme version and a new name, complete design settings or both.
required:
- expectedVersion
anyOf:
- required:
- name
- required:
- json
properties:
expectedVersion:
type: integer
format: int64
minimum: 1
description: >-
The version from the latest theme you retrieved. If the theme's settings have changed
since then, the request returns HTTP 409 so you can review the changes before retrying.
name:
type: string
minLength: 1
pattern: \S
description: New theme name. It must not be empty or contain only whitespace. Leading and trailing spaces are kept.
json:
type: string
description: >-
Complete email design settings encoded as a JSON string. Use the same settings
structure as when creating a theme, including all required fields. For updates,
this field accepts a string only, not a JSON object.
ThemeEmailIds:
type: array
items:
type: string
description: >-
IDs of emails currently using the theme, as used in your application. Returns an empty
array if no emails use the theme.
ApplyTemplateThemeRequest:
type: object
required:
- emailId
- themeId
properties:
emailId:
$ref: "#/components/schemas/EmailId"
themeId:
type: string
minLength: 1
description: ID of a theme available for the values supplied in Es-Plugin-Ui-Data.
EmailId:
type: string
minLength: 1
description: >-
Email ID used by your application for this plugin. Its length must be 1–100 bytes when
encoded as UTF-8. Double quotes, backslashes, line breaks and tabs are not allowed. The
combined length of your plugin ID and email ID must not exceed 253 bytes. Letter case
and leading zeroes are kept.
pattern: ^[^"\\\n\r\t]+$
x-stripo-maxUtf8Bytes: 100
example: qa-theme-1
UnlinkTemplateThemeRequest:
type: object
required:
- emailId
properties:
emailId:
$ref: "#/components/schemas/EmailId"
BulkApplyThemeResult:
type: object
required:
- successfulEmailIds
- failedEmails
properties:
successfulEmailIds:
type: array
items:
$ref: "#/components/schemas/EmailId"
description: >-
IDs of emails for which the theme was selected successfully. Each ID appears once,
in the order of its first appearance in the request. Empty if none succeeded.
failedEmails:
type: array
items:
$ref: "#/components/schemas/BulkApplyThemeFailure"
description: >-
Emails for which the theme could not be selected, with an error code explaining each
failure. Each email ID appears once. Always included; empty if no emails failed.
BulkApplyThemeFailure:
type: object
required:
- emailId
- code
properties:
emailId:
$ref: "#/components/schemas/EmailId"
code:
type: string
enum:
- MODEL_NOT_FOUND
- THEME_NOT_FOUND
- APPLY_FAILED
- CANCELED
- TIMEOUT
description: >-
Reason the theme could not be applied to this email.
- MODEL_NOT_FOUND: the email does not exist.
- THEME_NOT_FOUND: the theme became unavailable while the request was being handled.
- APPLY_FAILED: the theme could not be applied for another reason.
- CANCELED: the request was canceled before this email could be completed.
- TIMEOUT: the request exceeded its time limit before this email could be completed.
BulkApplyThemeRequest:
type: object
required:
- themeId
- emailIds
description: Provide one theme ID and a list of email IDs in a single JSON object.
properties:
themeId:
type: string
minLength: 1
description: ID of a theme available for the values supplied in Es-Plugin-Ui-Data.
example: a37dc20f-f2ce-4c4f-938a-57fc3e27e0be
emailIds:
type: array
minItems: 1
items:
$ref: "#/components/schemas/EmailId"
description: >-
IDs of existing emails in your application. Include at least one ID. The default
limit is 25 entries per request and may be configured differently. Repeated IDs count
toward that limit, but each email is updated only once, in the order it first appears.
x-stripo-defaultMaxItems: 25
ResourcePermissionsRequest:
type: object
properties:
pluginId:
type: string
description: ID of the plugin requesting access.
example: YOUR_PLUGIN_ID
uiData:
type: object
description: >-
Values supplied in uiData when opening the editor or in the Es-Plugin-Ui-Data header
of an API request. All values are strings. Empty object if no values were supplied.
additionalProperties:
type: string
requestPermissions:
type: array
description: Permissions Stripo asks your application to approve for this request.
items:
$ref: "#/components/schemas/ResourcePermission"
required:
- pluginId
- uiData
- requestPermissions
ResourcePermission:
type: object
properties:
type:
type: string
description: Resource to which the permission applies. Use TEMPLATE_THEMES for email themes.
enum:
- BLOCKS
- DOCS
- TEMPLATE_THEMES
action:
type: string
description: >-
Requested access. For themes, READ allows viewing and applying; MODIFY allows
creating, updating and deleting. Each permission must be granted separately.
enum:
- READ
- MODIFY
key:
type: string
description: Identifies the resources this permission applies to. Copy the requested value exactly when granting access.
example: pluginId_YOUR_PLUGIN_ID_emailId_123_id_456
keyTemplate:
type: string
description: >-
Your plugin's setting for grouping themes. For example, `brand_${brandId}` creates
separate groups for different `brandId` values supplied in `uiData`. An empty string
means themes are shared across the plugin. This field is always included in requests
for TEMPLATE_THEMES and is optional in grantPermissions.
Maximum length is 200 characters. Use ASCII letters, digits, underscores, hyphens
and placeholders such as `${brandId}`. Placeholder names must be nonempty and use the
same letters, digits, underscores or hyphens. Supply a value for every placeholder;
after substitution, only those characters are allowed. The full key sent in permission
requests, including the plugin identifier, must not exceed 255 bytes.
example: emailId_${emailId}_id_${someAnotherIdentifier}
required:
- type
- action
- key
ResourcePermissionsResponse:
type: object
properties:
grantPermissions:
type: array
description: >-
Permissions your application allows. Include a matching type, action and key for each
permission you grant. An empty array grants no access.
items:
$ref: "#/components/schemas/ResourcePermission"
required:
- grantPermissions
responses:
BadRequest:
description: >-
The request data or Es-Plugin-Ui-Data values are invalid, or Template Themes is disabled
for your plugin. Unlinking is allowed even when Template Themes is disabled.
headers:
X-Trace-Id:
$ref: "#/components/headers/TraceId"
content:
text/plain:
schema:
type: string
example: '{"Message":"template themes are disabled"}'
Unauthorized:
description: The plugin token is missing or invalid. Check the ES-PLUGIN-AUTH header.
headers:
X-Trace-Id:
$ref: "#/components/headers/TraceId"
content:
text/plain:
schema:
type: string
example: '{"Message":"Unauthorized"}'
Forbidden:
description: Your token does not have the API role, or you do not have permission for this operation.
headers:
X-Trace-Id:
$ref: "#/components/headers/TraceId"
content:
text/plain:
schema:
type: string
example: '{"Message":"Forbidden"}'
NotFound:
description: >-
The requested theme or plugin settings could not be found. Check the theme ID and the
values supplied in Es-Plugin-Ui-Data.
headers:
X-Trace-Id:
$ref: "#/components/headers/TraceId"
content:
text/plain:
schema:
type: string
example: '{"Message":"Not Found"}'
MethodNotAllowed:
description: This endpoint does not support the HTTP method used in the request.
headers:
X-Trace-Id:
$ref: "#/components/headers/TraceId"
content:
text/plain:
schema:
type: string
example: '{"Message":"Method Not Allowed"}'
TooManyRequests:
description: Too many requests were sent to this endpoint. Wait for the time specified in Retry-After before trying again.
headers:
X-Trace-Id:
$ref: "#/components/headers/TraceId"
Retry-After:
description: Number of seconds to wait before sending another request.
schema:
type: integer
minimum: 0
content:
text/plain:
schema:
type: string
example: Too Many Requests
InternalServerError:
description: >-
A server error prevented the request from completing. If you contact Stripo Support,
include the X-Trace-Id value from the response headers.
headers:
X-Trace-Id:
$ref: "#/components/headers/TraceId"
content:
text/plain:
schema:
type: string
example: '{"Message":"Internal server error, lookup traceId in headers for more information"}'
headers:
TraceId:
description: ID of this request. Include it when contacting Stripo Support about an error.
schema:
type: string
examples:
CreateTheme:
summary: A theme with complete email design settings
value:
name: QA API theme
json:
general:
defaultStyles: true
hideImageDownloadIcons: true
underlineLinks: true
responsiveDesign: true
messageAlignment: center
messageContentWidth: 600
backgroundImage: null
rightToLeftTextDirection: false
marginsAroundMessage:
desktop:
top: 0
right: 0
bottom: 0
left: 0
mobile:
top: 0
right: 0
bottom: 0
left: 0
defaultStructurePadding:
desktop:
top: 10
right: 10
bottom: 10
left: 10
mobile:
top: 5
right: 5
bottom: 5
left: 5
customListStyles:
leftIndent: 40
listItemsBottomSpace: 15
listTopBottomMargin: 15
lightTheme:
backgroundColor: "#f6f6f6"
customListStyles:
listMarkerColor: "#112233"
listNumberMarkerColor: transparent
darkTheme:
backgroundColor: null
customListStyles:
listMarkerColor: null
listNumberMarkerColor: null
stripes:
letterSpacing:
value: 0
unit: px
lineHeight:
desktop: 1.5
mobile: 1.5
fontFamily: Arial, sans-serif
fontWeight: 400
header:
fontSize:
desktop: 16
mobile: 16
paragraphBottomSpace: null
backgroundImage:
path: https://example.com/header.png
repeat: false
x: center
y: top
sizeX: auto
sizeY: auto
content:
fontSize:
desktop: 14
mobile: 14
paragraphBottomSpace: null
footer:
fontSize:
desktop: 14
mobile: 14
paragraphBottomSpace: null
backgroundImage: null
infoArea:
fontSize:
desktop: 12
mobile: 12
paragraphBottomSpace: null
lightTheme:
header:
stripeBackgroundColor: transparent
contentBackgroundColor: "#ffffff"
fontColor: "#101010"
linkColor: "#202020"
linkColorHover: "#303030"
content:
contentBackgroundColor: "#ffffff"
fontColor: "#404040"
linkColor: "#505050"
linkColorHover: "#606060"
footer:
stripeBackgroundColor: transparent
contentBackgroundColor: "#ffffff"
fontColor: "#707070"
linkColor: "#808080"
linkColorHover: "#909090"
infoArea:
fontColor: "#a0a0a0"
linkColor: "#b0b0b0"
linkColorHover: "#c0c0c0"
darkTheme:
header:
stripeBackgroundColor: null
contentBackgroundColor: null
fontColor: null
linkColor: null
linkColorHover: null
content:
contentBackgroundColor: null
fontColor: null
linkColor: null
linkColorHover: null
footer:
stripeBackgroundColor: null
contentBackgroundColor: null
fontColor: null
linkColor: null
linkColorHover: null
infoArea:
fontColor: null
linkColor: null
linkColorHover: null
headings:
letterSpacing:
value: 0
unit: px
fontFamily: Arial, sans-serif
h1:
textAlign:
mobile: left
textStyle:
italic: false
fontWeight: null
fontSize:
desktop: 40
mobile: 40
lineHeight:
desktop: 1.2
mobile: 1.2
paragraphBottomSpace: null
h2:
textAlign:
mobile: left
textStyle:
italic: false
fontWeight: null
fontSize:
desktop: 32
mobile: 32
lineHeight:
desktop: 1.2
mobile: 1.2
paragraphBottomSpace: null
h3:
textAlign:
mobile: left
textStyle:
italic: false
fontWeight: null
fontSize:
desktop: 28
mobile: 28
lineHeight:
desktop: 1.2
mobile: 1.2
paragraphBottomSpace: null
h4:
textAlign:
mobile: left
textStyle:
italic: false
fontWeight: null
fontSize:
desktop: 24
mobile: 24
lineHeight:
desktop: 1.2
mobile: 1.2
paragraphBottomSpace: null
h5:
textAlign:
mobile: left
textStyle:
italic: false
fontWeight: null
fontSize:
desktop: 20
mobile: 20
lineHeight:
desktop: 1.2
mobile: 1.2
paragraphBottomSpace: null
h6:
textAlign:
mobile: left
textStyle:
italic: false
fontWeight: null
fontSize:
desktop: 16
mobile: 16
lineHeight:
desktop: 1.2
mobile: 1.2
paragraphBottomSpace: null
lightTheme:
h1:
fontColor: "#111111"
h2:
fontColor: "#222222"
h3:
fontColor: "#333333"
h4:
fontColor: "#444444"
h5:
fontColor: "#555555"
h6:
fontColor: "#666666"
darkTheme:
h1:
fontColor: null
h2:
fontColor: null
h3:
fontColor: null
h4:
fontColor: null
h5:
fontColor: null
h6:
fontColor: null
buttons:
outlookSupport: false
textStyle:
bold: false
italic: false
textTransform: none
fontFamily: arial,'helvetica neue',helvetica,sans-serif
letterSpacing:
value: 0
unit: px
fontSize:
desktop: 14
mobile: 14
borderRadius:
topLeft: 15
topRight: 15
bottomRight: 15
bottomLeft: 15
fitContainer:
desktop: false
mobile: false
border:
top:
width: 1
right:
width: 2
bottom:
width: 3
left:
width: 4
style: solid
hoverButtonStyles: true
padding:
desktop:
top: 10
right: 20
bottom: 10
left: 20
mobile:
top: 10
right: 20
bottom: 10
left: 20
lightTheme:
buttonColor: "#31cb4b"
fontColor: "#ffffff"
hoverButtonStyles:
backgroundColor: "#2cb543"
fontColor: "#eeeeee"
borderColor:
top: "#555555"
right: "#666666"
bottom: "#777777"
left: "#888888"
borderColor:
top: "#111111"
right: "#222222"
bottom: "#333333"
left: "#444444"
darkTheme:
buttonColor: null
fontColor: null
hoverButtonStyles:
backgroundColor: null
fontColor: null
borderColor:
top: null
right: null
bottom: null
left: null
borderColor:
top: null
right: null
bottom: null
left: nullUpdating Timer Block Links
This API call allows you to update timer links in the HTML code when copying an email template outside the Stripo editor. It ensures that the timers are correctly cloned and updated in the new template.
OpenAPI Specification
Reference
yaml
openapi: 3.0.1
info:
title: Timer Clone API
description: This API call allows you to update timer links in the HTML code when copying an email template outside the Stripo editor. It ensures that the timers are correctly cloned and updated in the new template.
version: 1.0.0
servers:
- url: https://plugins.stripo.email
paths:
/api/v1/timers/clone:
post:
tags:
- Methods
summary: Updating Timer Block Links
description: Clone timers and update timer links in HTML
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
html:
type: string
description: HTML code containing timer links
example: 'Timer link: ...'
required:
- html
parameters:
- in: header
name: ES-PLUGIN-AUTH
required: true
schema:
type: string
description: Authorization token
example: Bearer YOUR_AUTH_TOKEN
responses:
'200':
description: Successful response with updated HTML and timer mapping
content:
application/json:
schema:
type: object
properties:
html:
type: string
description: HTML code with updated timer links
example: 'Timer link: ...'
timersMap:
type: object
description: Mapping of old timer IDs to new timer IDs and URLs. Keys are old timer IDs, values are objects containing new timer information.
additionalProperties:
type: object
properties:
id:
type: integer
description: New timer ID in the cloned template
example: 152752
url:
type: string
format: uri
description: URL of the new timer image
example: 'https://cdt-timer-plugins.stripocdn.email/api/v1/images/s5exXSdnyicX1pCXcz83Faw-C7kFWaTlkeHuxpPS8rs'
required:
- id
- url
example:
'152702':
id: 152752
url: 'https://cdt-timer-plugins.stripocdn.email/api/v1/images/s5exXSdnyicX1pCXcz83Faw-C7kFWaTlkeHuxpPS8rs'
'152701':
id: 152751
url: 'https://cdt-timer-plugins.stripocdn.email/api/v1/images/VxPC8zhLbJuBOfRINW0LODFkYw7WWRpi5WgOOq4AGsI'Access to Stripo Templates
Stripo provides access to a variety of email templates that you can use based on your subscription plan. If you have registered your account and integrated your plugin application, you can access these templates.
Template Access Based on Plan:
- FREE Plan: Access to basic templates only.
- STARTUP Plan: Access to basic templates and those marked as FREE.
- BUSINESS and ENTERPRISE Plans: Access to basic, free, and PREMIUM templates.
How to Access Templates
After making the initial request to get an array of the available templates, you will need to make individual calls for each template to retrieve its HTML and CSS.
Step-by-Step Process
- Get List of Templates: Make a request to retrieve an array of available templates based on your plan.
Endpoint:GET /bapi/plugin-templates/v1/templates - Get HTML and CSS for Each Template: For each template in the array, make separate requests to retrieve its HTML and CSS.
Endpoint:GET /bapi/plugin-templates/v1/templates/{templateId}
OpenAPI Specification
Reference
yaml
openapi: 3.0.0
info:
title: Stripo Email Template API
description: |
Stripo provides access to a variety of email templates that you can use based on your subscription plan. If you have registered your account and integrated your plugin application, you can access these templates.
After making the initial request to get an array of the available templates, you will need to make individual calls for each template to retrieve its HTML and CSS.
version: 1.0.0
servers:
- url: https://my.stripo.email/bapi/plugin-templates
paths:
/v1/templates:
get:
tags:
- Methods
summary: Get Templates
description: Get templates matching the specified search criteria.
parameters:
- name: type
in: query
required: true
schema:
type: string
enum: [BASIC, FREE, PREMIUM]
description: Specifies the variety of templates to be returned.
- name: sort
in: query
schema:
type: string
enum: [NEW, ACTUAL]
default: ACTUAL
description: Defines how the templates are sorted in response.
- name: limit
in: query
schema:
type: integer
description: Regulates how many items should be returned per page (suggested limit of no more than 50).
- name: page
in: query
schema:
type: integer
description: Defines the number of the page.
- name: templateTypes
in: query
schema:
type: array
items:
type: integer
description: Filters templates that specifically pertain to relevant categories.
- name: templateSeasons
in: query
schema:
type: array
items:
type: integer
description: Restricts the selection of templates to those associated with seasonal events categories.
- name: templateFeatures
in: query
schema:
type: array
items:
type: integer
description: Ensures that only templates related to specific feature categories are retrieved.
- name: templateIndustries
in: query
schema:
type: array
items:
type: integer
description: Narrows down template selection to include only those featuring industry-specific categories.
responses:
'200':
description: A list of templates matching the search criteria.
content:
application/json:
schema:
type: object
properties:
total:
type: integer
data:
type: array
items:
type: object
properties:
templateId:
type: integer
name:
type: string
logo:
type: string
premium:
type: boolean
hasAmp:
type: boolean
updatedAt:
type: integer
createdTime:
type: integer
templateTypes:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
templateSeasons:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
templateFeatures:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
templateIndustries:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
security:
- ES-PLUGIN-AUTH: []
/v1/templates/{templateId}:
get:
tags:
- Methods
summary: Get Template Details
description: Get the metadata, HTML, and CSS code for a specific template by ID.
parameters:
- name: templateId
in: path
required: true
schema:
type: integer
responses:
'200':
description: Metadata, HTML, and CSS code for the specified template.
content:
application/json:
schema:
type: object
properties:
templateId:
type: integer
name:
type: string
logo:
type: string
premium:
type: boolean
hasAmp:
type: boolean
updatedAt:
type: integer
createdTime:
type: integer
templateTypes:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
templateSeasons:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
templateFeatures:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
templateIndustries:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
html:
type: string
css:
type: string
security:
- ES-PLUGIN-AUTH: []
/v1/templates/types:
get:
tags:
- Methods
summary: Get Template Types
description: Get available values for the templateTypes parameter.
responses:
'200':
description: Array of available values for the templateTypes parameter.
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
security:
- ES-PLUGIN-AUTH: []
/v1/templates/seasons:
get:
tags:
- Methods
summary: Get Template Seasons
description: Get available values for the templateSeasons parameter.
responses:
'200':
description: Array of available values for the templateSeasons parameter.
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
security:
- ES-PLUGIN-AUTH: []
/v1/templates/features:
get:
tags:
- Methods
summary: Get Template Features
description: Get available values for the templateFeatures parameter.
responses:
'200':
description: Array of available values for the templateFeatures parameter.
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
security:
- ES-PLUGIN-AUTH: []
/v1/templates/industries:
get:
tags:
- Methods
summary: Get Template Industries
description: Get available values for the templateIndustries parameter.
responses:
'200':
description: Array of available values for the templateIndustries parameter.
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
security:
- ES-PLUGIN-AUTH: []
components:
securitySchemes:
ES-PLUGIN-AUTH:
type: apiKey
in: header
name: ES-PLUGIN-AUTH
description: Bearer YOUR_AUTH_TOKENDetailed Explanation
Get Templates
/v1/templates?type=BASIC
Summary: Get templates matching the specified search criteria.
Parameters:
type(required, query): Specifies the variety of templates to be returned (BASIC,FREE,PREMIUM).sort(query): Defines how the templates are sorted in response (NEW,ACTUAL).limit(query): Regulates how many items should be returned per page (suggested limit of no more than 50).page(query): Defines the number of the page.templateTypes(query): Filters templates that specifically pertain to relevant categories.templateSeasons(query): Restricts the selection of templates to those associated with seasonal events categories.templateFeatures(query): Ensures that only templates related to specific feature categories are retrieved.templateIndustries(query): Narrows down template selection to include only those featuring industry-specific categories.
Get Template Details
/v1/templates/{templateId}
Summary: Get the metadata, HTML, and CSS code for a specific template by ID.
Parameters:
templateId(required, path): The ID of the template.
Get Template Types
/v1/templates/types
- Summary: Get available values for the
templateTypesparameter.
Get Template Seasons
/v1/templates/seasons
- Summary: Get available values for the
templateSeasonsparameter.
Get Template Features
/v1/templates/features
- Summary: Get available values for the
templateFeaturesparameter.
Get Template Industries
/v1/templates/industries
- Summary: Get available values for the
templateIndustriesparameter.