# Email Templates
## POST /workspaces/{workspaceId}/projects/{projectId}/html-emails
> Creates an html-email template and adds it to the project.
```json
{"openapi":"3.0.3","info":{"title":"Touchpoints","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"CreateTemplate":{"type":"object","required":["editor","defaultLocale"],"description":"Input fields for creating a new template.","additionalProperties":false,"properties":{"editor":{"$ref":"#/components/schemas/HtmlEmailEditor"},"defaultLocale":{"type":"string","format":"locale-bcp47"},"description":{"type":"string"},"useCase":{"$ref":"#/components/schemas/UseCase"},"libraryTemplateId":{"type":"string","description":"The ID of the template in the library. If this is set, the template will be created with pre-populated content from the library template.\n"}}},"HtmlEmailEditor":{"type":"string","title":"HtmlEmailEditor","description":"A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.\n","enum":["taxi-for-email","native","html","rich-text","native-agentic"]},"UseCase":{"type":"string","description":"The use case of this template.","enum":["marketing","marketingCustomUnsubscribe","transactional","other"],"nullable":true},"HtmlEmailTemplate":{"type":"object","title":"HtmlEmailTemplate","additionalProperties":false,"required":["id","projectId","status","editor","editorUrl","defaultLocale","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"A unique identifier for this template."},"projectId":{"type":"string","format":"uuid","description":"The ID of the project that this template belongs to."},"status":{"type":"string","description":"Same as project status.","enum":["draft","active","inactive","pending","pendingReview"]},"description":{"type":"string","description":"Description of this template."},"editor":{"$ref":"#/components/schemas/HtmlEmailEditor"},"editorUrl":{"type":"string","description":"The URL to the editor that created this template. The user should be redirected to this URL to edit the template.\n"},"defaultLocale":{"type":"string","format":"locale-bcp47"},"content":{"$ref":"#/components/schemas/ContentPerLocale"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp for this template."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of when this template was last updated."},"editorId":{"type":"string","format":"uuid","description":"The ID of the user that last edited this template.","nullable":true},"editorType":{"type":"string"},"publisherId":{"type":"string","format":"uuid","description":"The ID of the user that last published this template."},"publisherType":{"type":"string"},"useCase":{"$ref":"#/components/schemas/UseCase"},"clonedFrom":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.\n"},"metrics":{"type":"object","description":"Metrics for this template."},"reviewInfo":{"$ref":"#/components/schemas/common.review.info"}}},"ContentPerLocale":{"type":"object","nullable":true,"description":"A summary of the content of this template per locale (the object keys). Includes subject and parameters but not full HTML or attachments. Use the GET .../content/{locale} endpoint to retrieve full content. Content is not required until this template is activated.\n","additionalProperties":{"allOf":[{"$ref":"#/components/schemas/HtmlEmailContent"}]}},"HtmlEmailContent":{"type":"object","title":"HtmlEmailContent","properties":{"subject":{"type":"string","description":"The subject of the email."},"variables":{"deprecated":true,"$ref":"#/components/schemas/HtmlEmailVariables"},"parameters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/HtmlEmailParameter"}},"referencedForms":{"type":"array","description":"A list of form IDs that the content links the recipient to.","items":{"type":"string","format":"uuid"}},"attachments":{"type":"array","nullable":true,"description":"List of attachments for this email. Only returned when using the GET .../content/{locale} endpoint. Not included in the template-level content summary.\n","items":{"$ref":"#/components/schemas/Attachment"}}}},"HtmlEmailVariables":{"type":"object","title":"HtmlEmailVariables","nullable":true,"description":"Variables define dynamic content that can exist in either subject, plainHtml or liquidHtml fields. They are identified in the content by curly brackets. For example: \"Hey, {{userName}}\". The keys of this object are the variable names. The actual value of the variable are filled when sending this template to the final user.\n","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string","nullable":true,"description":"A short description of this variable's use, if the variable name is not already descriptive enough.\n"}}}},"HtmlEmailParameter":{"type":"object","title":"HtmlEmailParameter","additionalProperties":false,"properties":{"type":{"type":"string","enum":["string","number","boolean","object"]},"key":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"object","additionalProperties":true}]}}},"Attachment":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string"},"filename":{"type":"string"}}},"common.review.info":{"additionalProperties":false,"description":"Describe the status of an entity that is being reviewed through approval flows.","properties":{"approvalFlowId":{"description":"The ID of the approval flow that triggered the review.","format":"uuid","type":"string"},"approvalRunId":{"description":"The ID of the approval run through which this entity is reviewed.","format":"uuid","type":"string"},"currentStep":{"description":"The current step of the approval flow being evaluated.","type":"number"},"status":{"$ref":"#/components/schemas/common.review.status"}},"required":["approvalFlowId","approvalRunId","status","currentStep"],"type":"object"},"common.review.status":{"description":"The status of the review process.","enum":["pending","approved","rejected"],"type":"string"},"error.validation":{"additionalProperties":false,"description":"A validation error returned from the API. The `details` map keys are JSON paths\npointing into the request body / parameters; values are arrays of human-readable\nmessages describing each problem with that path.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Per-field validation messages keyed by JSON path.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"ValidationError","type":"object"}},"responses":{"error.response.invalid_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.validation"}}},"description":"The request contains invalid parameters or body fields."}}},"paths":{"/workspaces/{workspaceId}/projects/{projectId}/html-emails":{"post":{"summary":"Creates an html-email template and adds it to the project.","operationId":"createHtmlEmailTemplate","tags":["htmlemail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HtmlEmailTemplate"}}}},"422":{"$ref":"#/components/responses/error.response.invalid_request"}}}}}}
```
## GET /workspaces/{workspaceId}/projects/{projectId}/html-emails
> Lists html-email templates in a specific project, sorted in descending order.
```json
{"openapi":"3.0.3","info":{"title":"Touchpoints","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"parameters":{"pagination.param.limit":{"description":"Limits the number of results to return.","in":"query","name":"limit","schema":{"default":25,"maximum":100,"type":"integer"}},"pagination.param.pageToken":{"description":"The cursor that keeps track of the current position in the results.","in":"query","name":"pageToken","schema":{"type":"string"}},"pagination.param.reverse":{"description":"Reverses the order in which the results are returned.","in":"query","name":"reverse","schema":{"default":false,"type":"boolean"}}},"schemas":{"HtmlEmailList":{"type":"object","title":"HtmlEmailList","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/HtmlEmailTemplate"}}}},"HtmlEmailTemplate":{"type":"object","title":"HtmlEmailTemplate","additionalProperties":false,"required":["id","projectId","status","editor","editorUrl","defaultLocale","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"A unique identifier for this template."},"projectId":{"type":"string","format":"uuid","description":"The ID of the project that this template belongs to."},"status":{"type":"string","description":"Same as project status.","enum":["draft","active","inactive","pending","pendingReview"]},"description":{"type":"string","description":"Description of this template."},"editor":{"$ref":"#/components/schemas/HtmlEmailEditor"},"editorUrl":{"type":"string","description":"The URL to the editor that created this template. The user should be redirected to this URL to edit the template.\n"},"defaultLocale":{"type":"string","format":"locale-bcp47"},"content":{"$ref":"#/components/schemas/ContentPerLocale"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp for this template."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of when this template was last updated."},"editorId":{"type":"string","format":"uuid","description":"The ID of the user that last edited this template.","nullable":true},"editorType":{"type":"string"},"publisherId":{"type":"string","format":"uuid","description":"The ID of the user that last published this template."},"publisherType":{"type":"string"},"useCase":{"$ref":"#/components/schemas/UseCase"},"clonedFrom":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.\n"},"metrics":{"type":"object","description":"Metrics for this template."},"reviewInfo":{"$ref":"#/components/schemas/common.review.info"}}},"HtmlEmailEditor":{"type":"string","title":"HtmlEmailEditor","description":"A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.\n","enum":["taxi-for-email","native","html","rich-text","native-agentic"]},"ContentPerLocale":{"type":"object","nullable":true,"description":"A summary of the content of this template per locale (the object keys). Includes subject and parameters but not full HTML or attachments. Use the GET .../content/{locale} endpoint to retrieve full content. Content is not required until this template is activated.\n","additionalProperties":{"allOf":[{"$ref":"#/components/schemas/HtmlEmailContent"}]}},"HtmlEmailContent":{"type":"object","title":"HtmlEmailContent","properties":{"subject":{"type":"string","description":"The subject of the email."},"variables":{"deprecated":true,"$ref":"#/components/schemas/HtmlEmailVariables"},"parameters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/HtmlEmailParameter"}},"referencedForms":{"type":"array","description":"A list of form IDs that the content links the recipient to.","items":{"type":"string","format":"uuid"}},"attachments":{"type":"array","nullable":true,"description":"List of attachments for this email. Only returned when using the GET .../content/{locale} endpoint. Not included in the template-level content summary.\n","items":{"$ref":"#/components/schemas/Attachment"}}}},"HtmlEmailVariables":{"type":"object","title":"HtmlEmailVariables","nullable":true,"description":"Variables define dynamic content that can exist in either subject, plainHtml or liquidHtml fields. They are identified in the content by curly brackets. For example: \"Hey, {{userName}}\". The keys of this object are the variable names. The actual value of the variable are filled when sending this template to the final user.\n","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string","nullable":true,"description":"A short description of this variable's use, if the variable name is not already descriptive enough.\n"}}}},"HtmlEmailParameter":{"type":"object","title":"HtmlEmailParameter","additionalProperties":false,"properties":{"type":{"type":"string","enum":["string","number","boolean","object"]},"key":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"object","additionalProperties":true}]}}},"Attachment":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string"},"filename":{"type":"string"}}},"UseCase":{"type":"string","description":"The use case of this template.","enum":["marketing","marketingCustomUnsubscribe","transactional","other"],"nullable":true},"common.review.info":{"additionalProperties":false,"description":"Describe the status of an entity that is being reviewed through approval flows.","properties":{"approvalFlowId":{"description":"The ID of the approval flow that triggered the review.","format":"uuid","type":"string"},"approvalRunId":{"description":"The ID of the approval run through which this entity is reviewed.","format":"uuid","type":"string"},"currentStep":{"description":"The current step of the approval flow being evaluated.","type":"number"},"status":{"$ref":"#/components/schemas/common.review.status"}},"required":["approvalFlowId","approvalRunId","status","currentStep"],"type":"object"},"common.review.status":{"description":"The status of the review process.","enum":["pending","approved","rejected"],"type":"string"},"pagination":{"type":"object","properties":{"nextPageToken":{"type":"string","description":"The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display."}}},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}},"responses":{"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."}}},"paths":{"/workspaces/{workspaceId}/projects/{projectId}/html-emails":{"get":{"summary":"Lists html-email templates in a specific project, sorted in descending order.","operationId":"listHtmlEmailTemplates","tags":["htmlemail"],"parameters":[{"$ref":"#/components/parameters/pagination.param.limit"},{"$ref":"#/components/parameters/pagination.param.pageToken"},{"$ref":"#/components/parameters/pagination.param.reverse"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/HtmlEmailList"},{"$ref":"#/components/schemas/pagination"}]}}}},"404":{"$ref":"#/components/responses/error.response.not_found"}}}}}}
```
## GET /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}
> Returns a single html-email template with metadata and a content summary per locale (subject, parameters). To retrieve the full content including HTML and attachments, use the GET .../content/{locale} endpoint.
```json
{"openapi":"3.0.3","info":{"title":"Touchpoints","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"HtmlEmailTemplate":{"type":"object","title":"HtmlEmailTemplate","additionalProperties":false,"required":["id","projectId","status","editor","editorUrl","defaultLocale","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"A unique identifier for this template."},"projectId":{"type":"string","format":"uuid","description":"The ID of the project that this template belongs to."},"status":{"type":"string","description":"Same as project status.","enum":["draft","active","inactive","pending","pendingReview"]},"description":{"type":"string","description":"Description of this template."},"editor":{"$ref":"#/components/schemas/HtmlEmailEditor"},"editorUrl":{"type":"string","description":"The URL to the editor that created this template. The user should be redirected to this URL to edit the template.\n"},"defaultLocale":{"type":"string","format":"locale-bcp47"},"content":{"$ref":"#/components/schemas/ContentPerLocale"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp for this template."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of when this template was last updated."},"editorId":{"type":"string","format":"uuid","description":"The ID of the user that last edited this template.","nullable":true},"editorType":{"type":"string"},"publisherId":{"type":"string","format":"uuid","description":"The ID of the user that last published this template."},"publisherType":{"type":"string"},"useCase":{"$ref":"#/components/schemas/UseCase"},"clonedFrom":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.\n"},"metrics":{"type":"object","description":"Metrics for this template."},"reviewInfo":{"$ref":"#/components/schemas/common.review.info"}}},"HtmlEmailEditor":{"type":"string","title":"HtmlEmailEditor","description":"A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.\n","enum":["taxi-for-email","native","html","rich-text","native-agentic"]},"ContentPerLocale":{"type":"object","nullable":true,"description":"A summary of the content of this template per locale (the object keys). Includes subject and parameters but not full HTML or attachments. Use the GET .../content/{locale} endpoint to retrieve full content. Content is not required until this template is activated.\n","additionalProperties":{"allOf":[{"$ref":"#/components/schemas/HtmlEmailContent"}]}},"HtmlEmailContent":{"type":"object","title":"HtmlEmailContent","properties":{"subject":{"type":"string","description":"The subject of the email."},"variables":{"deprecated":true,"$ref":"#/components/schemas/HtmlEmailVariables"},"parameters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/HtmlEmailParameter"}},"referencedForms":{"type":"array","description":"A list of form IDs that the content links the recipient to.","items":{"type":"string","format":"uuid"}},"attachments":{"type":"array","nullable":true,"description":"List of attachments for this email. Only returned when using the GET .../content/{locale} endpoint. Not included in the template-level content summary.\n","items":{"$ref":"#/components/schemas/Attachment"}}}},"HtmlEmailVariables":{"type":"object","title":"HtmlEmailVariables","nullable":true,"description":"Variables define dynamic content that can exist in either subject, plainHtml or liquidHtml fields. They are identified in the content by curly brackets. For example: \"Hey, {{userName}}\". The keys of this object are the variable names. The actual value of the variable are filled when sending this template to the final user.\n","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string","nullable":true,"description":"A short description of this variable's use, if the variable name is not already descriptive enough.\n"}}}},"HtmlEmailParameter":{"type":"object","title":"HtmlEmailParameter","additionalProperties":false,"properties":{"type":{"type":"string","enum":["string","number","boolean","object"]},"key":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"object","additionalProperties":true}]}}},"Attachment":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string"},"filename":{"type":"string"}}},"UseCase":{"type":"string","description":"The use case of this template.","enum":["marketing","marketingCustomUnsubscribe","transactional","other"],"nullable":true},"common.review.info":{"additionalProperties":false,"description":"Describe the status of an entity that is being reviewed through approval flows.","properties":{"approvalFlowId":{"description":"The ID of the approval flow that triggered the review.","format":"uuid","type":"string"},"approvalRunId":{"description":"The ID of the approval run through which this entity is reviewed.","format":"uuid","type":"string"},"currentStep":{"description":"The current step of the approval flow being evaluated.","type":"number"},"status":{"$ref":"#/components/schemas/common.review.status"}},"required":["approvalFlowId","approvalRunId","status","currentStep"],"type":"object"},"common.review.status":{"description":"The status of the review process.","enum":["pending","approved","rejected"],"type":"string"},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}},"responses":{"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."}}},"paths":{"/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}":{"get":{"summary":"Returns a single html-email template with metadata and a content summary per locale (subject, parameters). To retrieve the full content including HTML and attachments, use the GET .../content/{locale} endpoint.\n","operationId":"getHtmlEmailTemplate","tags":["htmlemail"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HtmlEmailTemplate"}}}},"404":{"$ref":"#/components/responses/error.response.not_found"}}}}}}
```
## POST /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/activate
> Activates and makes that html-email template immutable to be used for campaigns and other parts of Nest. Inactivates the previous active version that belongs to the same project.
```json
{"openapi":"3.0.3","info":{"title":"Touchpoints","version":"v1"},"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"HtmlEmailTemplate":{"type":"object","title":"HtmlEmailTemplate","additionalProperties":false,"required":["id","projectId","status","editor","editorUrl","defaultLocale","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"A unique identifier for this template."},"projectId":{"type":"string","format":"uuid","description":"The ID of the project that this template belongs to."},"status":{"type":"string","description":"Same as project status.","enum":["draft","active","inactive","pending","pendingReview"]},"description":{"type":"string","description":"Description of this template."},"editor":{"$ref":"#/components/schemas/HtmlEmailEditor"},"editorUrl":{"type":"string","description":"The URL to the editor that created this template. The user should be redirected to this URL to edit the template.\n"},"defaultLocale":{"type":"string","format":"locale-bcp47"},"content":{"$ref":"#/components/schemas/ContentPerLocale"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp for this template."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of when this template was last updated."},"editorId":{"type":"string","format":"uuid","description":"The ID of the user that last edited this template.","nullable":true},"editorType":{"type":"string"},"publisherId":{"type":"string","format":"uuid","description":"The ID of the user that last published this template."},"publisherType":{"type":"string"},"useCase":{"$ref":"#/components/schemas/UseCase"},"clonedFrom":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.\n"},"metrics":{"type":"object","description":"Metrics for this template."},"reviewInfo":{"$ref":"#/components/schemas/common.review.info"}}},"HtmlEmailEditor":{"type":"string","title":"HtmlEmailEditor","description":"A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.\n","enum":["taxi-for-email","native","html","rich-text","native-agentic"]},"ContentPerLocale":{"type":"object","nullable":true,"description":"A summary of the content of this template per locale (the object keys). Includes subject and parameters but not full HTML or attachments. Use the GET .../content/{locale} endpoint to retrieve full content. Content is not required until this template is activated.\n","additionalProperties":{"allOf":[{"$ref":"#/components/schemas/HtmlEmailContent"}]}},"HtmlEmailContent":{"type":"object","title":"HtmlEmailContent","properties":{"subject":{"type":"string","description":"The subject of the email."},"variables":{"deprecated":true,"$ref":"#/components/schemas/HtmlEmailVariables"},"parameters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/HtmlEmailParameter"}},"referencedForms":{"type":"array","description":"A list of form IDs that the content links the recipient to.","items":{"type":"string","format":"uuid"}},"attachments":{"type":"array","nullable":true,"description":"List of attachments for this email. Only returned when using the GET .../content/{locale} endpoint. Not included in the template-level content summary.\n","items":{"$ref":"#/components/schemas/Attachment"}}}},"HtmlEmailVariables":{"type":"object","title":"HtmlEmailVariables","nullable":true,"description":"Variables define dynamic content that can exist in either subject, plainHtml or liquidHtml fields. They are identified in the content by curly brackets. For example: \"Hey, {{userName}}\". The keys of this object are the variable names. The actual value of the variable are filled when sending this template to the final user.\n","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string","nullable":true,"description":"A short description of this variable's use, if the variable name is not already descriptive enough.\n"}}}},"HtmlEmailParameter":{"type":"object","title":"HtmlEmailParameter","additionalProperties":false,"properties":{"type":{"type":"string","enum":["string","number","boolean","object"]},"key":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"object","additionalProperties":true}]}}},"Attachment":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string"},"filename":{"type":"string"}}},"UseCase":{"type":"string","description":"The use case of this template.","enum":["marketing","marketingCustomUnsubscribe","transactional","other"],"nullable":true},"common.review.info":{"additionalProperties":false,"description":"Describe the status of an entity that is being reviewed through approval flows.","properties":{"approvalFlowId":{"description":"The ID of the approval flow that triggered the review.","format":"uuid","type":"string"},"approvalRunId":{"description":"The ID of the approval run through which this entity is reviewed.","format":"uuid","type":"string"},"currentStep":{"description":"The current step of the approval flow being evaluated.","type":"number"},"status":{"$ref":"#/components/schemas/common.review.status"}},"required":["approvalFlowId","approvalRunId","status","currentStep"],"type":"object"},"common.review.status":{"description":"The status of the review process.","enum":["pending","approved","rejected"],"type":"string"},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"},"error.validation":{"additionalProperties":false,"description":"A validation error returned from the API. The `details` map keys are JSON paths\npointing into the request body / parameters; values are arrays of human-readable\nmessages describing each problem with that path.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Per-field validation messages keyed by JSON path.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"ValidationError","type":"object"}},"responses":{"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."},"error.response.invalid_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.validation"}}},"description":"The request contains invalid parameters or body fields."}}},"paths":{"/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/activate":{"post":{"summary":"Activates and makes that html-email template immutable to be used for campaigns and other parts of Nest. Inactivates the previous active version that belongs to the same project.\n","operationId":"activateHtmlEmailTemplate","responses":{"200":{"description":"Activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HtmlEmailTemplate"}}}},"404":{"$ref":"#/components/responses/error.response.not_found"},"422":{"$ref":"#/components/responses/error.response.invalid_request"}}}}}}
```
## POST /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/deactivate
> Deactivates an active template. Only a draft template can be deactivated at the moment. This is useful to deactivate an existing draft when a new draft cloned from an active/inactive template needs to be created, since there can be only one draft per project.
```json
{"openapi":"3.0.3","info":{"title":"Touchpoints","version":"v1"},"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"HtmlEmailTemplate":{"type":"object","title":"HtmlEmailTemplate","additionalProperties":false,"required":["id","projectId","status","editor","editorUrl","defaultLocale","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"A unique identifier for this template."},"projectId":{"type":"string","format":"uuid","description":"The ID of the project that this template belongs to."},"status":{"type":"string","description":"Same as project status.","enum":["draft","active","inactive","pending","pendingReview"]},"description":{"type":"string","description":"Description of this template."},"editor":{"$ref":"#/components/schemas/HtmlEmailEditor"},"editorUrl":{"type":"string","description":"The URL to the editor that created this template. The user should be redirected to this URL to edit the template.\n"},"defaultLocale":{"type":"string","format":"locale-bcp47"},"content":{"$ref":"#/components/schemas/ContentPerLocale"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp for this template."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of when this template was last updated."},"editorId":{"type":"string","format":"uuid","description":"The ID of the user that last edited this template.","nullable":true},"editorType":{"type":"string"},"publisherId":{"type":"string","format":"uuid","description":"The ID of the user that last published this template."},"publisherType":{"type":"string"},"useCase":{"$ref":"#/components/schemas/UseCase"},"clonedFrom":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.\n"},"metrics":{"type":"object","description":"Metrics for this template."},"reviewInfo":{"$ref":"#/components/schemas/common.review.info"}}},"HtmlEmailEditor":{"type":"string","title":"HtmlEmailEditor","description":"A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.\n","enum":["taxi-for-email","native","html","rich-text","native-agentic"]},"ContentPerLocale":{"type":"object","nullable":true,"description":"A summary of the content of this template per locale (the object keys). Includes subject and parameters but not full HTML or attachments. Use the GET .../content/{locale} endpoint to retrieve full content. Content is not required until this template is activated.\n","additionalProperties":{"allOf":[{"$ref":"#/components/schemas/HtmlEmailContent"}]}},"HtmlEmailContent":{"type":"object","title":"HtmlEmailContent","properties":{"subject":{"type":"string","description":"The subject of the email."},"variables":{"deprecated":true,"$ref":"#/components/schemas/HtmlEmailVariables"},"parameters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/HtmlEmailParameter"}},"referencedForms":{"type":"array","description":"A list of form IDs that the content links the recipient to.","items":{"type":"string","format":"uuid"}},"attachments":{"type":"array","nullable":true,"description":"List of attachments for this email. Only returned when using the GET .../content/{locale} endpoint. Not included in the template-level content summary.\n","items":{"$ref":"#/components/schemas/Attachment"}}}},"HtmlEmailVariables":{"type":"object","title":"HtmlEmailVariables","nullable":true,"description":"Variables define dynamic content that can exist in either subject, plainHtml or liquidHtml fields. They are identified in the content by curly brackets. For example: \"Hey, {{userName}}\". The keys of this object are the variable names. The actual value of the variable are filled when sending this template to the final user.\n","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string","nullable":true,"description":"A short description of this variable's use, if the variable name is not already descriptive enough.\n"}}}},"HtmlEmailParameter":{"type":"object","title":"HtmlEmailParameter","additionalProperties":false,"properties":{"type":{"type":"string","enum":["string","number","boolean","object"]},"key":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"object","additionalProperties":true}]}}},"Attachment":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string"},"filename":{"type":"string"}}},"UseCase":{"type":"string","description":"The use case of this template.","enum":["marketing","marketingCustomUnsubscribe","transactional","other"],"nullable":true},"common.review.info":{"additionalProperties":false,"description":"Describe the status of an entity that is being reviewed through approval flows.","properties":{"approvalFlowId":{"description":"The ID of the approval flow that triggered the review.","format":"uuid","type":"string"},"approvalRunId":{"description":"The ID of the approval run through which this entity is reviewed.","format":"uuid","type":"string"},"currentStep":{"description":"The current step of the approval flow being evaluated.","type":"number"},"status":{"$ref":"#/components/schemas/common.review.status"}},"required":["approvalFlowId","approvalRunId","status","currentStep"],"type":"object"},"common.review.status":{"description":"The status of the review process.","enum":["pending","approved","rejected"],"type":"string"},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}},"responses":{"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."}}},"paths":{"/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/deactivate":{"post":{"summary":"Deactivates an active template. Only a draft template can be deactivated at the moment. This is useful to deactivate an existing draft when a new draft cloned from an active/inactive template needs to be created, since there can be only one draft per project.\n","operationId":"deactivateHtmlEmailTemplate","responses":{"200":{"description":"Deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HtmlEmailTemplate"}}}},"404":{"$ref":"#/components/responses/error.response.not_found"}}}}}}
```
## POST /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/clone
> Clones an existing html-email template and adds it to the same project.
```json
{"openapi":"3.0.3","info":{"title":"Touchpoints","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"CloneTemplate":{"type":"object","description":"Input fields for cloning a template.","additionalProperties":false,"properties":{"toProjectId":{"type":"string","format":"uuid","description":"The ID of the project to which the template should be cloned. If not specified, the template will be cloned to the same project as the source template.\n","nullable":true}}},"HtmlEmailTemplate":{"type":"object","title":"HtmlEmailTemplate","additionalProperties":false,"required":["id","projectId","status","editor","editorUrl","defaultLocale","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"A unique identifier for this template."},"projectId":{"type":"string","format":"uuid","description":"The ID of the project that this template belongs to."},"status":{"type":"string","description":"Same as project status.","enum":["draft","active","inactive","pending","pendingReview"]},"description":{"type":"string","description":"Description of this template."},"editor":{"$ref":"#/components/schemas/HtmlEmailEditor"},"editorUrl":{"type":"string","description":"The URL to the editor that created this template. The user should be redirected to this URL to edit the template.\n"},"defaultLocale":{"type":"string","format":"locale-bcp47"},"content":{"$ref":"#/components/schemas/ContentPerLocale"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp for this template."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of when this template was last updated."},"editorId":{"type":"string","format":"uuid","description":"The ID of the user that last edited this template.","nullable":true},"editorType":{"type":"string"},"publisherId":{"type":"string","format":"uuid","description":"The ID of the user that last published this template."},"publisherType":{"type":"string"},"useCase":{"$ref":"#/components/schemas/UseCase"},"clonedFrom":{"type":"string","nullable":true,"format":"uuid","description":"The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.\n"},"metrics":{"type":"object","description":"Metrics for this template."},"reviewInfo":{"$ref":"#/components/schemas/common.review.info"}}},"HtmlEmailEditor":{"type":"string","title":"HtmlEmailEditor","description":"A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.\n","enum":["taxi-for-email","native","html","rich-text","native-agentic"]},"ContentPerLocale":{"type":"object","nullable":true,"description":"A summary of the content of this template per locale (the object keys). Includes subject and parameters but not full HTML or attachments. Use the GET .../content/{locale} endpoint to retrieve full content. Content is not required until this template is activated.\n","additionalProperties":{"allOf":[{"$ref":"#/components/schemas/HtmlEmailContent"}]}},"HtmlEmailContent":{"type":"object","title":"HtmlEmailContent","properties":{"subject":{"type":"string","description":"The subject of the email."},"variables":{"deprecated":true,"$ref":"#/components/schemas/HtmlEmailVariables"},"parameters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/HtmlEmailParameter"}},"referencedForms":{"type":"array","description":"A list of form IDs that the content links the recipient to.","items":{"type":"string","format":"uuid"}},"attachments":{"type":"array","nullable":true,"description":"List of attachments for this email. Only returned when using the GET .../content/{locale} endpoint. Not included in the template-level content summary.\n","items":{"$ref":"#/components/schemas/Attachment"}}}},"HtmlEmailVariables":{"type":"object","title":"HtmlEmailVariables","nullable":true,"description":"Variables define dynamic content that can exist in either subject, plainHtml or liquidHtml fields. They are identified in the content by curly brackets. For example: \"Hey, {{userName}}\". The keys of this object are the variable names. The actual value of the variable are filled when sending this template to the final user.\n","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string","nullable":true,"description":"A short description of this variable's use, if the variable name is not already descriptive enough.\n"}}}},"HtmlEmailParameter":{"type":"object","title":"HtmlEmailParameter","additionalProperties":false,"properties":{"type":{"type":"string","enum":["string","number","boolean","object"]},"key":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"object","additionalProperties":true}]}}},"Attachment":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string"},"filename":{"type":"string"}}},"UseCase":{"type":"string","description":"The use case of this template.","enum":["marketing","marketingCustomUnsubscribe","transactional","other"],"nullable":true},"common.review.info":{"additionalProperties":false,"description":"Describe the status of an entity that is being reviewed through approval flows.","properties":{"approvalFlowId":{"description":"The ID of the approval flow that triggered the review.","format":"uuid","type":"string"},"approvalRunId":{"description":"The ID of the approval run through which this entity is reviewed.","format":"uuid","type":"string"},"currentStep":{"description":"The current step of the approval flow being evaluated.","type":"number"},"status":{"$ref":"#/components/schemas/common.review.status"}},"required":["approvalFlowId","approvalRunId","status","currentStep"],"type":"object"},"common.review.status":{"description":"The status of the review process.","enum":["pending","approved","rejected"],"type":"string"},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}},"responses":{"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."}}},"paths":{"/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/clone":{"post":{"summary":"Clones an existing html-email template and adds it to the same project.","operationId":"cloneHtmlEmailTemplate","tags":["htmlemail"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloneTemplate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HtmlEmailTemplate"}}}},"404":{"$ref":"#/components/responses/error.response.not_found"}}}}}}
```
## GET /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}
> Retrieves content for a template in a specific locale.
```json
{"openapi":"3.0.3","info":{"title":"Touchpoints","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"FullContent":{"type":"object","allOf":[{"$ref":"#/components/schemas/HtmlEmailContent"},{"properties":{"plainHtml":{"nullable":true,"type":"string","description":"The rendered HTML content of this email template. This field is read-only and returned by the GET .../content/{locale} endpoint. To update HTML content, use the presigned upload URL and set rawFileName via the PATCH endpoint.\n"}}}]},"HtmlEmailContent":{"type":"object","title":"HtmlEmailContent","properties":{"subject":{"type":"string","description":"The subject of the email."},"variables":{"deprecated":true,"$ref":"#/components/schemas/HtmlEmailVariables"},"parameters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/HtmlEmailParameter"}},"referencedForms":{"type":"array","description":"A list of form IDs that the content links the recipient to.","items":{"type":"string","format":"uuid"}},"attachments":{"type":"array","nullable":true,"description":"List of attachments for this email. Only returned when using the GET .../content/{locale} endpoint. Not included in the template-level content summary.\n","items":{"$ref":"#/components/schemas/Attachment"}}}},"HtmlEmailVariables":{"type":"object","title":"HtmlEmailVariables","nullable":true,"description":"Variables define dynamic content that can exist in either subject, plainHtml or liquidHtml fields. They are identified in the content by curly brackets. For example: \"Hey, {{userName}}\". The keys of this object are the variable names. The actual value of the variable are filled when sending this template to the final user.\n","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string","nullable":true,"description":"A short description of this variable's use, if the variable name is not already descriptive enough.\n"}}}},"HtmlEmailParameter":{"type":"object","title":"HtmlEmailParameter","additionalProperties":false,"properties":{"type":{"type":"string","enum":["string","number","boolean","object"]},"key":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"object","additionalProperties":true}]}}},"Attachment":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string"},"filename":{"type":"string"}}},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}},"responses":{"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."}}},"paths":{"/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}":{"get":{"summary":"Retrieves content for a template in a specific locale.\n","operationId":"getHtmlEmailTemplateContent","tags":["htmlemail"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FullContent"}}}},"404":{"$ref":"#/components/responses/error.response.not_found"}}}}}}
```
## PATCH /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}
> Updates content for a template in a specific locale. For 'html' editor templates, HTML content is updated by uploading the HTML file via the presigned upload URL and then setting the rawFileName field. The plainHtml field is read-only and cannot be set directly through this endpoint.
```json
{"openapi":"3.0.3","info":{"title":"Touchpoints","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"schemas":{"HtmlEmailUpdateContent":{"type":"object","title":"HtmlEmailUpdateContent","additionalProperties":false,"properties":{"htmlType":{"type":"string","deprecated":true,"description":"Deprecated. This field is accepted but ignored by the server.\n","enum":["plainHtml","liquidHtml",""]},"subject":{"type":"string","description":"The subject of the email."},"variables":{"deprecated":true,"$ref":"#/components/schemas/HtmlEmailVariables"},"parameters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/HtmlEmailParameter"}},"attachments":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/Attachment"}},"rawFileName":{"type":"string","nullable":true,"description":"Only applicable to 'html' editor templates. Set this field after uploading a new HTML file via the presigned upload URL to update the template's HTML content. This is the only way to update HTML content; the plainHtml and liquidHtml fields are deprecated and ignored on this endpoint.\n"},"assetRefs":{"type":"object","nullable":true,"description":"Only applicable to 'html' editor templates. A map of asset reference keys to asset reference values. The keys should match a an img tag 'src' in an uploaded raw html file. The values should be an URL. assetRefs should only be specified if a new raw file has been uploaded for this template i.e. a rawFileName has been specified.\n","additionalProperties":{"type":"string","nullable":true}},"plainHtml":{"nullable":true,"deprecated":true,"type":"string","description":"Deprecated. This field is accepted but ignored by the server. To update HTML content, upload the HTML file via the presigned upload URL and set the rawFileName field instead.\n"},"liquidHtml":{"type":"object","deprecated":true,"nullable":true,"description":"Deprecated. This field is accepted but ignored by the server. To update HTML content, upload the HTML file via the presigned upload URL and set the rawFileName field instead.\n","additionalProperties":false,"properties":{"template":{"type":"string","description":"The liquid template contents to be compiled, along with the \"bindings\" field.\n"},"bindings":{"type":"object","description":"A JSON object specifying arbitrary properties to be used when compiling this liquid template.\n"}}},"referencedForms":{"type":"array","description":"A list of form IDs that the content links the recipient to.","items":{"type":"string","format":"uuid"}}}},"HtmlEmailVariables":{"type":"object","title":"HtmlEmailVariables","nullable":true,"description":"Variables define dynamic content that can exist in either subject, plainHtml or liquidHtml fields. They are identified in the content by curly brackets. For example: \"Hey, {{userName}}\". The keys of this object are the variable names. The actual value of the variable are filled when sending this template to the final user.\n","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string","nullable":true,"description":"A short description of this variable's use, if the variable name is not already descriptive enough.\n"}}}},"HtmlEmailParameter":{"type":"object","title":"HtmlEmailParameter","additionalProperties":false,"properties":{"type":{"type":"string","enum":["string","number","boolean","object"]},"key":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"object","additionalProperties":true}]}}},"Attachment":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string"},"filename":{"type":"string"}}},"FullContent":{"type":"object","allOf":[{"$ref":"#/components/schemas/HtmlEmailContent"},{"properties":{"plainHtml":{"nullable":true,"type":"string","description":"The rendered HTML content of this email template. This field is read-only and returned by the GET .../content/{locale} endpoint. To update HTML content, use the presigned upload URL and set rawFileName via the PATCH endpoint.\n"}}}]},"HtmlEmailContent":{"type":"object","title":"HtmlEmailContent","properties":{"subject":{"type":"string","description":"The subject of the email."},"variables":{"deprecated":true,"$ref":"#/components/schemas/HtmlEmailVariables"},"parameters":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/HtmlEmailParameter"}},"referencedForms":{"type":"array","description":"A list of form IDs that the content links the recipient to.","items":{"type":"string","format":"uuid"}},"attachments":{"type":"array","nullable":true,"description":"List of attachments for this email. Only returned when using the GET .../content/{locale} endpoint. Not included in the template-level content summary.\n","items":{"$ref":"#/components/schemas/Attachment"}}}},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"},"error.validation":{"additionalProperties":false,"description":"A validation error returned from the API. The `details` map keys are JSON paths\npointing into the request body / parameters; values are arrays of human-readable\nmessages describing each problem with that path.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Per-field validation messages keyed by JSON path.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"ValidationError","type":"object"}},"responses":{"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."},"error.response.invalid_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.validation"}}},"description":"The request contains invalid parameters or body fields."}}},"paths":{"/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}":{"patch":{"summary":"Updates content for a template in a specific locale. For 'html' editor templates, HTML content is updated by uploading the HTML file via the presigned upload URL and then setting the rawFileName field. The plainHtml field is read-only and cannot be set directly through this endpoint.\n","operationId":"patchHtmlEmailTemplateContent","tags":["htmlemail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HtmlEmailUpdateContent"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FullContent"}}}},"404":{"$ref":"#/components/responses/error.response.not_found"},"422":{"$ref":"#/components/responses/error.response.invalid_request"}}}}}}
```
## DELETE /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}
> Deletes content for a template in a specific locale.
```json
{"openapi":"3.0.3","info":{"title":"Touchpoints","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"responses":{"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."},"error.response.invalid_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.validation"}}},"description":"The request contains invalid parameters or body fields."}},"schemas":{"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"},"error.validation":{"additionalProperties":false,"description":"A validation error returned from the API. The `details` map keys are JSON paths\npointing into the request body / parameters; values are arrays of human-readable\nmessages describing each problem with that path.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Per-field validation messages keyed by JSON path.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"ValidationError","type":"object"}}},"paths":{"/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}":{"delete":{"summary":"Deletes content for a template in a specific locale.\n","operationId":"deleteHtmlEmailTemplateContent","tags":["htmlemail"],"responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/error.response.not_found"},"422":{"$ref":"#/components/responses/error.response.invalid_request"}}}}}}
```
## GET /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/render/{locale}
> Returns rendered HTML and variables to display a preview of an htmlEmail template for a specific locale.
```json
{"openapi":"3.0.3","info":{"title":"Touchpoints","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token","scheme":"AccessKey","type":"http"}},"responses":{"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."}},"schemas":{"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}}},"paths":{"/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/render/{locale}":{"get":{"summary":"Returns rendered HTML and variables to display a preview of an htmlEmail template for a specific locale.\n","operationId":"previewHtmlEmailTemplateForLocale","tags":["htmlemail"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["html"],"additionalProperties":false,"properties":{"html":{"type":"string"},"variables":{"type":"object","nullable":true,"additionalProperties":true}}}}}},"404":{"$ref":"#/components/responses/error.response.not_found"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.bird.com/api/touchpoints-api/api-reference/email-templates.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.