Retrieving Plugin Modules API

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.

Server

https://plugins.stripo.email

Plugin Backend Service

Client Libraries

Shell Curl

Methods

Plugin module management operations

Methods Operations

get/api/v1/customblocks/v4/modules/list

List plugin modules

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).

Query Parameters

key
Type: string

Filter by module key (folder name). Returns modules matching the specified key.
query
Type: string

Full-text search query for module name.
categories
Type: array of integerFormat: int64

Filter by one or more category IDs. Returns modules belonging to any of the specified categories.
tags
Type: array of string

Filter by one or more tag values. Returns modules that have any of the specified tags.
id
Type: integerFormat: int64

Filter by specific module ID. When provided, returns only the module with this exact ID (if it belongs to the authenticated plugin).
synchronizable
Type: boolean

Filter by synchronizable status. Set to true for synchronizable modules only, false for non-synchronizable modules only, or omit for all modules.
withContent
Type: boolean

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.
sortingColumn
Type: "id" or "name"enum

Column to sort results by. Options are id (module ID) or name (module name).
sortingAsc
Type: boolean

Sort direction. Set to true for ascending order, false for descending order.
offset
Type: integer
min:
0

Zero-based pagination offset. Specifies the starting position in the result set. Takes precedence over the page parameter when both are provided.
page
Type: integer
min:
1

One-based page number for pagination. Used only if offset is not provided. Calculated as: offset = (page - 1) * limit
limit
Type: integer
min:
1
max:
100

Maximum number of modules to return per page. Controls the page size for pagination.

Headers

ES-PLUGIN-AUTH
Type: string
required

Plugin authentication token with "API" role. Must be in Bearer token format.

Responses

200
Type:

Modules list retrieved successfully. Returns a paginated list of modules with metadata and optionally HTML/CSS content.

Response containing a paginated list of plugin modules with metadata
limit
Type: integer
min:
1

Maximum number of modules returned in this page. Corresponds to the limit parameter from the request.

modules
Type:

Array of module objects. Each module contains metadata and optionally HTML/CSS content (depending on the withContent parameter).

Properties: 16
offset
Type: integer
min:
0

Current pagination offset (starting position in the result set). Corresponds to the offset parameter from the request.

total
Type: integerFormat: int64
min:
0

Total count of modules matching the filter criteria (across all pages). Used for calculating pagination metadata.
application/json
401
Type: object
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
application/json
403
Type: object

Forbidden - The authenticated plugin does not have permissions to access modules. This typically indicates an authorization configuration issue.

application/json

get/api/v1/customblocks/v4/modules/list

curl 'https://plugins.stripo.email/api/v1/customblocks/v4/modules/list?key=header-templates&query=newsletter&categories=1&categories=2&categories=5&tags=promotional&tags=seasonal&id=12345&synchronizable=true&withContent=false&sortingColumn=name&sortingAsc=true&offset=0&page=1&limit=20' \
  --header 'ES-PLUGIN-AUTH: Bearer YOUR_AUTH_TOKEN' \
  --header 'ES-PLUGIN-AUTH: YOUR_SECRET_TOKEN'

Show Schema

Basic module list with content (withContent=true)

{
  "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
}

Modules list retrieved successfully. Returns a paginated list of modules with metadata and optionally HTML/CSS content.

Models

Response containing a paginated list of plugin modules with metadata

limit
Type: integer
min:
1

Maximum number of modules returned in this page. Corresponds to the limit parameter from the request.
modules
Type:

Array of module objects. Each module contains metadata and optionally HTML/CSS content (depending on the withContent parameter).

Properties: 16
offset
Type: integer
min:
0

Current pagination offset (starting position in the result set). Corresponds to the offset parameter from the request.
total
Type: integerFormat: int64
min:
0

Total count of modules matching the filter criteria (across all pages). Used for calculating pagination metadata.

Represents a single plugin module with all its metadata and optional content

blockType
Type: string

Type of block. Determines how the module behaves in the editor.
category
Type: object

Category information for the module. Categories provide high-level organization of modules in the editor's library.

Properties: 2
createdOn
Type: stringFormat: date-time

ISO 8601 timestamp indicating when the module was created.
croppedIcon
Type: string

URL to the cropped version of the module's icon. Used for optimized display.
css
Type: string | null

CSS styles for the module. Applied to the HTML content when rendered. This field will be null when withContent=false (default) or not specified.
description
Type: string

Textual description of the module. Provides additional context about the module's purpose and design.
html
Type: string | null

HTML content of the module. Contains the email template markup. This field will be null when withContent=false (default) or not specified.
icon
Type: string

URL to the module's icon image. Displayed as thumbnail in the module library.
id
Type: integerFormat: int64

Unique identifier of the module within the plugin.
key
Type: string

Module key (folder name). Used for organizing modules into logical groups.
name
Type: string

Human-readable name of the module. Displayed in the editor's module library.
scope
Type: stringenum

Defines the section of the email where this module can be used. Modules are organized by scope in the editor's module library.

values
INFO_AREAHEADERMENUCONTENTFOOTER
synchronizable
Type: boolean

Indicates whether this module supports synchronization. Synchronized modules can be updated across multiple email templates automatically.
tagObjects
Type: array of object

List of tag objects with full details including tag IDs. Provides more complete information than the tags array.

Properties: 2
tags
Type: array of string

List of tag values associated with the module. Tags provide additional categorization and filtering capabilities. This is a simplified array of string values.
updatedOn
Type: stringFormat: date-time

ISO 8601 timestamp indicating when the module was last updated.