Email Templates

creates an htmlEmail 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"
        }
      ],
      "attachments": [
        {
          "url": "text",
          "filename": "text"
        }
      ]
    }
  },
  "createdAt": "2026-02-04T11:16:44.383Z",
  "updatedAt": "2026-02-04T11:16:44.383Z",
  "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 htmlEmail templates in a specific project, sorts them 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"
            }
          ],
          "attachments": [
            {
              "url": "text",
              "filename": "text"
            }
          ]
        }
      },
      "createdAt": "2026-02-04T11:16:44.383Z",
      "updatedAt": "2026-02-04T11:16:44.383Z",
      "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.

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

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"
        }
      ],
      "attachments": [
        {
          "url": "text",
          "filename": "text"
        }
      ]
    }
  },
  "createdAt": "2026-02-04T11:16:44.383Z",
  "updatedAt": "2026-02-04T11:16:44.383Z",
  "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

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"
        }
      ],
      "attachments": [
        {
          "url": "text",
          "filename": "text"
        }
      ]
    }
  },
  "createdAt": "2026-02-04T11:16:44.383Z",
  "updatedAt": "2026-02-04T11:16:44.383Z",
  "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

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"
        }
      ],
      "attachments": [
        {
          "url": "text",
          "filename": "text"
        }
      ]
    }
  },
  "createdAt": "2026-02-04T11:16:44.383Z",
  "updatedAt": "2026-02-04T11:16:44.383Z",
  "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"
        }
      ],
      "attachments": [
        {
          "url": "text",
          "filename": "text"
        }
      ]
    }
  },
  "createdAt": "2026-02-04T11:16:44.383Z",
  "updatedAt": "2026-02-04T11:16:44.383Z",
  "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

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"
    }
  ],
  "attachments": [
    {
      "url": "text",
      "filename": "text"
    }
  ]
}

Retrieves content for a template in a specific locale.

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

and

Responses

200

OK

application/json

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"
    }
  ],
  "attachments": [
    {
      "url": "text",
      "filename": "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

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"
  }
}