Email Templates

Creates an html-email template and adds it to the project.

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstringRequired

projectIdstringRequired

Query parameters

metricsbooleanOptional

Include metrics in the response

Default: false

Body

application/json

Input fields for creating a new template.

editorstring · enumRequired

A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.

Possible values:

defaultLocalestring · locale-bcp47Required

descriptionstringOptional

useCasestring · enum · nullableOptional

The use case of this template.

Possible values:

libraryTemplateIdstringOptional

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.

Responses

201

Created

application/json

422

Invalid template

application/json

post

/workspaces/{workspaceId}/projects/{projectId}/html-emails

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/projects/{projectId}/html-emails HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 120

{
  "editor": "taxi-for-email",
  "defaultLocale": "text",
  "description": "text",
  "useCase": "marketing",
  "libraryTemplateId": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "draft",
  "description": "text",
  "editor": "taxi-for-email",
  "editorUrl": "text",
  "defaultLocale": "text",
  "content": {
    "ANY_ADDITIONAL_PROPERTY": {
      "subject": "text",
      "parameters": [
        {
          "type": "string",
          "key": "text",
          "value": "text"
        }
      ],
      "referencedForms": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "attachments": [
        {
          "url": "text",
          "filename": "text"
        }
      ]
    }
  },
  "createdAt": "2026-03-03T16:29:18.637Z",
  "updatedAt": "2026-03-03T16:29:18.637Z",
  "editorId": "123e4567-e89b-12d3-a456-426614174000",
  "editorType": "text",
  "publisherId": "123e4567-e89b-12d3-a456-426614174000",
  "publisherType": "text",
  "useCase": "marketing",
  "clonedFrom": "123e4567-e89b-12d3-a456-426614174000",
  "metrics": {},
  "reviewInfo": {
    "approvalFlowId": "123e4567-e89b-12d3-a456-426614174000",
    "approvalRunId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "currentStep": 1
  }
}

Lists html-email templates in a specific project, sorted in descending order.

get

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstringRequired

projectIdstringRequired

Query parameters

metricsbooleanOptional

Include metrics in the response

Default: false

limitinteger · min: 1 · max: 100Optional

Limits the project of results to return

Default: 10

pageTokenstring · max: 8000Optional

Pagination token that keeps of track of the current position in the list

reversebooleanOptional

Order in which to retrieve the results

Default: false

Responses

200

OK

application/json

404

Workspace or project not found

application/json

get

/workspaces/{workspaceId}/projects/{projectId}/html-emails

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/projects/{projectId}/html-emails HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "projectId": "123e4567-e89b-12d3-a456-426614174000",
      "status": "draft",
      "description": "text",
      "editor": "taxi-for-email",
      "editorUrl": "text",
      "defaultLocale": "text",
      "content": {
        "ANY_ADDITIONAL_PROPERTY": {
          "subject": "text",
          "parameters": [
            {
              "type": "string",
              "key": "text",
              "value": "text"
            }
          ],
          "referencedForms": [
            "123e4567-e89b-12d3-a456-426614174000"
          ],
          "attachments": [
            {
              "url": "text",
              "filename": "text"
            }
          ]
        }
      },
      "createdAt": "2026-03-03T16:29:18.637Z",
      "updatedAt": "2026-03-03T16:29:18.637Z",
      "editorId": "123e4567-e89b-12d3-a456-426614174000",
      "editorType": "text",
      "publisherId": "123e4567-e89b-12d3-a456-426614174000",
      "publisherType": "text",
      "useCase": "marketing",
      "clonedFrom": "123e4567-e89b-12d3-a456-426614174000",
      "metrics": {},
      "reviewInfo": {
        "approvalFlowId": "123e4567-e89b-12d3-a456-426614174000",
        "approvalRunId": "123e4567-e89b-12d3-a456-426614174000",
        "status": "pending",
        "currentStep": 1
      }
    }
  ],
  "nextPageToken": "text"
}

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.

get

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstringRequired

projectIdstringRequired

templateIdstringRequired

Responses

200

OK

application/json

idstring · uuidRequired

A unique identifier for this template.

projectIdstring · uuidRequired

The ID of the project that this template belongs to.

statusstring · enumRequired

Same as project status.

Possible values:

descriptionstringOptional

Description of this template.

editorstring · enumRequired

A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.

Possible values:

editorUrlstringRequired

The URL to the editor that created this template. The user should be redirected to this URL to edit the template.

defaultLocalestring · locale-bcp47Required

createdAtstring · date-timeRequired

Creation timestamp for this template.

updatedAtstring · date-timeRequired

Timestamp of when this template was last updated.

editorIdstring · uuid · nullableOptional

The ID of the user that last edited this template.

editorTypestringOptional

publisherIdstring · uuidOptional

The ID of the user that last published this template.

publisherTypestringOptional

useCasestring · enum · nullableOptional

The use case of this template.

Possible values:

clonedFromstring · uuid · nullableOptional

