Email Templates
POST
/workspaces/{workspaceId}/projects/{projectId}/html-emails
Creates an html-email template and adds it to the project.
Payload della richiesta
editor
string
obbligatorio
A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.
Possible values: taxi-for-email, native, html, rich-text, native-agentic
defaultLocale
string
obbligatorio
description
string
useCase
string
The use case of this template.
Possible values: marketing, marketingCustomUnsubscribe, transactional, other
libraryTemplateId
string
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.
Payload della risposta
id
string
obbligatorio
A unique identifier for this template.
projectId
string
obbligatorio
The ID of the project that this template belongs to.
status
string
obbligatorio
Same as project status.
Possible values: draft, active, inactive, pending, pendingReview
description
string
Description of this template.
editor
string
obbligatorio
A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.
Possible values: taxi-for-email, native, html, rich-text, native-agentic
editorUrl
string
obbligatorio
The URL to the editor that created this template. The user should be redirected to this URL to edit the template.
defaultLocale
string
obbligatorio
content
object
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.
createdAt
string
obbligatorio
Creation timestamp for this template.
updatedAt
string
obbligatorio
Timestamp of when this template was last updated.
editorId
string
The ID of the user that last edited this template.
editorType
string
publisherId
string
The ID of the user that last published this template.
publisherType
string
useCase
string
The use case of this template.
Possible values: marketing, marketingCustomUnsubscribe, transactional, other
clonedFrom
string
The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.
metrics
object
Metrics for this template.
reviewInfo
object
Describe the status of an entity that is being reviewed through approval flows.
Mostra attributi secondari
reviewInfo.approvalFlowId
string
obbligatorio
The ID of the approval flow that triggered the review.
reviewInfo.approvalRunId
string
obbligatorio
The ID of the approval run through which this entity is reviewed.
reviewInfo.currentStep
number
obbligatorio
The current step of the approval flow being evaluated.
reviewInfo.status
string
obbligatorio
The status of the review process.
Possible values: pending, approved, rejected
Esempio di codice
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/projects/{projectId}/html-emails' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'GET
/workspaces/{workspaceId}/projects/{projectId}/html-emails
Lists html-email templates in a specific project, sorted in descending order.
Parametri di query
limit
integer
Limits the number of results to return.
pageToken
string
The cursor that keeps track of the current position in the results.
reverse
boolean
Reverses the order in which the results are returned.
Payload della risposta
results
array of object
obbligatorio
Mostra attributi secondari
results.id
string
obbligatorio
A unique identifier for this template.
results.projectId
string
obbligatorio
The ID of the project that this template belongs to.
results.status
string
obbligatorio
Same as project status.
Possible values: draft, active, inactive, pending, pendingReview
results.description
string
Description of this template.
results.editor
string
obbligatorio
A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.
Possible values: taxi-for-email, native, html, rich-text, native-agentic
results.editorUrl
string
obbligatorio
The URL to the editor that created this template. The user should be redirected to this URL to edit the template.
results.defaultLocale
string
obbligatorio
results.content
object
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.
results.createdAt
string
obbligatorio
Creation timestamp for this template.
results.updatedAt
string
obbligatorio
Timestamp of when this template was last updated.
results.editorId
string
The ID of the user that last edited this template.
results.editorType
string
results.publisherId
string
The ID of the user that last published this template.
results.publisherType
string
results.useCase
string
The use case of this template.
Possible values: marketing, marketingCustomUnsubscribe, transactional, other
results.clonedFrom
string
The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.
results.metrics
object
Metrics for this template.
results.reviewInfo
object
Describe the status of an entity that is being reviewed through approval flows.
Mostra attributi secondari
results.reviewInfo.approvalFlowId
string
obbligatorio
The ID of the approval flow that triggered the review.
results.reviewInfo.approvalRunId
string
obbligatorio
The ID of the approval run through which this entity is reviewed.
results.reviewInfo.currentStep
number
obbligatorio
The current step of the approval flow being evaluated.
results.reviewInfo.status
string
obbligatorio
The status of the review process.
Possible values: pending, approved, rejected
nextPageToken
string
The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display.
Esempio di codice
curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/projects/{projectId}/html-emails' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'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.
Payload della risposta
id
string
obbligatorio
A unique identifier for this template.
projectId
string
obbligatorio
The ID of the project that this template belongs to.
status
string
obbligatorio
Same as project status.
Possible values: draft, active, inactive, pending, pendingReview
description
string
Description of this template.
editor
string
obbligatorio
A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.
Possible values: taxi-for-email, native, html, rich-text, native-agentic
editorUrl
string
obbligatorio
The URL to the editor that created this template. The user should be redirected to this URL to edit the template.
defaultLocale
string
obbligatorio
content
object
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.
createdAt
string
obbligatorio
Creation timestamp for this template.
updatedAt
string
obbligatorio
Timestamp of when this template was last updated.
editorId
string
The ID of the user that last edited this template.
editorType
string
publisherId
string
The ID of the user that last published this template.
publisherType
string
useCase
string
The use case of this template.
Possible values: marketing, marketingCustomUnsubscribe, transactional, other
clonedFrom
string
The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.
metrics
object
Metrics for this template.
reviewInfo
object
Describe the status of an entity that is being reviewed through approval flows.
Mostra attributi secondari
reviewInfo.approvalFlowId
string
obbligatorio
The ID of the approval flow that triggered the review.
reviewInfo.approvalRunId
string
obbligatorio
The ID of the approval run through which this entity is reviewed.
reviewInfo.currentStep
number
obbligatorio
The current step of the approval flow being evaluated.
reviewInfo.status
string
obbligatorio
The status of the review process.
Possible values: pending, approved, rejected
Esempio di codice
curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'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.
Payload della risposta
id
string
obbligatorio
A unique identifier for this template.
projectId
string
obbligatorio
The ID of the project that this template belongs to.
status
string
obbligatorio
Same as project status.
Possible values: draft, active, inactive, pending, pendingReview
description
string
Description of this template.
editor
string
obbligatorio
A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.
Possible values: taxi-for-email, native, html, rich-text, native-agentic
editorUrl
string
obbligatorio
The URL to the editor that created this template. The user should be redirected to this URL to edit the template.
defaultLocale
string
obbligatorio
content
object
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.
createdAt
string
obbligatorio
Creation timestamp for this template.
updatedAt
string
obbligatorio
Timestamp of when this template was last updated.
editorId
string
The ID of the user that last edited this template.
editorType
string
publisherId
string
The ID of the user that last published this template.
publisherType
string
useCase
string
The use case of this template.
Possible values: marketing, marketingCustomUnsubscribe, transactional, other
clonedFrom
string
The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.
metrics
object
Metrics for this template.
reviewInfo
object
Describe the status of an entity that is being reviewed through approval flows.
Mostra attributi secondari
reviewInfo.approvalFlowId
string
obbligatorio
The ID of the approval flow that triggered the review.
reviewInfo.approvalRunId
string
obbligatorio
The ID of the approval run through which this entity is reviewed.
reviewInfo.currentStep
number
obbligatorio
The current step of the approval flow being evaluated.
reviewInfo.status
string
obbligatorio
The status of the review process.
Possible values: pending, approved, rejected
Esempio di codice
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/activate' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'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.
Payload della risposta
id
string
obbligatorio
A unique identifier for this template.
projectId
string
obbligatorio
The ID of the project that this template belongs to.
status
string
obbligatorio
Same as project status.
Possible values: draft, active, inactive, pending, pendingReview
description
string
Description of this template.
editor
string
obbligatorio
A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.
Possible values: taxi-for-email, native, html, rich-text, native-agentic
editorUrl
string
obbligatorio
The URL to the editor that created this template. The user should be redirected to this URL to edit the template.
defaultLocale
string
obbligatorio
content
object
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.
createdAt
string
obbligatorio
Creation timestamp for this template.
updatedAt
string
obbligatorio
Timestamp of when this template was last updated.
editorId
string
The ID of the user that last edited this template.
editorType
string
publisherId
string
The ID of the user that last published this template.
publisherType
string
useCase
string
The use case of this template.
Possible values: marketing, marketingCustomUnsubscribe, transactional, other
clonedFrom
string
The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.
metrics
object
Metrics for this template.
reviewInfo
object
Describe the status of an entity that is being reviewed through approval flows.
Mostra attributi secondari
reviewInfo.approvalFlowId
string
obbligatorio
The ID of the approval flow that triggered the review.
reviewInfo.approvalRunId
string
obbligatorio
The ID of the approval run through which this entity is reviewed.
reviewInfo.currentStep
number
obbligatorio
The current step of the approval flow being evaluated.
reviewInfo.status
string
obbligatorio
The status of the review process.
Possible values: pending, approved, rejected
Esempio di codice
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/deactivate' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'POST
/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/clone
Clones an existing html-email template and adds it to the same project.
Payload della richiesta
toProjectId
string
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.
Payload della risposta
id
string
obbligatorio
A unique identifier for this template.
projectId
string
obbligatorio
The ID of the project that this template belongs to.
status
string
obbligatorio
Same as project status.
Possible values: draft, active, inactive, pending, pendingReview
description
string
Description of this template.
editor
string
obbligatorio
A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.
Possible values: taxi-for-email, native, html, rich-text, native-agentic
editorUrl
string
obbligatorio
The URL to the editor that created this template. The user should be redirected to this URL to edit the template.
defaultLocale
string
obbligatorio
content
object
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.
createdAt
string
obbligatorio
Creation timestamp for this template.
updatedAt
string
obbligatorio
Timestamp of when this template was last updated.
editorId
string
The ID of the user that last edited this template.
editorType
string
publisherId
string
The ID of the user that last published this template.
publisherType
string
useCase
string
The use case of this template.
Possible values: marketing, marketingCustomUnsubscribe, transactional, other
clonedFrom
string
The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.
metrics
object
Metrics for this template.
reviewInfo
object
Describe the status of an entity that is being reviewed through approval flows.
Mostra attributi secondari
reviewInfo.approvalFlowId
string
obbligatorio
The ID of the approval flow that triggered the review.
reviewInfo.approvalRunId
string
obbligatorio
The ID of the approval run through which this entity is reviewed.
reviewInfo.currentStep
number
obbligatorio
The current step of the approval flow being evaluated.
reviewInfo.status
string
obbligatorio
The status of the review process.
Possible values: pending, approved, rejected
Esempio di codice
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/clone' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'GET
/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}
Retrieves content for a template in a specific locale.
Payload della risposta
subject
string
The subject of the email.
variables
object
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.
parameters
array of object
Mostra attributi secondari
parameters.type
string
Possible values: string, number, boolean, object
parameters.key
string
parameters.value
string or number or boolean or object
referencedForms
array of string
A list of form IDs that the content links the recipient to.
attachments
array of object
List of attachments for this email. Only returned when using the GET .../content/{locale} endpoint. Not included in the template-level content summary.
Mostra attributi secondari
attachments.url
string
attachments.filename
string
plainHtml
string
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.
Esempio di codice
curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'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.
Payload della richiesta
htmlType
string
Deprecated. This field is accepted but ignored by the server.
Possible values: plainHtml, liquidHtml, ``
subject
string
The subject of the email.
variables
object
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.
parameters
array of object
Mostra parametri secondari
parameters.type
string
Possible values: string, number, boolean, object
parameters.key
string
parameters.value
string or number or boolean or object
attachments
array of object
Mostra parametri secondari
attachments.url
string
attachments.filename
string
rawFileName
string
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.
assetRefs
object
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.
plainHtml
string
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.
liquidHtml
object
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.
Mostra parametri secondari
liquidHtml.template
string
The liquid template contents to be compiled, along with the "bindings" field.
liquidHtml.bindings
object
A JSON object specifying arbitrary properties to be used when compiling this liquid template.
referencedForms
array of string
A list of form IDs that the content links the recipient to.
Payload della risposta
subject
string
The subject of the email.
variables
object
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.
parameters
array of object
Mostra attributi secondari
parameters.type
string
Possible values: string, number, boolean, object
parameters.key
string
parameters.value
string or number or boolean or object
referencedForms
array of string
A list of form IDs that the content links the recipient to.
attachments
array of object
List of attachments for this email. Only returned when using the GET .../content/{locale} endpoint. Not included in the template-level content summary.
Mostra attributi secondari
attachments.url
string
attachments.filename
string
plainHtml
string
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.
Esempio di codice
curl -X PATCH 'https://api.bird.com/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'DELETE
/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}
Deletes content for a template in a specific locale.
Esempio di codice
curl -X DELETE 'https://api.bird.com/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'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.
Payload della risposta
html
string
obbligatorio
variables
object
Esempio di codice
curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/render/{locale}' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'