Creating HTML Email Templates

Creating HTML Email Templates

This guide walks you through creating and managing HTML email templates using the Bird API. By the end, you'll have a fully functional email template ready to send.

Overview

Creating an HTML email template involves the following steps:

1. Create a project – Set up an HTML email project to hold your templates

2. Create a template – Initialize a new template with basic settings

3. Add content – Upload your HTML and define variables

4. Activate the template – Make it available for sending

Let's walk through each step.

---

Step 1: Create a project

Before you can create templates, you need an HTML email project to store them. Projects act as containers that organize your templates and define their type.

Request

POST /workspaces/{workspaceId}/projects

To create a basic HTML email project:

{
  "name": "Transactional Emails",
  "type": "htmlEmail"
}

Response

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "workspaceId": "ws-123",
  "name": "Transactional Emails",
  "type": "htmlEmail",
  "draftCount": 0,
  "activeCount": 0,
  "inactiveCount": 0,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

Save the id from the response – this is your projectId for the next steps.

Adding optional fields

You can include additional fields when creating the project:

{
  "name": "Marketing Campaigns",
  "description": "Email templates for marketing campaigns",
  "type": "htmlEmail",
  "suites": ["marketing", "automations"]
}

Field	Required	Description
name	No	Project name (max 100 characters)
description	No	Project description (max 300 characters)
type	Yes	Must be htmlEmail for email templates
suites	No	Categorization: marketing, service, payments, automations, developer

Alternative: Create project with initial template

You can also create a project and its first template in a single request:

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

{
  "name": "Order Notifications",
  "type": "htmlEmail",
  "templateEditor": "html",
  "templateDefaultLocale": "en",
  "templateDescription": "Order confirmation email",
  "templateUseCase": "transactional"
}

This approach saves an API call when you know you'll need a template immediately.

---

Step 2: Create a template

Once you have a project, you can create templates within it. Each project can contain multiple templates.

Request

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

For a simple HTML template, you only need to specify the editor type and default locale:

{
  "editor": "html",
  "defaultLocale": "en"
}

Response

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "projectId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "draft",
  "editor": "html",
  "defaultLocale": "en",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

The template is created in draft status. Save the id from the response – you'll need it for the next steps.

Adding optional fields

You can include additional fields when creating the template:

{
  "editor": "html",
  "defaultLocale": "en",
  "description": "Order confirmation email",
  "useCase": "transactional"
}

Field	Required	Description
editor	Yes	Set to html for raw HTML templates
defaultLocale	Yes	Default language code (e.g., en, de, fr)
description	No	A description to help identify the template
useCase	No	Classification: transactional, marketing, marketingCustomUnsubscribe, or other

The useCase field affects compliance requirements. Marketing emails require an unsubscribe link, while transactional emails do not.

---

Step 3: Add content

Now that you have a template, you need to add the actual email content. Content is stored per locale, so you can have different versions for different languages.

Request

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

Replace {templateId} with the ID from Step 2, and {locale} with the language code (e.g., en).

Here's a basic example with a subject line and HTML body:

{
  "subject": "Welcome to our service!",
  "plainHtml": "<!DOCTYPE html><html><head><meta charset=\"utf-8\"></head><body><h1>Welcome!</h1><p>Thank you for signing up.</p></body></html>"
}

Using variables

To personalize your emails, use variables with the {{variableName}} syntax. Define each variable with a description and example value:

{
  "subject": "Welcome, {{firstName}}!",
  "plainHtml": "<!DOCTYPE html><html><body><h1>Hello {{firstName}}</h1><p>Your order #{{orderId}} is confirmed.</p></body></html>",
  "variables": {
    "firstName": {
      "description": "Customer's first name",
      "example": "Jane"
    },
    "orderId": {
      "description": "Order reference number",
      "example": "ORD-12345"
    }
  }
}

The description helps team members understand each variable's purpose. The example value is used when previewing the template.

Adding attachments

To include file attachments with your email, use the attachments field:

{
  "subject": "Your invoice is ready",
  "plainHtml": "<!DOCTYPE html><html><body><p>Please find your invoice attached.</p></body></html>",
  "attachments": [
    {
      "url": "https://cdn.example.com/invoices/invoice-123.pdf",
      "filename": "invoice.pdf"
    }
  ]
}

Each attachment requires:

• url – The URL where the file is hosted

