{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid Templates API", "summary": "The Twilio SendGrid Templates API allows you to create and manage email templates to be delivered with SendGrid's sending APIs.", "description": "The Twilio SendGrid Templates API allows you to create and manage email templates to be delivered with SendGrid's sending APIs. The templates you create will be available using a template ID that is passed to our sending APIs as part of the request. Each template may then have multiple versions associated with it. Whichever version is set as \"active\" at the time of the request will be sent to your recipients. This system allows you to update a single template's look and feel entirely without modifying your requests to our Mail Send API. For example, you could have a single template for welcome emails. That welcome template could then have a version for each season of the year that's themed appropriately and marked as active during the appropriate season. The template ID passed to our sending APIs never needs to change; you can just modify which version is active.\n\nThis API provides operations to create and manage your templates as well as their versions.\n\nEach user can create up to 300 different templates. Templates are specific to accounts and Subusers. Templates created on a parent account will not be accessible from the Subusers' accounts.", "termsOfService": "https://www.twilio.com/legal/tos", "contact": { "name": "Twilio SendGrid Support", "url": "https://support.sendgrid.com/hc/en-us" }, "license": { "name": "MIT", "url": "https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE" }, "version": "1.0.0", "x-sendgrid": { "libraryPackage": "templates" } }, "servers": [ { "url": "https://api.sendgrid.com", "description": "for global users and subusers" }, { "url": "https://api.eu.sendgrid.com", "description": "for EU regional subusers" } ], "paths": { "/v3/templates": { "post": { "operationId": "CreateTemplate", "summary": "Create a transactional template.", "tags": [ "Templates" ], "description": "**This endpoint allows you to create a transactional template.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the new transactional template.", "maxLength": 100 }, "generation": { "type": "string", "description": "Defines whether the template supports dynamic replacement.", "default": "legacy", "$ref": "#/components/schemas/Generation" } }, "required": [ "name" ], "example": { "name": "example_name", "generation": "dynamic" } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalTemplate" }, "examples": { "response": { "value": { "id": "733ba07f-ead1-41fc-933a-3976baa23716", "name": "example_name", "generation": "legacy", "updated_at": "2021-04-28 13:12:46", "versions": [] } } } } } } } }, "get": { "operationId": "ListTemplate", "summary": "Retrieve paged transactional templates.", "tags": [ "Templates" ], "description": "**This endpoint allows you to retrieve all transactional templates.**", "parameters": [ { "name": "generations", "in": "query", "description": "Comma-delimited list specifying which generations of templates to return. Options are `legacy`, `dynamic` or `legacy,dynamic`.", "required": false, "schema": { "type": "string", "default": "legacy", "$ref": "#/components/schemas/Generations" } }, { "name": "page_size", "in": "query", "description": "The number of templates to be returned in each page of results", "required": true, "schema": { "type": "number", "minimum": 1, "maximum": 200 } }, { "name": "page_token", "in": "query", "description": "A token corresponding to a specific page of results, as provided by metadata", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "description": "", "items": { "$ref": "#/components/schemas/TransactionalTemplatesTemplateLean" } }, "_metadata": { "$ref": "#/components/schemas/Metadata" } } }, "examples": { "response": { "value": { "result": [ { "id": "fae7c985-eb92-4b47-9987-28ec29dbc698", "name": "example_name", "generation": "legacy", "updated_at": "2020-11-12 12:00:09", "versions": [] } ], "_metadata": { "self": "https://api.sendgrid.com/v3/templates", "count": 1 } } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } } } } } }, "/v3/templates/{template_id}": { "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "DuplicateTemplate", "summary": "Duplicate a transactional template.", "tags": [ "Templates" ], "description": "**This endpoint allows you to duplicate a transactional template.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the new transactional template.", "maxLength": 100 } }, "example": { "name": "example_name" } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalTemplate" }, "examples": { "response": { "value": { "id": "733ba07f-ead1-41fc-933a-3976baa23716", "name": "example_name", "generation": "dynamic", "updated_at": "2020-12-12 58:26:65", "versions": [] } } } } } } } }, "get": { "operationId": "GetTemplate", "summary": "Retrieve a single transactional template.", "tags": [ "Templates" ], "description": "**This endpoint allows you to retrieve a single transactional template.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalTemplate" }, "examples": { "response": { "value": { "id": "40da60e6-66f3-4223-9406-ba58b7f55a62", "name": "Duis in dolor", "generation": "legacy", "updated_at": "2020-12-12 58:26:65", "versions": [] } } } } } } } }, "patch": { "operationId": "UpdateTemplate", "summary": "Edit a transactional template.", "tags": [ "Templates" ], "description": "**This endpoint allows you to edit the name of a transactional template.**\n\nTo edit the template itself, [create a new transactional template version](https://docs.sendgrid.com/api-reference/transactional-templates-versions/create-a-new-transactional-template-version).", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the transactional template.", "maxLength": 100 } }, "example": { "name": "new_example_name" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalTemplate" }, "examples": { "response": { "value": { "id": "733ba07f-ead1-41fc-933a-3976baa23716", "name": "new_example_name", "generation": "legacy", "updated_at": "2021-04-28 13:12:46", "versions": [] } } } } } } } }, "delete": { "operationId": "DeleteTemplate", "summary": "Delete a template.", "tags": [ "Templates" ], "description": "**This endpoint allows you to delete a transactional template.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "204": { "description": "" } } } }, "/v3/templates/{template_id}/versions": { "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "CreateTemplateVersion", "summary": "Create a new transactional template version.", "tags": [ "Templates Versions" ], "description": "**This endpoint allows you to create a new version of a template.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "$ref": "#/components/requestBodies/PostPatchTransactionalTemplateVersion" }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalTemplateVersionOutput" }, "examples": { "response": { "value": { "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", "active": 1, "name": "example_version_name", "html_content": "<%body%>", "plain_content": "<%body%>", "generate_plain_content": true, "subject": "<%subject%>", "updated_at": "2019-03-13 18:56:33", "editor": "code" } } } } } } } } }, "/v3/templates/{template_id}/versions/{version_id}": { "parameters": [ { "name": "template_id", "in": "path", "description": " The ID of the original template", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version_id", "in": "path", "description": "The ID of the template version", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "GetTemplateVersion", "summary": "Retrieve a specific transactional template version.", "tags": [ "Templates Versions" ], "description": "**This endpoint allows you to retrieve a specific version of a template.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalTemplateVersionOutput" }, "examples": { "response": { "value": { "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", "active": 1, "name": "example_version_name", "html_content": "<%body%>", "plain_content": "<%body%>", "generate_plain_content": true, "subject": "<%subject%>", "updated_at": "2019-03-13 18:56:33", "editor": "code" } } } } } } } }, "patch": { "operationId": "UpdateTemplateVersion", "summary": "Edit a transactional template version.", "tags": [ "Templates Versions" ], "description": "**This endpoint allows you to edit the content of your template version.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "$ref": "#/components/requestBodies/PostPatchTransactionalTemplateVersion" }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalTemplateVersionOutput" }, "examples": { "response": { "value": { "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", "active": 1, "name": "example_version_name", "html_content": "<%body%>", "plain_content": "<%body%>", "generate_plain_content": true, "subject": "<%subject%>", "updated_at": "2019-03-13 18:56:33", "editor": "code" } } } } } } } }, "delete": { "operationId": "DeleteTemplateVersion", "summary": "Delete a transactional template version.", "tags": [ "Templates Versions" ], "description": "**This endpoint allows you to delete a transactional template version.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "204": { "description": "" } } } }, "/v3/templates/{template_id}/versions/{version_id}/activate": { "parameters": [ { "name": "template_id", "in": "path", "description": "The ID of the original template", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version_id", "in": "path", "description": "The ID of the template version", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "ActivateTemplateVersion", "summary": "Activate a transactional template version.", "tags": [ "Templates Versions" ], "description": "**This endpoint allows you to activate a version of one of your templates.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalTemplateVersionOutput" }, "examples": { "response": { "value": { "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", "active": 1, "name": "example_version_name", "html_content": "<%body%>", "plain_content": "<%body%>", "generate_plain_content": true, "subject": "<%subject%>", "updated_at": "2019-03-13 18:56:33", "editor": "code" } } } } } } } } } }, "components": { "schemas": { "TransactionalTemplate": { "title": "Transactional Templates: Template", "example": { "id": "33feeff2-5069-43fe-8853-428651e5be79", "name": "example_name", "updated_at": "2021-04-28 13:12:46", "warning": { "message": "Sample warning message" }, "generation": "legacy" }, "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the transactional template.", "minLength": 36, "maxLength": 36, "format": "uuid" }, "name": { "type": "string", "description": "The name for the transactional template.", "maxLength": 100 }, "generation": { "type": "string", "description": "Defines the generation of the template.", "$ref": "#/components/schemas/Generation1" }, "updated_at": { "type": "string", "description": "The date and time that this transactional template version was updated.", "pattern": "^(\\d{4}-\\d{2}-\\d{2}) ((\\d{2}):(\\d{2}):(\\d{2}))$" }, "versions": { "type": "array", "description": "The different versions of this transactional template.", "items": { "$ref": "#/components/schemas/TransactionalTemplatesVersionOutputLean" } }, "warning": { "$ref": "#/components/schemas/TransactionalTemplateWarning" } }, "required": [ "generation", "id", "name", "updated_at" ] }, "TransactionalTemplateVersionOutput": { "title": "Transactional Templates: Version Output", "type": "object", "properties": { "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionalTemplateWarning" } }, "active": { "type": "integer", "description": "Set the version as the active version associated with the template. Only one version of a template can be active. The first version created for a template will automatically be set to Active.", "$ref": "#/components/schemas/Active1" }, "name": { "type": "string", "description": "Name of the transactional template version.", "maxLength": 100 }, "html_content": { "type": "string", "description": "The HTML content of the Design." }, "plain_content": { "type": "string", "description": "Plain text content of the Design." }, "generate_plain_content": { "type": "boolean", "description": "If true, plain_content is always generated from html_content. If false, plain_content is not altered.", "default": true }, "subject": { "type": "string", "description": "Subject of the new transactional template version.", "maxLength": 255 }, "editor": { "type": "string", "description": "The editor used in the UI.", "$ref": "#/components/schemas/Editor1" }, "test_data": { "type": "string", "description": "For dynamic templates only, the mock json data that will be used for template preview and test sends." }, "id": { "type": "string", "description": "ID of the transactional template version.", "format": "uuid" }, "template_id": { "type": "string", "description": "ID of the transactional template." }, "updated_at": { "type": "string", "description": "The date and time that this transactional template version was updated." }, "thumbnail_url": { "type": "string", "description": "A Thumbnail preview of the template's html content." } }, "required": [ "name", "subject" ] }, "TransactionalTemplateVersionCreate": { "title": "Transactional Templates: Version Create", "type": "object", "properties": { "active": { "type": "integer", "description": "Set the version as the active version associated with the template (0 is inactive, 1 is active). Only one version of a template can be active. The first version created for a template will automatically be set to Active.", "$ref": "#/components/schemas/Active" }, "name": { "type": "string", "description": "Name of the transactional template version.", "maxLength": 100 }, "html_content": { "type": "string", "description": "The HTML content of the version. Maximum of 1048576 bytes allowed.", "maxLength": 1048576 }, "plain_content": { "type": "string", "description": "Text/plain content of the transactional template version. Maximum of 1048576 bytes allowed.", "maxLength": 1048576, "default": "" }, "generate_plain_content": { "type": "boolean", "description": "If true, plain_content is always generated from html_content. If false, plain_content is not altered.", "default": true }, "subject": { "type": "string", "description": "Subject of the new transactional template version.", "maxLength": 255 }, "editor": { "type": "string", "description": "The editor used in the UI.", "$ref": "#/components/schemas/Editor" }, "test_data": { "type": "string", "description": "For dynamic templates only, the mock json data that will be used for template preview and test sends." } }, "required": [ "name", "subject" ], "example": { "template_id": "Excepteur Ut qui", "active": 1, "name": "pariatur non incididunt commodo", "html_content": "dolor", "generate_plain_content": false, "subject": "aliquip nulla Ut", "editor": "design", "plain_content": "labore dolore" } }, "TransactionalTemplatesVersionOutputLean": { "title": "Transactional Templates: Version Output Lean", "type": "object", "properties": { "id": { "type": "string", "description": "ID of the transactional template version.", "format": "uuid" }, "template_id": { "type": "string", "description": "ID of the transactional template." }, "active": { "type": "integer", "description": "Set the version as the active version associated with the template. Only one version of a template can be active. The first version created for a template will automatically be set to Active.", "$ref": "#/components/schemas/Active1" }, "name": { "type": "string", "description": "Name of the transactional template version.", "maxLength": 100 }, "subject": { "type": "string", "description": "Subject of the new transactional template version.", "maxLength": 255 }, "updated_at": { "type": "string", "description": "The date and time that this transactional template version was updated." }, "generate_plain_content": { "type": "boolean", "description": "If true, plain_content is always generated from html_content. If false, plain_content is not altered.", "default": true }, "html_content": { "type": "string", "description": "The HTML content of the Design." }, "plain_content": { "type": "string", "description": "Plain text content of the Design." }, "editor": { "type": "string", "description": "The editor used in the UI.", "$ref": "#/components/schemas/Editor1" }, "thumbnail_url": { "type": "string", "description": "A Thumbnail preview of the template's html content." } } }, "TransactionalTemplatesTemplateLean": { "title": "Transactional Templates: Template Lean", "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the transactional template.", "minLength": 36, "maxLength": 36, "format": "uuid" }, "name": { "type": "string", "description": "The name for the transactional template.", "maxLength": 100 }, "generation": { "type": "string", "description": "Defines the generation of the template.", "$ref": "#/components/schemas/Generation1" }, "updated_at": { "type": "string", "description": "The date and time that this transactional template version was updated.", "pattern": "^(\\d{4}-\\d{2}-\\d{2}) ((\\d{2}):(\\d{2}):(\\d{2}))$" }, "versions": { "type": "array", "description": "The different versions of this transactional template.", "items": { "$ref": "#/components/schemas/TransactionalTemplatesVersionOutputLean" } } }, "required": [ "id", "name", "generation", "updated_at" ], "example": { "id": "0c314114-a2b7-4523-8cbc-a293d7d19007", "name": "example_name", "generation": "legacy", "updated_at": "2021-04-28 13:12:46", "versions": [] } }, "TransactionalTemplateWarning": { "title": "Warning", "type": "object", "properties": { "message": { "type": "string", "description": "Warning message for the user" } }, "example": { "message": "A sample warning message." } }, "Metadata": { "title": "_metadata", "type": "object", "properties": { "prev": { "type": "string", "format": "uri" }, "self": { "type": "string", "format": "uri" }, "next": { "type": "string", "format": "uri" }, "count": { "type": "integer", "minimum": 0 } } }, "Generation": { "type": "string", "enum": [ "legacy", "dynamic" ] }, "Generations": { "type": "string", "enum": [ "legacy", "dynamic", "legacy,dynamic" ] }, "Active": { "type": "integer", "enum": [ 0, 1 ] }, "Editor": { "type": "string", "enum": [ "code", "design" ] }, "Active1": { "type": "integer", "enum": [ 0, 1 ] }, "Editor1": { "type": "string", "enum": [ "code", "design" ] }, "Generation1": { "type": "string", "enum": [ "legacy", "dynamic" ] } }, "responses": {}, "parameters": { "OnBehalfOf": { "name": "on-behalf-of", "in": "header", "description": "The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be \"account-id\" followed by the customer account's ID (e.g., `on-behalf-of: account-id `). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: `). See [**On Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.", "required": false, "schema": { "type": "string" } } }, "examples": {}, "requestBodies": { "PostPatchTransactionalTemplateVersion": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionalTemplateVersionCreate" } } } } }, "headers": {}, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Twilio SendGrid requires you to authenticate with its APIs using an API key. The API key must be sent as a bearer token in the Authorization header." } } }, "tags": [ { "name": "Templates", "description": "Twilio SendGrid Templates API" }, { "name": "Templates Versions", "description": "Twilio SendGrid Templates API: Versions operations" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }