Creating HTML Email Templates
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:
Create a project – Set up an HTML email project to hold your templates
Create a template – Initialize a new template with basic settings
Add content – Upload your HTML and set the subject line
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}/projectsTo create a basic HTML email project:
Response
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
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:
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
For a simple HTML template, you only need to specify the editor type and default locale:
Response
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
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
Adding content to an html editor template is a two-part process: first you upload the HTML file, then you update the template metadata (subject, variables, attachments, etc.).
3a. Get a presigned upload URL
Request a presigned URL to upload your HTML file:
No request body is required (send {}).
Response
The response contains the upload URL along with form data fields that must be included in the upload request.
3b. Upload the HTML file
Upload your HTML content to the presigned URL as a multipart form POST. You must include all fields from uploadFormData as form fields, with the file field appended last:
Important: Use
POSTwith multipart form data — notPUTwith a raw body. TheuploadMethodfield in the response confirms this. AlluploadFormDatafields are required for S3 to authenticate and accept the upload.
Your HTML can include variables using the {{variableName}} syntax:
3c. Update the template content
After the upload completes, set the subject, variables, and other metadata. The uploaded HTML is automatically associated with the template locale — no file name reference is needed.
Important: You cannot set HTML content directly via
plainHtmlon this endpoint — it must be uploaded via the presigned URL. TheplainHtmlfield is read-only on the GET response.
Adding attachments
Include file attachments in the same PATCH request:
Each attachment requires:
url– The URL where the file is hostedfilename– The name shown to recipients
Mapping image assets (raw file upload)
If your HTML references images by local filenames (e.g. <img src="logo.png">) and you want to map them to CDN URLs, use the raw file upload endpoint instead:
This endpoint returns a fileName field in addition to the upload details. After uploading, pass rawFileName and assetRefs in the PATCH request:
Note:
assetRefsshould only be specified together withrawFileName.
Complete content example
Here's a full PATCH example combining subject, variables, and attachments:
Updating only the subject or variables
If you only need to update metadata without changing the HTML, just send the fields you want to update:
Step 4: Activate the template
Once your content is ready, activate the template to make it available for sending emails.
Request
No request body is required.
Response
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 repeating the upload-and-patch process with a different locale code.
Add German content
First, get a presigned upload URL for the German locale:
Upload the German HTML file to the returned uploadUrl using multipart form POST (as described in Step 3b), then patch the content:
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
This returns the template metadata and a content summary per locale (subject and parameters). It does not include the full HTML content or attachments.
Get full template content
To retrieve the full content for a specific locale, including the rendered HTML and attachments, use the content endpoint:
The plainHtml field in the response contains the complete HTML content of the template. This is useful for migrating templates between workspaces, backing up template content, and reviewing rendered output.
Note:
plainHtmlis a read-only field on this GET response. To update HTML content, use the presigned upload workflow described in Step 3.
Preview the template
To see how the template renders with example values:
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:
Retrieve the source template content – Call the GET content endpoint for each locale. Save the
plainHtml,subject,variables,attachments, andassetRefsfields.Create a project in the target workspace – Use the POST projects endpoint.
Create a template in the new project – Use the POST html-emails endpoint with the same
editoranddefaultLocale.Upload HTML and set content for each locale – For each locale: a. Get a presigned upload URL in the target workspace via the
.../content/{locale}/presigned-uploadendpoint. b. Save theplainHtmlfrom step 1 as an HTML file and upload it to the presigned URL using multipart form POST with alluploadFormDatafields. c. PATCH the content withsubject,variables, andattachments.Activate the template – Use the POST activate endpoint.
Managing templates
List all templates
Returns all templates in the project.
Update template metadata
To change the description or use case without modifying content:
Deactivate a template
To temporarily disable a template:
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:
Omit toProjectId to clone within the same project.
Delete content for a locale
To remove a specific language version:
Template status reference
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.
Last updated
Was this helpful?