The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.

metricsobjectOptional

Metrics for this template.

404

Workspace, project or template not found

application/json

get

/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "draft",
  "description": "text",
  "editor": "taxi-for-email",
  "editorUrl": "text",
  "defaultLocale": "text",
  "content": {
    "ANY_ADDITIONAL_PROPERTY": {
      "subject": "text",
      "parameters": [
        {
          "type": "string",
          "key": "text",
          "value": "text"
        }
      ],
      "referencedForms": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "attachments": [
        {
          "url": "text",
          "filename": "text"
        }
      ]
    }
  },
  "createdAt": "2026-03-03T16:29:18.637Z",
  "updatedAt": "2026-03-03T16:29:18.637Z",
  "editorId": "123e4567-e89b-12d3-a456-426614174000",
  "editorType": "text",
  "publisherId": "123e4567-e89b-12d3-a456-426614174000",
  "publisherType": "text",
  "useCase": "marketing",
  "clonedFrom": "123e4567-e89b-12d3-a456-426614174000",
  "metrics": {},
  "reviewInfo": {
    "approvalFlowId": "123e4567-e89b-12d3-a456-426614174000",
    "approvalRunId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "currentStep": 1
  }
}

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.

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstringRequired

projectIdstringRequired

templateIdstringRequired

Responses

200

Activated

application/json

idstring · uuidRequired

A unique identifier for this template.

projectIdstring · uuidRequired

The ID of the project that this template belongs to.

statusstring · enumRequired

Same as project status.

Possible values:

descriptionstringOptional

Description of this template.

editorstring · enumRequired

A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.

Possible values:

editorUrlstringRequired

The URL to the editor that created this template. The user should be redirected to this URL to edit the template.

defaultLocalestring · locale-bcp47Required

createdAtstring · date-timeRequired

Creation timestamp for this template.

updatedAtstring · date-timeRequired

Timestamp of when this template was last updated.

editorIdstring · uuid · nullableOptional

The ID of the user that last edited this template.

editorTypestringOptional

publisherIdstring · uuidOptional

The ID of the user that last published this template.

publisherTypestringOptional

useCasestring · enum · nullableOptional

The use case of this template.

Possible values:

clonedFromstring · uuid · nullableOptional

The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.

metricsobjectOptional

Metrics for this template.

404

Workspace, project or template not found

application/json

422

Invalid template contents

application/json

post

/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/activate

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/activate HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "draft",
  "description": "text",
  "editor": "taxi-for-email",
  "editorUrl": "text",
  "defaultLocale": "text",
  "content": {
    "ANY_ADDITIONAL_PROPERTY": {
      "subject": "text",
      "parameters": [
        {
          "type": "string",
          "key": "text",
          "value": "text"
        }
      ],
      "referencedForms": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "attachments": [
        {
          "url": "text",
          "filename": "text"
        }
      ]
    }
  },
  "createdAt": "2026-03-03T16:29:18.637Z",
  "updatedAt": "2026-03-03T16:29:18.637Z",
  "editorId": "123e4567-e89b-12d3-a456-426614174000",
  "editorType": "text",
  "publisherId": "123e4567-e89b-12d3-a456-426614174000",
  "publisherType": "text",
  "useCase": "marketing",
  "clonedFrom": "123e4567-e89b-12d3-a456-426614174000",
  "metrics": {},
  "reviewInfo": {
    "approvalFlowId": "123e4567-e89b-12d3-a456-426614174000",
    "approvalRunId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "currentStep": 1
  }
}

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.

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstringRequired

projectIdstringRequired

templateIdstringRequired

Responses

200

Deactivated

application/json

idstring · uuidRequired

A unique identifier for this template.

projectIdstring · uuidRequired

The ID of the project that this template belongs to.

statusstring · enumRequired

Same as project status.

Possible values:

descriptionstringOptional

Description of this template.

editorstring · enumRequired

A string constant used to identify the editor that generated this content, and therefore to generate the editorUrl for this template.

Possible values:

editorUrlstringRequired

The URL to the editor that created this template. The user should be redirected to this URL to edit the template.

defaultLocalestring · locale-bcp47Required

createdAtstring · date-timeRequired

Creation timestamp for this template.

updatedAtstring · date-timeRequired

Timestamp of when this template was last updated.

editorIdstring · uuid · nullableOptional

The ID of the user that last edited this template.

editorTypestringOptional

publisherIdstring · uuidOptional

The ID of the user that last published this template.

publisherTypestringOptional

useCasestring · enum · nullableOptional

The use case of this template.

Possible values:

clonedFromstring · uuid · nullableOptional

The ID of the template that this template was cloned from. This field is only present if this template was cloned from another template.

metricsobjectOptional

Metrics for this template.

404

Workspace, project or template not found

application/json

post

