--- title: "Create email template" method: POST path: "/api/v1/email-templates" tags: ["Email templates"] --- # Create email template `POST /api/v1/email-templates` ## Request - Base URL: `https://www.useboom.ai` - URL: `https://www.useboom.ai/api/v1/email-templates` - Auth: HTTP bearer Create an email template as a DRAFT, from either a block `document` (like the drag-and-drop builder) or raw `html`. The deliverable HTML and plain text are produced server-side; {{path}} variables in the subject and body resolve at send. Publish it with email_templates_update (status PUBLISHED) before a journey can send it. Minimal blocks example: `{ "name": "Recordatorio", "subject": "Hola {{customer.name}}", "document": { "blocks": [ { "type": "heading", "text": "Tu pago vence pronto" }, { "type": "text", "text": "Hola {{customer.name}}, ..." }, { "type": "button", "text": "Pagar", "href": "https://..." }, { "type": "footer", "text": "Empresa, dirección" } ] } }`. ## Request body - object - `name` string, required: Internal name, not shown to recipients. - `subject` string, required: Subject line; may contain {{path}} variables. - `document` object: Block-builder content. Send exactly one of `document` or `html`. - `body` object: Whole-email styles. - `preheader` string: Inbox preview text shown next to the subject. May contain {{path}} variables, e.g. {{customer.name}} (see journeys_message_variables for bindable paths). - `language` 'es' | 'en' | 'pt': Language the email is written in; defaults to es. - `textColor` string: CSS color, e.g. #111827 - `background` string: Canvas behind the email sheet. - `sheetBackground` string: CSS color, e.g. #111827 - `sheetRadius` number - `sheetPadding` number - `contentWidth` number - `contentAlign` 'left' | 'center' - `fontFamily` string - `fontWeight` '400' | '500' | '600' | '700' - `blocks` union[], required - union - object: A heading. - `id` string - `spacingBelow` number: Space after the block, px. - `type` 'heading', required - `text` string, required: Heading text. May contain {{path}} variables, e.g. {{customer.name}} (see journeys_message_variables for bindable paths). - `size` number - `color` string: CSS color, e.g. #111827 - `align` 'left' | 'center' | 'right' - object: A paragraph. - `id` string - `spacingBelow` number: Space after the block, px. - `type` 'text', required - `text` string, required: Paragraph text. A blank line starts a new paragraph, a single newline is a line break. May contain {{path}} variables, e.g. {{customer.name}} (see journeys_message_variables for bindable paths). - `size` number - `color` string: CSS color, e.g. #111827 - `align` 'left' | 'center' | 'right' - object: A call-to-action button. - `id` string - `spacingBelow` number: Space after the block, px. - `type` 'button', required - `text` string, required: Button label (single line). - `href` string, required: Destination URL. May be a variable, e.g. {{engagement.chatLink}} for the link that opens this run’s web chat. - `bg` string: CSS color, e.g. #111827 - `color` string: CSS color, e.g. #111827 - `align` 'left' | 'center' | 'right' - `radius` number - `corners` unknown[]: Per-corner radii [top-left, top-right, bottom-right, bottom-left] - unknown - object: An image. - `id` string - `spacingBelow` number: Space after the block, px. - `type` 'image', required - `src` string, uri, required: Public image URL (https). - `alt` string - `radius` number - `corners` unknown[]: Per-corner radii [top-left, top-right, bottom-right, bottom-left] - unknown - `width` number - `widthUnit` '%' | 'px': px suits a logo or icon; % scales with the email width. - `align` 'left' | 'center' | 'right' - `href` string: Optional link target; empty = not a link. - object: A horizontal rule. - `id` string - `spacingBelow` number: Space after the block, px. - `type` 'divider', required - `color` string: CSS color, e.g. #111827 - `thickness` number - `width` number: Percent of the container. - `align` 'left' | 'center' | 'right' - object: Vertical space. - `id` string - `spacingBelow` number: Space after the block, px. - `type` 'spacer', required - `height` number - object: An HTML snippet inside a block email. - `id` string - `spacingBelow` number: Space after the block, px. - `type` 'html', required - `source` string, required: Raw HTML for markup the other blocks cannot express. Sanitized at render: scripts, event handlers and external stylesheets are removed. May contain {{path}} variables, e.g. {{customer.name}} (see journeys_message_variables for bindable paths). - object: A row of social network icons. - `id` string - `spacingBelow` number: Space after the block, px. - `type` 'social', required - `links` object[], required - `id` string - `network` 'instagram' | 'facebook' | 'tiktok' | 'x' | 'linkedin' | 'youtube' | 'whatsapp', required - `url` string, uri, required - `style` 'brand' | 'dark' | 'light' - `size` number - `spacing` number - `align` 'left' | 'center' | 'right' - object: The email footer. Top level only. - `id` string - `spacingBelow` number: Space after the block, px. - `type` 'footer', required - `text` string, required: Footer copy, usually the company name and postal address. - `unsubscribeLabel` string: Text of the one-click unsubscribe link under the footer. Omit for the document language's default; empty string for no link (transactional email). - `color` string: CSS color, e.g. #111827 - `size` number - `align` 'left' | 'center' | 'right' - object: Side-by-side columns (1–4). A column holds leaf blocks only. - `id` string - `spacingBelow` number: Space after the block, px. - `type` 'columns', required - `columns` object[], required - `id` string - `ratio` number: Share of the row width; [1,2] = a third / two thirds. - `children` union[], required - … - `gap` number - `stackOnMobile` boolean - object: A framed card. May hold leaf blocks and one level of columns. - `id` string - `spacingBelow` number: Space after the block, px. - `type` 'container', required - `children` union[], required - union - … - `background` string: CSS color, e.g. #111827 - `padding` number - `radius` number - `corners` unknown[]: Per-corner radii [top-left, top-right, bottom-right, bottom-left] - unknown - `borderColor` string: CSS color, e.g. #111827 - `borderWidth` number - `html` string: Hand-written HTML (the template becomes an HTML template). Sanitized on save — scripts, event handlers and external stylesheets are removed and listed in `removed`. Variables use the same {{path}} grammar. - `fromSenderId` string, nullable: Sender id to send From. Must be on the verified domain (usableAsFrom in journeys_email_templates). Null/omitted = the org default. - `replyToSenderId` string, nullable: Sender id for Reply-To. Null/omitted = the org default. ## Response `201` Success - object - `template` object, required - `id` string, required - `name` string, required - `subject` string, required - `status` 'DRAFT' | 'PUBLISHED', required: Only a PUBLISHED template can be sent by a journey. - `authoringMode` 'BLOCKS' | 'CODE', required: BLOCKS = block builder; CODE = hand-written HTML. - `updatedAt` string, required: ISO timestamp. - `variables` object[], required: The {{path}} variables the subject and body use, one per path however it is spaced. - `key` string, required - `path` string, required - `document` unknown, required - `html` string, nullable, required: CODE templates: the HTML source as authored. Null for BLOCKS templates. - `renderedHtml` string, required: The deliverable HTML, with {{path}} variables still literal (they resolve at send). - `text` string, nullable, required: The plain-text part. - `fromSenderId` string, nullable, required - `replyToSenderId` string, nullable, required - `removed` string[], required: What the HTML sanitizer removed. Empty for block content. ## Other responses - `400`: Validation failed or the request cannot proceed. - `401`: Missing, malformed, or revoked API key. - `404`: The resource does not exist in this organization. - `409`: Conflicts with the current state (duplicates, wrong lifecycle state). - `422`: The request is well-formed but semantically invalid. - `429`: Rate limit exceeded — retry after `Retry-After`. - `500`: Internal server error. - `503`: Transient error — retry with a narrower request. ## Changes - **2026-11-03** `7c7a773b12ce`: 1 info - endpoint added [Operation history](https://skmtc.dev/useboom/apis/boom-api/changes/api/v1/email-templates/post.md) --- [API](https://skmtc.dev/useboom/apis/boom-api.md) - [All operations](https://skmtc.dev/useboom/apis/boom-api/llms.txt) - [OpenAPI document](https://skmtc.dev/useboom/apis/boom-api/revisions/d596d92ed092?raw)