{
"openapi": "3.1.0",
"info": {
"title": "Mailjet Content API",
"description": "A complete collection of all publicly available endpoints for the Mailjet Content API (v1). Manage email templates, template contents, images, labels and authentication tokens.",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.mailjet.com"
}
],
"paths": {
"/v1/REST/templates": {
"get": {
"x-seo": {
"title": "List of templates",
"description": "Retrieve a comprehensive list of templates and their corresponding data, including the ExternalID which is needed to send your templates."
},
"tags": [
"Templates"
],
"summary": "List of templates",
"description": "Retrieve a comprehensive list of templates and their corresponding data, including the ExternalID which is needed to send your templates.",
"operationId": "get_v1_templates",
"parameters": [
{
"name": "Sort",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/Sort"
}
},
{
"name": "CheckLocaleOnLastContent",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/CheckLocaleOnLastContent"
}
},
{
"name": "ID",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/ID"
}
},
{
"name": "IDs",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/IDs"
}
},
{
"name": "Name",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/Name"
}
},
{
"name": "PartialName",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/PartialName"
}
},
{
"name": "Locale",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/Locale"
}
},
{
"name": "EditMode",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/EditMode"
}
},
{
"name": "LabelIDs",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/LabelIDs"
}
},
{
"name": "Purposes",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/Purposes"
}
},
{
"name": "ExternalID",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/ExternalID"
}
},
{
"name": "IsPublished",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/IsPublished"
}
},
{
"name": "IsStarred",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/IsStarred"
}
},
{
"name": "Limit",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/Limit"
},
"example": 10
},
{
"name": "Offset",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_templates_QueryParams/properties/Offset"
},
"example": 0
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/templatesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
},
"post": {
"x-seo": {
"title": "Create a template",
"description": "Create a new email template. This is the first step before adding content to it. Once your template has been successfully created, use the Create…"
},
"tags": [
"Templates"
],
"summary": "Create a template",
"description": "Create a new email template. This is the first step before adding content to it. Once your template has been successfully created, use the Create Template Content endpoint to add and customize the content.",
"operationId": "post_v1_templates",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTemplateRequest"
},
"example": {
"Name": "Example Template",
"EditMode": 2,
"Purposes": [
"transactional"
],
"Description": "An example template created via the Try It console.",
"IsStarred": false
}
}
}
},
"responses": {
"201": {
"description": "Template created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/templatesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/REST/templates/{id}": {
"get": {
"x-seo": {
"title": "Retrieve a single template",
"description": "Retrieve detailed information about a specific email template using its unique template ID. This endpoint is particularly useful when you need to fetch…"
},
"tags": [
"Templates"
],
"summary": "Retrieve a single template",
"description": "Retrieve detailed information about a specific email template using its unique template ID. This endpoint is particularly useful when you need to fetch the details of a single template for viewing, editing, or sending purposes. To obtain a valid `id`, first call `GET /v1/REST/templates` to list your templates.",
"operationId": "get_v1_template_by_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the template.",
"example": 101
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/templatesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
},
"put": {
"x-seo": {
"title": "Update a template",
"description": "Update a template using its unique ID. Add new labels, modify the name, add it as a favorite and more. All PUT requests behave like PATCH requests — only…"
},
"tags": [
"Templates"
],
"summary": "Update a template",
"description": "Update a template using its unique ID. Add new labels, modify the name, add it as a favorite and more. All PUT requests behave like PATCH requests — only the specified properties are updated. To obtain a valid `id`, first call `GET /v1/REST/templates` to list your templates.",
"operationId": "put_v1_template",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the template.",
"example": 101
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTemplateRequest"
},
"example": {
"Name": "Example Template",
"IsStarred": false
}
}
}
},
"responses": {
"200": {
"description": "Template updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/templatesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
},
"delete": {
"x-seo": {
"title": "Delete a template",
"description": "Delete a template in the Mailjet Content API. Permanently delete a template using its unique ID. Once a template is deleted, it cannot be restored."
},
"tags": [
"Templates"
],
"summary": "Delete a template",
"description": "Permanently delete a template using its unique ID. Once a template is deleted, it cannot be restored.",
"operationId": "delete_v1_template",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the template."
}
],
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/REST/templates/{id}/contents": {
"get": {
"x-seo": {
"title": "List all template content",
"description": "Retrieve previous versions of your template's content. You can access the five most recent versions for each status (Draft, Published, Autosave). This is…"
},
"tags": [
"Template Contents"
],
"summary": "List all template content",
"description": "Retrieve previous versions of your template's content. You can access the five most recent versions for each status (Draft, Published, Autosave). This is useful when looking to revert your template content to a previous version. To obtain a valid `id`, first call `GET /v1/REST/templates` to list your templates.",
"operationId": "get_v1_template_contents",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the template.",
"example": 101
},
{
"name": "Sort",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_template_contents_QueryParams/properties/Sort"
}
},
{
"name": "ID",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_template_contents_QueryParams/properties/ID"
}
},
{
"name": "Locale",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_template_contents_QueryParams/properties/Locale"
}
},
{
"name": "ContentType",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_template_contents_QueryParams/properties/ContentType"
}
},
{
"name": "IsLocked",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_template_contents_QueryParams/properties/IsLocked"
}
},
{
"name": "Limit",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_template_contents_QueryParams/properties/Limit"
},
"example": 10
},
{
"name": "Offset",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_template_contents_QueryParams/properties/Offset"
},
"example": 0
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/templateContentsResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
},
"post": {
"x-seo": {
"title": "Create template content",
"description": "Add content to an existing template. You will need to specify the template ID and include either MJML, HTML or plain text. A locale is required in order…"
},
"tags": [
"Template Contents"
],
"summary": "Create template content",
"description": "Add content to an existing template. You will need to specify the template ID and include either MJML, HTML or plain text. A locale is required in order to save and send your template. To obtain a valid `id`, first call `GET /v1/REST/templates` to list your templates.",
"operationId": "post_v1_template_contents",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the template.",
"example": 101
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTemplateContentRequest"
},
"example": {
"Locale": "en_US",
"Name": "Example Content",
"Author": "Example Author",
"HTMLPart": "Hello from Mailjet
",
"TextPart": "Greetings from Mailjet!",
"Headers": {
"Subject": "Hello from Mailjet",
"From": "Example Sender ",
"SenderName": "Example Sender",
"SenderEmail": "no-reply@example.com"
}
}
}
}
},
"responses": {
"201": {
"description": "Template content created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/templateContent"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/REST/templates/{id}/contents/types/{content_type}": {
"get": {
"x-seo": {
"title": "Get template content by status",
"description": "Retrieve the most recent content of your template based on its status. This endpoint allows you to access specific versions of your template content…"
},
"tags": [
"Template Contents"
],
"summary": "Get template content by status",
"description": "Retrieve the most recent content of your template based on its status. This endpoint allows you to access specific versions of your template content based on their status — Draft, Published, or Autosave. To obtain a valid `id`, first call `GET /v1/REST/templates` to list your templates.",
"operationId": "get_v1_template_content_by_type",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the template.",
"example": 101
},
{
"name": "content_type",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"D",
"P",
"A"
]
},
"description": "The content status to retrieve. Accepted values: D (Draft), P (Published), A (Autosave).",
"example": "D"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/templateContentsResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
},
"put": {
"x-seo": {
"title": "Update template content",
"description": "Update draft template content. The endpoint takes the latest draft version, applies your changes, and creates a new draft version. If your template…"
},
"tags": [
"Template Contents"
],
"summary": "Update template content",
"description": "Update draft template content. The endpoint takes the latest draft version, applies your changes, and creates a new draft version. If your template content is published, you should create new content and then publish it instead. To obtain a valid `id`, first call `GET /v1/REST/templates` to list your templates.",
"operationId": "put_v1_template_content_by_type",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the template.",
"example": 101
},
{
"name": "content_type",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"D"
]
},
"description": "The content status to update. Accepted value: D (Draft).",
"example": "D"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTemplateContentRequest"
},
"example": {
"HTMLPart": "Hello from Mailjet
",
"TextPart": "Greetings from Mailjet!"
}
}
}
},
"responses": {
"200": {
"description": "Template content updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/templateContentsResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/REST/templates/{id}/contents/publish": {
"post": {
"x-seo": {
"title": "Publish template content",
"description": "Publish the content of your template to make it available for sending. When you publish, it is always the most recent draft content that is published…"
},
"tags": [
"Template Contents"
],
"summary": "Publish template content",
"description": "Publish the content of your template to make it available for sending. When you publish, it is always the most recent draft content that is published. Verify that your most recent draft is the content you wish to publish. To obtain a valid `id`, first call `GET /v1/REST/templates` to list your templates.",
"operationId": "post_v1_template_contents_publish",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the template.",
"example": 101
}
],
"responses": {
"200": {
"description": "Template content published successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/templateContentsResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/REST/templates/{id}/contents/lock": {
"post": {
"x-seo": {
"title": "Lock template content",
"description": "Lock the content of your template to prevent any further edits. This ensures that the current version remains unchanged until it is unlocked."
},
"tags": [
"Template Contents"
],
"summary": "Lock template content",
"description": "Lock the content of your template to prevent any further edits. This ensures that the current version remains unchanged until it is unlocked. To obtain a valid `id`, first call `GET /v1/REST/templates` to list your templates.",
"operationId": "post_v1_template_contents_lock",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the template.",
"example": 101
}
],
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/REST/templates/{id}/contents/unlock": {
"post": {
"x-seo": {
"title": "Unlock template content",
"description": "Unlock template content in the Mailjet Content API. Unlock the content of your template to allow edits again after it has been locked."
},
"tags": [
"Template Contents"
],
"summary": "Unlock template content",
"description": "Unlock the content of your template to allow edits again after it has been locked. To obtain a valid `id`, first call `GET /v1/REST/templates` to list your templates.",
"operationId": "post_v1_template_contents_unlock",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the template.",
"example": 101
}
],
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/REST/images": {
"get": {
"x-seo": {
"title": "List image metadata",
"description": "Retrieve metadata for multiple images, including details such as image ID, status, name, and label IDs. This endpoint is useful for retrieving the URLs…"
},
"tags": [
"Images"
],
"summary": "List image metadata",
"description": "Retrieve metadata for multiple images, including details such as image ID, status, name, and label IDs. This endpoint is useful for retrieving the URLs of images you would like to use in your templates.",
"operationId": "get_v1_images",
"parameters": [
{
"name": "ID",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_images_QueryParams/properties/ID"
}
},
{
"name": "IDs",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_images_QueryParams/properties/IDs"
}
},
{
"name": "IsStarred",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_images_QueryParams/properties/IsStarred"
}
},
{
"name": "Status",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_images_QueryParams/properties/Status"
}
},
{
"name": "LabelIDs",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_images_QueryParams/properties/LabelIDs"
}
},
{
"name": "Name",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_images_QueryParams/properties/Name"
}
},
{
"name": "PartialName",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_images_QueryParams/properties/PartialName"
}
},
{
"name": "Limit",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_images_QueryParams/properties/Limit"
},
"example": 10
},
{
"name": "Offset",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_images_QueryParams/properties/Offset"
},
"example": 0
},
{
"name": "Sort",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_images_QueryParams/properties/Sort"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/imagesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/data/images": {
"post": {
"x-seo": {
"title": "Upload an image",
"description": "Upload an image along with its metadata to the Mailjet image gallery. The maximum upload size for a single image is 2MB. Image files used in emails…"
},
"tags": [
"Images"
],
"summary": "Upload an image",
"description": "Upload an image along with its metadata to the Mailjet image gallery. The maximum upload size for a single image is 2MB. Image files used in emails should not exceed 200KB to optimize loading times.",
"operationId": "post_v1_data_images",
"requestBody": {
"required": true,
"content": {
"multipart/mixed": {
"schema": {
"$ref": "#/components/schemas/UploadImageRequest"
}
},
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/UploadImageRequest"
}
}
}
},
"responses": {
"201": {
"description": "Image uploaded successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/imagesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/data/images/{id}/{image_content_type}": {
"put": {
"x-seo": {
"title": "Upload a thumbnail or update an image",
"description": "Upload or update the thumbnail of an existing image, or update an existing image file. The image content type parameter determines whether the request is…"
},
"tags": [
"Images"
],
"summary": "Upload a thumbnail or update an image",
"description": "Upload or update the thumbnail of an existing image, or update an existing image file. The image_content_type parameter determines whether the request is for the image itself (content) or a thumbnail (thumbnail). To obtain a valid `id`, first call `GET /v1/REST/images` to list your images.",
"operationId": "put_v1_data_images_content",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the image (UUID).",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
{
"name": "image_content_type",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"content",
"thumbnail"
]
},
"description": "Whether to update the image or its thumbnail. Accepted values: content, thumbnail.",
"example": "content"
}
],
"requestBody": {
"required": true,
"content": {
"multipart/mixed": {
"schema": {
"$ref": "#/components/schemas/UploadImageFileRequest"
}
},
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/UploadImageFileRequest"
}
}
}
},
"responses": {
"200": {
"description": "Image updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/imagesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/REST/images/{id}": {
"get": {
"x-seo": {
"title": "Retrieve image metadata",
"description": "Retrieve metadata for a single image using its unique ID, including details such as the status, name, and label IDs."
},
"tags": [
"Images"
],
"summary": "Retrieve image metadata",
"description": "Retrieve metadata for a single image using its unique ID, including details such as the status, name, and label IDs. To obtain a valid `id`, first call `GET /v1/REST/images` to list your images.",
"operationId": "get_v1_image_by_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the image (UUID).",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/imagesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
},
"put": {
"x-seo": {
"title": "Update image metadata",
"description": "Update the metadata of an existing image using its unique ID. Only the metadata (name, status, labels, starred) can be updated through this endpoint, not…"
},
"tags": [
"Images"
],
"summary": "Update image metadata",
"description": "Update the metadata of an existing image using its unique ID. Only the metadata (name, status, labels, starred) can be updated through this endpoint, not the image file itself. To obtain a valid `id`, first call `GET /v1/REST/images` to list your images.",
"operationId": "put_v1_image",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the image (UUID).",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateImageMetadataRequest"
},
"example": {
"Name": "Example Image",
"Status": "open",
"IsStarred": false
}
}
}
},
"responses": {
"200": {
"description": "Image metadata updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/imagesResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
},
"delete": {
"x-seo": {
"title": "Delete an image",
"description": "Delete an image in the Mailjet Content API. Permanently delete an image using its unique ID. Once an image is deleted, it cannot be restored."
},
"tags": [
"Images"
],
"summary": "Delete an image",
"description": "Permanently delete an image using its unique ID. Once an image is deleted, it cannot be restored.",
"operationId": "delete_v1_image",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the image (UUID)."
}
],
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/REST/labels": {
"get": {
"x-seo": {
"title": "List labels",
"description": "Retrieve a list of your labels. Labels are used to categorize your images or templates by assigning tags to them."
},
"tags": [
"Labels"
],
"summary": "List labels",
"description": "Retrieve a list of your labels. Labels are used to categorize your images or templates by assigning tags to them.",
"operationId": "get_v1_labels",
"parameters": [
{
"name": "Name",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_labels_QueryParams/properties/Name"
}
},
{
"name": "IDs",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_labels_QueryParams/properties/IDs"
}
},
{
"name": "UsedFor",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_labels_QueryParams/properties/UsedFor"
}
},
{
"name": "Limit",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_labels_QueryParams/properties/Limit"
},
"example": 10
},
{
"name": "Offset",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_labels_QueryParams/properties/Offset"
},
"example": 0
},
{
"name": "Sort",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_labels_QueryParams/properties/Sort"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/labelsResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
},
"post": {
"x-seo": {
"title": "Create a label",
"description": "Create a label to categorize resources (templates) or images for better organization. Each label has a unique name, a color represented as a hexadecimal…"
},
"tags": [
"Labels"
],
"summary": "Create a label",
"description": "Create a label to categorize resources (templates) or images for better organization. Each label has a unique name, a color represented as a hexadecimal code, and a type indicating whether it is used for images or templates.",
"operationId": "post_v1_labels",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateLabelRequest"
},
"example": {
"Name": "Example Label",
"Color": "#00AEEF",
"UsedFor": "resource"
}
}
}
},
"responses": {
"201": {
"description": "Label created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/labelsResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/REST/labels/{id}": {
"get": {
"x-seo": {
"title": "Retrieve a single label",
"description": "Retrieve a single label using the Mailjet Content API. Retrieve a single label using its unique ID."
},
"tags": [
"Labels"
],
"summary": "Retrieve a single label",
"description": "Retrieve a single label using its unique ID. To obtain a valid `id`, first call `GET /v1/REST/labels` to list your labels.",
"operationId": "get_v1_label_by_id",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the label.",
"example": 102
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/labelsResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
},
"put": {
"x-seo": {
"title": "Update a label",
"description": "Update a label using its unique ID. You can update its name and color. All PUT requests behave like PATCH requests — only the specified properties are…"
},
"tags": [
"Labels"
],
"summary": "Update a label",
"description": "Update a label using its unique ID. You can update its name and color. All PUT requests behave like PATCH requests — only the specified properties are updated. To obtain a valid `id`, first call `GET /v1/REST/labels` to list your labels.",
"operationId": "put_v1_label",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the label.",
"example": 102
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateLabelRequest"
},
"example": {
"Name": "Example Label",
"Color": "#00AEEF"
}
}
}
},
"responses": {
"200": {
"description": "Label updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/labelsResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
},
"delete": {
"x-seo": {
"title": "Delete a label",
"description": "Permanently delete a label using its unique ID. Once a label is deleted, it will be removed from all images or templates and cannot be restored."
},
"tags": [
"Labels"
],
"summary": "Delete a label",
"description": "Permanently delete a label using its unique ID. Once a label is deleted, it will be removed from all images or templates and cannot be restored.",
"operationId": "delete_v1_label",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the label."
}
],
"responses": {
"204": {
"$ref": "#/components/responses/204"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/REST/tokens": {
"get": {
"x-seo": {
"title": "List tokens",
"description": "Retrieve a comprehensive list of all tokens created. This allows for easy oversight and management of token permissions and statuses."
},
"tags": [
"Tokens"
],
"summary": "List tokens",
"description": "Retrieve a comprehensive list of all tokens created. This allows for easy oversight and management of token permissions and statuses.",
"operationId": "get_v1_tokens",
"parameters": [
{
"name": "Name",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_tokens_QueryParams/properties/Name"
}
},
{
"name": "Limit",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_tokens_QueryParams/properties/Limit"
},
"example": 10
},
{
"name": "Offset",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_tokens_QueryParams/properties/Offset"
},
"example": 0
},
{
"name": "Sort",
"in": "query",
"schema": {
"$ref": "#/components/schemas/get_v1_tokens_QueryParams/properties/Sort"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/tokensResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
},
"post": {
"x-seo": {
"title": "Create a token",
"description": "Create a Bearer Token to authenticate requests and manage permissions for different operations. The token value will be displayed only once at creation…"
},
"tags": [
"Tokens"
],
"summary": "Create a token",
"description": "Create a Bearer Token to authenticate requests and manage permissions for different operations. The token value will be displayed only once at creation time. Securely store it immediately.",
"operationId": "post_v1_tokens",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTokenRequest"
},
"example": {
"Name": "Example Token",
"Permissions": [
"read_template"
],
"ExpiresInDays": 365
}
}
}
},
"responses": {
"201": {
"description": "Token created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/tokensResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
},
"/v1/REST/tokens/{id}": {
"put": {
"x-seo": {
"title": "Update a token",
"description": "Update a token's properties, such as its name or permissions, to reflect changes in your security policies or operational requirements. Use this endpoint…"
},
"tags": [
"Tokens"
],
"summary": "Update a token",
"description": "Update a token's properties, such as its name or permissions, to reflect changes in your security policies or operational requirements. Use this endpoint to renew a token before it expires. To obtain a valid `id`, first call `GET /v1/REST/tokens` to list your tokens.",
"operationId": "put_v1_token",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the token.",
"example": 103
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTokenRequest"
},
"example": {
"Name": "Example Token",
"Permissions": [
"read_template"
],
"ExpiresAt": "2025-01-01T00:00:00Z"
}
}
}
},
"responses": {
"200": {
"description": "Token updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/tokensResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"404": {
"$ref": "#/components/responses/404"
},
"429": {
"$ref": "#/components/responses/429"
},
"500": {
"$ref": "#/components/responses/500"
}
},
"security": [
{
"basicAuth": []
},
{
"bearerAuth": []
}
]
}
}
},
"components": {
"schemas": {
"templatesResponse": {
"type": "object",
"properties": {
"Count": {
"type": "integer",
"description": "Number of items in this response"
},
"Data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ID": {
"type": "integer",
"description": "The ID of the template."
},
"Name": {
"type": "string",
"description": "The name of the template."
},
"EditMode": {
"type": "integer",
"description": "Specifies the mode in which the template can be edited. Values: 1 (Drag-and-drop), 2 (HTML builder), 3 (Saved Section), 4 (MJML builder)."
},
"LabelIDs": {
"type": "array",
"items": {
"type": "integer"
},
"description": "An array of IDs representing labels associated with the template."
},
"Purposes": {
"type": "array",
"items": {
"type": "string"
},
"description": "The purposes of the template. Accepted values: marketing, transactional, automation, opt-in."
},
"ExternalID": {
"type": [
"string",
"null"
],
"description": "The ID that must be used to send the template."
},
"Description": {
"type": [
"string",
"null"
],
"description": "A brief description of the template."
},
"IsPublished": {
"type": "boolean",
"description": "Indicates whether the template is published."
},
"IsStarred": {
"type": "boolean",
"description": "Indicates whether the template is marked as a favorite."
},
"IsTextPartGenerationEnabled": {
"type": "boolean",
"description": "Determines if text part generation functionality is enabled for this template."
},
"CreatedAt": {
"type": "string",
"format": "date-time",
"description": "The date and time when the template was created (RFC3339)."
},
"UpdatedAt": {
"type": "string",
"format": "date-time",
"description": "The date and time when the template was last updated (RFC3339)."
}
},
"title": "template"
}
},
"Total": {
"type": "integer",
"description": "Total number of items available"
}
}
},
"templateContent": {
"type": "object",
"description": "A single template content object (returned by create endpoint without Count/Data/Total wrapper).",
"properties": {
"ID": {
"type": "integer",
"description": "The ID of the content version."
},
"TemplateID": {
"type": "integer",
"description": "The ID of the template."
},
"ContentType": {
"type": "string",
"description": "Content status. Values: D (Draft), P (Published), A (Autosave). Always D when created."
},
"Author": {
"type": [
"string",
"null"
],
"description": "The name of the person or entity creating the template content."
},
"Name": {
"type": "string",
"description": "The name of the template content."
},
"IsLocked": {
"type": "boolean",
"description": "If true, the template content cannot be edited."
},
"Locale": {
"type": "string",
"description": "Specifies the locale (language and region) for the template content."
},
"MJMLPart": {
"type": [
"string",
"null"
],
"description": "The MJML code for the template."
},
"HTMLPart": {
"type": [
"string",
"null"
],
"description": "The HTML code for the template."
},
"TextPart": {
"type": [
"string",
"null"
],
"description": "The plain text version of the template content."
},
"Headers": {
"type": "object",
"description": "Additional headers for the template in JSON format (Subject, From, Reply-To, SenderName, SenderEmail)."
},
"CreatedAt": {
"type": "string",
"format": "date-time",
"description": "The date and time when the content was created (RFC3339)."
},
"UpdatedAt": {
"type": "string",
"format": "date-time",
"description": "The date and time when the content was last updated (RFC3339)."
}
}
},
"templateContentsResponse": {
"type": "object",
"properties": {
"Count": {
"type": "integer",
"description": "Number of items in this response"
},
"Data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/templateContent"
}
},
"Total": {
"type": "integer",
"description": "Total number of items available"
}
}
},
"imagesResponse": {
"type": "object",
"properties": {
"Count": {
"type": "integer",
"description": "Number of items in this response"
},
"Data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ID": {
"type": "string",
"description": "The ID of the image (UUID)."
},
"Name": {
"type": "string",
"description": "The name of the image."
},
"Status": {
"type": "string",
"description": "Indicates whether the image is open or locked. Values: open, locked."
},
"TargetContent": {
"type": "string",
"description": "Indicates the purpose of the image. Values: image, background, video, social."
},
"ImageSize": {
"type": "integer",
"description": "The size of the image file in bytes."
},
"LabelIDs": {
"type": "array",
"items": {
"type": "integer"
},
"description": "An array of IDs representing labels associated with the image."
},
"IsStarred": {
"type": "boolean",
"description": "Indicates whether the image is marked as a favorite."
},
"ImageUrl": {
"type": "string",
"description": "The URL where the image is stored."
},
"ThumbnailUrl": {
"type": "string",
"description": "The URL where the thumbnail is stored."
},
"CreatedAt": {
"type": "string",
"format": "date-time",
"description": "The date and time when the image was created (RFC3339)."
},
"UpdatedAt": {
"type": "string",
"format": "date-time",
"description": "The date and time when the image was last updated (RFC3339)."
},
"ExpiresAt": {
"type": "string",
"format": "date-time",
"description": "The date and time when the image will expire (RFC3339)."
}
},
"title": "image"
}
},
"Total": {
"type": "integer",
"description": "Total number of items available"
}
}
},
"labelsResponse": {
"type": "object",
"properties": {
"Count": {
"type": "integer",
"description": "Number of items in this response"
},
"Data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ID": {
"type": "integer",
"description": "The ID of the label."
},
"Name": {
"type": "string",
"description": "The name of the label."
},
"Color": {
"type": "string",
"description": "The hexadecimal color of the label (e.g."
},
"UsedFor": {
"type": "string",
"description": "Indicates if the label is used for a template or an image. Values: resource, image."
}
},
"title": "label"
}
},
"Total": {
"type": "integer",
"description": "Total number of items available"
}
}
},
"tokensResponse": {
"type": "object",
"properties": {
"Count": {
"type": "integer",
"description": "Number of items in this response"
},
"Data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ID": {
"type": "integer",
"description": "The ID of the token."
},
"Name": {
"type": "string",
"description": "A unique identifier for the token."
},
"Permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of permissions assigned to the token."
},
"AccessToken": {
"type": [
"string",
"null"
],
"description": "The token value to use for authentication. Only displayed once at creation time."
},
"ExpiresAt": {
"type": "string",
"format": "date-time",
"description": "Date at which the token expires (RFC3339)."
},
"CreatedAt": {
"type": "string",
"format": "date-time",
"description": "Date on which the token was created (RFC3339)."
},
"UpdatedAt": {
"type": "string",
"format": "date-time",
"description": "Date on which the token was last updated (RFC3339)."
}
},
"title": "token"
}
},
"Total": {
"type": "integer",
"description": "Total number of items available"
}
}
},
"CreateTemplateRequest": {
"type": "object",
"required": [
"Name"
],
"properties": {
"Name": {
"type": "string",
"description": "Required. A unique identifier for the template."
},
"EditMode": {
"type": "integer",
"description": "Specifies the mode in which the template can be edited. Default: 2 (HTML builder). Values: 2 (HTML builder), 4 (MJML builder)."
},
"LabelIDs": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Labels associated with the template."
},
"Purposes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"marketing",
"transactional",
"automation",
"opt-in"
]
},
"description": "Required if you would like the template to appear in the UI."
},
"Description": {
"type": [
"string",
"null"
],
"description": "A brief description of the template."
},
"IsStarred": {
"type": "boolean",
"description": "Indicates whether the template is marked as a favorite."
},
"IsTextPartGenerationEnabled": {
"type": "boolean",
"description": "Determines if text part generation functionality is enabled for this template."
}
}
},
"UpdateTemplateRequest": {
"type": "object",
"properties": {
"Name": {
"type": "string",
"description": "A unique identifier for the template."
},
"EditMode": {
"type": "integer",
"description": "Specifies the mode in which the template can be edited. Values: 2 (HTML builder), 4 (MJML builder)."
},
"LabelIDs": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Labels associated with the template."
},
"Purposes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"marketing",
"transactional",
"automation",
"opt-in"
]
},
"description": "The purposes of the template."
},
"Description": {
"type": [
"string",
"null"
],
"description": "A brief description of the template."
},
"IsStarred": {
"type": "boolean",
"description": "Indicates whether the template is marked as a favorite."
},
"IsTextPartGenerationEnabled": {
"type": "boolean",
"description": "Determines if text part generation functionality is enabled for this template."
}
}
},
"CreateTemplateContentRequest": {
"type": "object",
"required": [
"Locale"
],
"properties": {
"Author": {
"type": "string",
"description": "The name of the person or entity creating the template content."
},
"Name": {
"type": "string",
"description": "The name of the template content."
},
"Locale": {
"type": "string",
"description": "Required. Specifies the locale for the template content (e.g. en_US, fr_FR, de_DE, es_ES, it_IT, pt_BR, ja_JP, zh_CN, etc.)."
},
"MJMLPart": {
"type": "string",
"description": "The MJML code for the template. Either MJMLPart, TextPart or HTMLPart must be provided."
},
"HTMLPart": {
"type": "string",
"description": "The HTML code for the template. Either MJMLPart, TextPart or HTMLPart must be provided."
},
"TextPart": {
"type": "string",
"description": "The plain text version of the template content. Either MJMLPart, TextPart or HTMLPart must be provided."
},
"Headers": {
"type": "object",
"description": "Additional headers for the template in JSON format (Subject, From, Reply-To, SenderName, SenderEmail).",
"properties": {
"Subject": {
"type": "string",
"description": "The email subject line."
},
"From": {
"type": "string",
"description": "The sender identity (e.g. \"MyCompany \")."
},
"Reply-To": {
"type": "string",
"description": "The reply-to email address."
},
"SenderName": {
"type": "string",
"description": "The sender display name."
},
"SenderEmail": {
"type": "string",
"description": "The sender email address."
}
}
}
}
},
"UpdateTemplateContentRequest": {
"type": "object",
"properties": {
"Author": {
"type": "string",
"description": "The name of the person or entity creating the template content."
},
"Name": {
"type": "string",
"description": "The name of the template content."
},
"Locale": {
"type": "string",
"description": "Specifies the locale for the template content."
},
"MJMLPart": {
"type": [
"string",
"null"
],
"description": "The MJML code for the template."
},
"HTMLPart": {
"type": [
"string",
"null"
],
"description": "The HTML code for the template."
},
"TextPart": {
"type": [
"string",
"null"
],
"description": "The plain text version of the template content."
},
"Headers": {
"type": "object",
"description": "Additional headers for the template in JSON format.",
"properties": {
"Subject": {
"type": "string",
"description": "The email subject line."
},
"From": {
"type": "string",
"description": "The sender identity (e.g. \"MyCompany \")."
},
"Reply-To": {
"type": "string",
"description": "The reply-to email address."
},
"SenderName": {
"type": "string",
"description": "The sender display name."
},
"SenderEmail": {
"type": "string",
"description": "The sender email address."
}
}
}
}
},
"UploadImageRequest": {
"type": "object",
"required": [
"file",
"Metadata"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "The binary data of the image. Supported content types: image/jpeg, image/png, image/svg, image/gif, image/webp. Maximum size: 2MB."
},
"Metadata": {
"type": "object",
"required": [
"Name",
"Status"
],
"description": "A JSON object containing image metadata.",
"properties": {
"Name": {
"type": "string",
"description": "Required. The name of the image."
},
"Status": {
"type": "string",
"enum": [
"open",
"locked"
],
"description": "Required. Whether the image is open for editing or locked."
},
"LabelIDs": {
"type": "array",
"items": {
"type": "integer"
},
"description": "An array of IDs representing labels associated with the image."
},
"IsStarred": {
"type": "boolean",
"description": "Indicates whether the image is marked as a favorite."
}
}
}
}
},
"UploadImageFileRequest": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "The binary data of the image. Supported content types: image/jpeg, image/png, image/svg, image/gif, image/webp."
}
}
},
"UpdateImageMetadataRequest": {
"type": "object",
"properties": {
"Name": {
"type": "string",
"description": "The name of the image."
},
"Status": {
"type": "string",
"enum": [
"open",
"locked"
],
"description": "Whether the image is open for editing or locked."
},
"LabelIDs": {
"type": "array",
"items": {
"type": "integer"
},
"description": "An array of IDs representing labels associated with the image."
},
"IsStarred": {
"type": "boolean",
"description": "Indicates whether the image is marked as a favorite."
}
}
},
"CreateLabelRequest": {
"type": "object",
"required": [
"Name",
"Color"
],
"properties": {
"Name": {
"type": "string",
"description": "Required. Must be unique."
},
"Color": {
"type": "string",
"description": "Required. Should be a valid hexadecimal color (e.g."
},
"UsedFor": {
"type": "string",
"enum": [
"resource",
"image"
],
"description": "Indicates if the label is used for a template (resource) or an image. Default: resource."
}
}
},
"UpdateLabelRequest": {
"type": "object",
"properties": {
"Name": {
"type": "string",
"description": "Must be unique."
},
"Color": {
"type": "string",
"description": "Should be a valid hexadecimal color (e.g."
}
}
},
"CreateTokenRequest": {
"type": "object",
"required": [
"Name"
],
"properties": {
"Name": {
"type": "string",
"description": "Required. A unique identifier for the token."
},
"Permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of permissions assigned to the token (e.g. read_template, create_template, update_template, delete_template, read_image, create_image, etc.)."
},
"ExpiresInDays": {
"type": "integer",
"description": "Number of days until the token expires. Default: 365 days."
},
"ExpiresAt": {
"type": "string",
"format": "date-time",
"description": "Date at which the token expires (RFC3339)."
}
}
},
"UpdateTokenRequest": {
"type": "object",
"required": [
"Name"
],
"properties": {
"Name": {
"type": "string",
"description": "Required. Name of the existing token."
},
"Permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of permissions assigned to the token."
},
"ExpiresAt": {
"type": "string",
"format": "date-time",
"description": "Date at which the token expires (RFC3339)."
}
}
},
"get_v1_templates_QueryParams": {
"type": "object",
"additionalProperties": false,
"properties": {
"Sort": {
"type": "string",
"description": "Sort results by a property. Available: Name, CreatedAt, IsStarred, UpdatedAt. Default: ID ASC. Example: Sort=Name+DESC"
},
"CheckLocaleOnLastContent": {
"type": "boolean",
"description": "Set to true to check the value of the Locale query parameter based on the last content."
},
"ID": {
"type": "integer",
"description": "Search by the ID of the template."
},
"IDs": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Search by multiple template IDs."
},
"Name": {
"type": "string",
"description": "Search by the template name. Only returns exact match."
},
"PartialName": {
"type": "string",
"description": "Search by partial or fragmentary name."
},
"Locale": {
"type": "string",
"description": "Search by the template locale."
},
"EditMode": {
"type": "integer",
"description": "Filter by edit mode. Accepted values: 1, 2, 3 or 4."
},
"LabelIDs": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Search by label IDs associated to a template."
},
"Purposes": {
"type": "string",
"description": "Comma-separated list of purposes. Filters templates having all specified purposes. Accepted values — marketing, transactional, opt-in, automation."
},
"ExternalID": {
"type": "string",
"description": "Search by the send ID of the template."
},
"IsPublished": {
"type": "boolean",
"description": "Filter by published status. True = published."
},
"IsStarred": {
"type": "boolean",
"description": "Filter by favorite status. True = favorite."
},
"Limit": {
"type": "integer",
"description": "The number of results returned per page. Default: 10, maximum: 1000."
},
"Offset": {
"type": "integer",
"description": "The index of the first object in the page."
}
}
},
"get_v1_template_contents_QueryParams": {
"type": "object",
"additionalProperties": false,
"properties": {
"Sort": {
"type": "string",
"description": "Sort results by a property. Available: UpdatedAt. Default: UpdatedAt DESC."
},
"ID": {
"type": "integer",
"description": "The ID of the content version."
},
"Locale": {
"type": "string",
"description": "Specifies the locale for the template content."
},
"ContentType": {
"type": "string",
"description": "Filter by content type. Values: D (Draft), P (Published), A (Autosave).",
"enum": [
"D",
"P",
"A"
]
},
"IsLocked": {
"type": "boolean",
"description": "Filter by locked status. True = locked."
},
"Limit": {
"type": "integer",
"description": "The number of results returned per page. Default: 10, maximum: 1000."
},
"Offset": {
"type": "integer",
"description": "The index of the first object in the page."
}
}
},
"get_v1_images_QueryParams": {
"type": "object",
"additionalProperties": false,
"properties": {
"ID": {
"type": "string",
"description": "The ID of the image (UUID)."
},
"IDs": {
"type": "array",
"items": {
"type": "string"
},
"description": "An array of image IDs."
},
"IsStarred": {
"type": "boolean",
"description": "Filter by favorite status."
},
"Status": {
"type": "string",
"description": "Filter by image status. Accepted values: open, locked.",
"enum": [
"open",
"locked"
]
},
"LabelIDs": {
"type": "array",
"items": {
"type": "integer"
},
"description": "An array of IDs representing labels associated with the image."
},
"Name": {
"type": "string",
"description": "The name of the image."
},
"PartialName": {
"type": "string",
"description": "Search by partial image name."
},
"Limit": {
"type": "integer",
"description": "The number of results returned per page. Default: 10, maximum: 1000."
},
"Offset": {
"type": "integer",
"description": "The index of the first object in the page."
},
"Sort": {
"type": "string",
"description": "Sort results by a property and select ascending (ASC) or descending (DESC) order."
}
}
},
"get_v1_labels_QueryParams": {
"type": "object",
"additionalProperties": false,
"properties": {
"Name": {
"type": "string",
"description": "Search by the name of the label. Only returns exact match."
},
"IDs": {
"type": "array",
"items": {
"type": "integer"
},
"description": "An array of label IDs."
},
"UsedFor": {
"type": "string",
"description": "Filter labels by type. Possible values: image, resource. Cannot retrieve both in one request. Default: resource.",
"enum": [
"image",
"resource"
]
},
"Limit": {
"type": "integer",
"description": "The number of results returned per page. Default: 10, maximum: 1000."
},
"Offset": {
"type": "integer",
"description": "The index of the first object in the page."
},
"Sort": {
"type": "string",
"description": "Sort results by a property. Available: Name. Default: ID ASC."
}
}
},
"get_v1_tokens_QueryParams": {
"type": "object",
"additionalProperties": false,
"properties": {
"Name": {
"type": "string",
"description": "Search by token name. Only returns exact match."
},
"Limit": {
"type": "integer",
"description": "The number of results returned per page. Default: 10, maximum: 1000."
},
"Offset": {
"type": "integer",
"description": "The index of the first object in the page."
},
"Sort": {
"type": "string",
"description": "Sort results by a property. Available: Name."
}
}
}
},
"responses": {
"204": {
"description": "No content found or expected to return."
},
"400": {
"description": "One or more parameters are missing or maybe misspelled (unknown resource or action)."
},
"401": {
"description": "You have specified an incorrect API Key / API Secret Key pair. You may be unauthorized to access the API or your API key may be inactive. Visit API keys Management section to check your keys."
},
"403": {
"description": "You are not authorized to access this resource."
},
"404": {
"description": "The resource with the specified ID you are trying to reach does not exist."
},
"429": {
"description": "Too many requests. You have exceeded the rate limit."
},
"500": {
"description": "An unexpected error occurred on the server. Please contact our support team, providing the error identifier (ErrorIdentifier) and we will do our best to help."
}
},
"securitySchemes": {
"basicAuth": {
"type": "http",
"description": "HTTPS Basic Auth using your API Key as username and Secret Key as password. See documentation at https://dev.mailjet.com/content/guides/authentication/",
"scheme": "basic"
},
"bearerAuth": {
"type": "http",
"description": "Bearer Token authentication using a token generated via the /v1/REST/tokens endpoint. Tokens carry permissions that may restrict access to certain resources. See documentation at https://dev.mailjet.com/content/guides/authentication/",
"scheme": "bearer"
}
}
},
"tags": [
{
"name": "Templates",
"x-displayName": "Content API Templates",
"description": "Email templates are a crucial component for sending consistent and personalized\nemails. These endpoints handle the creation, listing, retrieval, update and deletion\nof email templates. A template includes metadata such as name, edit mode, purposes,\nlabels and publication status. Creating a template is the first step — content is\nadded separately via the Template Contents endpoints."
},
{
"name": "Template Contents",
"description": "Template Contents endpoints manage the actual content of email templates — the HTML,\nMJML or plain text, along with headers like Subject and From. Content goes through\na lifecycle: Draft, Published and Autosave. Up to 5 versions per status are stored.\nUse these endpoints to create, list, update, publish, lock and unlock template content."
},
{
"name": "Images",
"description": "Image endpoints allow you to upload images to the Mailjet image gallery, retrieve\ntheir metadata and URLs, update metadata, upload thumbnails, and delete images.\nImages can be categorized with labels and marked as favorites. The maximum upload\nsize is 2MB per image."
},
{
"name": "Labels",
"description": "Labels are used to categorize your images or templates by assigning tags to them.\nEach label has a unique name, a color represented as a hexadecimal code, and a type\nindicating whether it is used for images or templates (resources)."
},
{
"name": "Tokens",
"description": "Token endpoints allow you to create, list and update Bearer Tokens for authenticating\nContent API requests. Tokens carry specific permissions that control access to\nresources such as templates, images and labels. Initial token creation requires\nBasic Auth."
}
],
"externalDocs": {
"url": "https://dev.mailjet.com/content/guides/",
"description": "Mailjet Content API documentation"
}
}