/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/deactivate

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/deactivate HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "draft",
  "description": "text",
  "editor": "taxi-for-email",
  "editorUrl": "text",
  "defaultLocale": "text",
  "content": {
    "ANY_ADDITIONAL_PROPERTY": {
      "subject": "text",
      "parameters": [
        {
          "type": "string",
          "key": "text",
          "value": "text"
        }
      ],
      "referencedForms": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "attachments": [
        {
          "url": "text",
          "filename": "text"
        }
      ]
    }
  },
  "createdAt": "2026-03-03T16:29:18.637Z",
  "updatedAt": "2026-03-03T16:29:18.637Z",
  "editorId": "123e4567-e89b-12d3-a456-426614174000",
  "editorType": "text",
  "publisherId": "123e4567-e89b-12d3-a456-426614174000",
  "publisherType": "text",
  "useCase": "marketing",
  "clonedFrom": "123e4567-e89b-12d3-a456-426614174000",
  "metrics": {},
  "reviewInfo": {
    "approvalFlowId": "123e4567-e89b-12d3-a456-426614174000",
    "approvalRunId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "currentStep": 1
  }
}

Clones an existing html-email template and adds it to the same project.

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstringRequired

projectIdstringRequired

templateIdstringRequired

Body

application/json

Input fields for cloning a template.

toProjectIdstring · uuid · nullableOptional

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.

Responses

201

Created

application/json

404

Workspace, project or template not found

application/json

post

/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/clone

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/clone HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "toProjectId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "projectId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "draft",
  "description": "text",
  "editor": "taxi-for-email",
  "editorUrl": "text",
  "defaultLocale": "text",
  "content": {
    "ANY_ADDITIONAL_PROPERTY": {
      "subject": "text",
      "parameters": [
        {
          "type": "string",
          "key": "text",
          "value": "text"
        }
      ],
      "referencedForms": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "attachments": [
        {
          "url": "text",
          "filename": "text"
        }
      ]
    }
  },
  "createdAt": "2026-03-03T16:29:18.637Z",
  "updatedAt": "2026-03-03T16:29:18.637Z",
  "editorId": "123e4567-e89b-12d3-a456-426614174000",
  "editorType": "text",
  "publisherId": "123e4567-e89b-12d3-a456-426614174000",
  "publisherType": "text",
  "useCase": "marketing",
  "clonedFrom": "123e4567-e89b-12d3-a456-426614174000",
  "metrics": {},
  "reviewInfo": {
    "approvalFlowId": "123e4567-e89b-12d3-a456-426614174000",
    "approvalRunId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "currentStep": 1
  }
}

Retrieves content for a template in a specific locale.

get

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstringRequired

projectIdstringRequired

templateIdstringRequired

localestringRequired

Responses

200

OK

application/json

and

404

Workspace, project, template or locale not found

application/json

get

/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "subject": "text",
  "parameters": [
    {
      "type": "string",
      "key": "text",
      "value": "text"
    }
  ],
  "referencedForms": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "attachments": [
    {
      "url": "text",
      "filename": "text"
    }
  ],
  "plainHtml": "text"
}

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.

patch

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstringRequired

projectIdstringRequired

templateIdstringRequired

localestringRequired

Body

application/json

htmlTypestring · enumOptionalDeprecated

Deprecated. This field is accepted but ignored by the server.

Possible values:

subjectstringOptional

The subject of the email.

rawFileNamestring · nullableOptional

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.

plainHtmlstring · nullableOptionalDeprecated

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.

referencedFormsstring · uuid[]Optional

A list of form IDs that the content links the recipient to.

Responses

200

OK

application/json

and

404

Workspace, project, template or locale not found

application/json

422

Invalid request

application/json

patch

/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}

HTTPcURLJavaScriptPython

PATCH /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 255

{
  "subject": "text",
  "parameters": [
    {
      "type": "string",
      "key": "text",
      "value": "text"
    }
  ],
  "attachments": [
    {
      "url": "text",
      "filename": "text"
    }
  ],
  "rawFileName": "text",
  "assetRefs": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "referencedForms": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

{
  "subject": "text",
  "parameters": [
    {
      "type": "string",
      "key": "text",
      "value": "text"
    }
  ],
  "referencedForms": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "attachments": [
    {
      "url": "text",
      "filename": "text"
    }
  ],
  "plainHtml": "text"
}

Deletes content for a template in a specific locale.

delete

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstringRequired

projectIdstringRequired

templateIdstringRequired

localestringRequired

Responses

204

Deleted

404

Workspace, project, template or locale not found

application/json

422

Invalid request

application/json

delete

/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale}

HTTPcURLJavaScriptPython

DELETE /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/content/{locale} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

No content

Returns rendered HTML and variables to display a preview of an htmlEmail template for a specific locale.

get

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstringRequired

projectIdstringRequired

templateIdstringRequired

localestringRequired

Responses

200

OK

application/json

htmlstringRequired

404

Workspace, project or template or locale not found

application/json

get

/workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/render/{locale}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/projects/{projectId}/html-emails/{templateId}/render/{locale} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "html": "text",
  "variables": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}