• filename – The name shown to recipients

Mapping image assets

If your HTML references images, use assetRefs to map local references to CDN URLs:

{
  "subject": "Check out our new products",
  "plainHtml": "<!DOCTYPE html><html><body><img src=\"logo.png\" alt=\"Logo\"><p>New arrivals are here!</p></body></html>",
  "assetRefs": {
    "logo.png": "https://cdn.example.com/assets/logo.png"
  }
}

Complete content example

Here's a full example combining all content options:

{
  "subject": "Order #{{orderId}} confirmed",
  "plainHtml": "<!DOCTYPE html><html><head><meta charset=\"utf-8\"></head><body><img src=\"header.png\" alt=\"Header\"><h1>Thanks, {{customerName}}!</h1><p>Your order #{{orderId}} for {{orderTotal}} has been confirmed.</p></body></html>",
  "variables": {
    "customerName": {
      "description": "Customer's full name",
      "example": "Jane Smith"
    },
    "orderId": {
      "description": "Order reference",
      "example": "ORD-98765"
    },
    "orderTotal": {
      "description": "Formatted order total",
      "example": "$149.99"
    }
  },
  "attachments": [
    {
      "url": "https://cdn.example.com/receipts/receipt.pdf",
      "filename": "receipt.pdf"
    }
  ],
  "assetRefs": {
    "header.png": "https://cdn.example.com/assets/email-header.png"
  }
}

---

Step 4: Activate the template

Once your content is ready, activate the template to make it available for sending emails.

Request

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

No request body is required.

Response

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "active",
  "editor": "html",
  "defaultLocale": "en",
  "description": "Order confirmation email",
  "useCase": "transactional",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:35:00Z"
}

The template status changes from draft to active. You can now use this template to send emails.

---

Adding multiple languages

Templates support multiple locales. After creating content for your default language, you can add additional languages by calling the content endpoint with different locale codes.

Add German content

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

{
  "subject": "Bestellung #{{orderId}} bestätigt",
  "plainHtml": "<!DOCTYPE html><html><body><h1>Danke, {{customerName}}!</h1><p>Ihre Bestellung #{{orderId}} wurde bestätigt.</p></body></html>",
  "variables": {
    "customerName": {
      "description": "Name des Kunden",
      "example": "Max Mustermann"
    },
    "orderId": {
      "description": "Bestellnummer",
      "example": "ORD-98765"
    }
  }
}

Common locale codes: en, en-US, en-GB, de, de-DE, fr, fr-FR, es, es-ES, it, nl, pt, pt-BR, ja, zh, ko.

---

Verifying your template

After activation, you can verify your template was created correctly.

Get template details

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

This returns the template metadata and content summaries for all locales.

Get template content (with HTML)

To retrieve the full content for a specific locale, including the actual HTML, use the content endpoint:

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

The plainHtml field contains the complete HTML content of the template. This is useful for migrating templates between workspaces, backing up template content, and programmatically editing templates.

Preview the template

To see how the template renders with example values:

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

This returns the rendered HTML with variables replaced by their example values.

---

Migrating templates between workspaces

To move a template from one workspace to another (e.g., sandbox to production), follow these steps:

1. Retrieve the source template content – Call the GET content endpoint and save the response, particularly the plainHtml, subject, variables, and attachments fields.

2. Create a project in the target workspace – Use the POST projects endpoint.

3. Create a template in the new project – Use the POST html-emails endpoint.

4. Add the content to the new template – Use the PATCH content endpoint with the data from step 1.

5. Activate the template – Use the POST activate endpoint.

---

Managing templates

List all templates

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

Returns all templates in the project.

Update template metadata

To change the description or use case without modifying content:

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

{
  "description": "Updated order confirmation",
  "useCase": "marketing"
}

Deactivate a template

To temporarily disable a template:

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

The status changes to inactive. You can reactivate it later using the activate endpoint.

Clone a template

To copy a template to the same or different project:

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

{
  "toProjectId": "target-project-id"
}

Omit toProjectId to clone within the same project.

Delete content for a locale

To remove a specific language version:

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

---

Template status reference

Status	Description
draft	Template is being edited and cannot be used for sending
active	Template is live and available for sending emails
inactive	Template has been deactivated
pending	Template is being processed
pendingReview	Template is awaiting review

---

Next steps

For a complete list of endpoints and parameters, see the API Reference.