---
title: "Create a triggered email"
method: POST
path: "/v1/projectId/{projectId}/triggered-emails"
tags: ["Triggered Emails"]
---

# Create a triggered email

`POST /v1/projectId/{projectId}/triggered-emails`

## Request

- Base URL: `https://api.bluefox.email`
- URL: `https://api.bluefox.email/v1/projectId/{projectId}/triggered-emails`
- Auth: HTTP bearer

subscriberListId must belong to this same project - a valid ID from a different project 404s.

## Path parameters

- `projectId` string, required

## Request body

- TriggeredEmailInput
  - `name` string, required
  - `subscriberListId` string, required: Required. If the user hasn't told you which list this triggered email is for, call GET /v1/projectId/{projectId}/subscriber-lists first and ask them to choose from the real list names - don't ask them for a raw ID.
  - `excludeUnengaged` boolean
  - `subject` string, required
  - `previewText` string: Optional, but meaningfully affects open rates - if the user hasn't given you one, ask what they'd like it to say rather than leaving it blank.
  - `senderIdentity` string: A sender identity _id. If the user hasn't told you which one to use, call GET /v1/projectId/{projectId}/sender-identities first and ask them to choose from the real email addresses returned - don't ask them for a raw ID.
  - `replyTo` string
  - `type` 'html' | 'text': Omit to keep using the visual (Chamaileon) editor document. Set to "html" or "text" to author document as a raw Handlebars template string instead (see the document field).
  - `document` unknown
  - `feeds` object[]: RSS/Atom/JSON feeds to pull into this email - see variableName on each feed for how to reference it from document.
    - `url` string, required
    - `feedType` 'rss-xml' | 'json', required: "rss-xml" covers both RSS and Atom XML feeds - which one it actually is gets auto-detected from the feed content itself, which changes the array key inside the template (see variableName below).
    - `variableName` string, required: No spaces allowed. This becomes a top-level Handlebars variable in the document (see the `document` field on the parent email for the templating syntax). The feed's parsed items are NOT directly at `{{variableName}}` - they're nested under a feed-shape-dependent array key you loop over with the custom `each` helper: - feedType "rss-xml" that turns out to be RSS: `{{#each <variableName>.item}}...{{/each}}` (array key is the literal word "item", singular) - feedType "rss-xml" that turns out to be Atom: `{{#each <variableName>.entry}}...{{/each}}` (array key is "entry") - feedType "json": the array key is whatever field the source JSON actually uses for its list (e.g. "items", "articles") - inspect the feed's JSON to find it, it is not fixed. Inside the loop, each item's own fields are whatever the feed provides (e.g. RSS gives `{{this.title}}`, `{{this.link}}`, `{{this.pubDate}}`) - there is no fixed schema, it mirrors the feed's actual content one-to-one.
    - `maxItems` integer: Informational only - NOT enforced when the email is sent. To actually limit how many items render, pass limit (and optionally skip) as hash arguments on the each tag itself, e.g. `{{#each news.item limit=5 skip=0}}`.
    - `required` boolean
    - `availableFields` string[]: Informational only, for the app UI - not enforced or used when rendering.

## Response `201`

Created

- object
  - `status` integer
  - `result` TriggeredEmail
    - `_id` string
    - `name` string
    - `subject` string
    - `previewText` string
    - `subscriberListId` string
    - `senderIdentity` string
    - `replyTo` string
    - `type` 'chamaileon' | 'html' | 'text'
    - `excludeUnengaged` boolean
    - `feeds` object[]
      - `url` string, required
      - `feedType` 'rss-xml' | 'json', required: "rss-xml" covers both RSS and Atom XML feeds - which one it actually is gets auto-detected from the feed content itself, which changes the array key inside the template (see variableName below).
      - `variableName` string, required: No spaces allowed. This becomes a top-level Handlebars variable in the document (see the `document` field on the parent email for the templating syntax). The feed's parsed items are NOT directly at `{{variableName}}` - they're nested under a feed-shape-dependent array key you loop over with the custom `each` helper: - feedType "rss-xml" that turns out to be RSS: `{{#each <variableName>.item}}...{{/each}}` (array key is the literal word "item", singular) - feedType "rss-xml" that turns out to be Atom: `{{#each <variableName>.entry}}...{{/each}}` (array key is "entry") - feedType "json": the array key is whatever field the source JSON actually uses for its list (e.g. "items", "articles") - inspect the feed's JSON to find it, it is not fixed. Inside the loop, each item's own fields are whatever the feed provides (e.g. RSS gives `{{this.title}}`, `{{this.link}}`, `{{this.pubDate}}`) - there is no fixed schema, it mirrors the feed's actual content one-to-one.
      - `maxItems` integer: Informational only - NOT enforced when the email is sent. To actually limit how many items render, pass limit (and optionally skip) as hash arguments on the each tag itself, e.g. `{{#each news.item limit=5 skip=0}}`.
      - `required` boolean
      - `availableFields` string[]: Informational only, for the app UI - not enforced or used when rendering.
    - `createdAt` string, date-time
    - `updatedAt` string, date-time

## Other responses

- `400`: Invalid request body or query - every violation found (missing/invalid/unexpected fields) is reported in one response, semicolon-separated, not just the first one hit.
- `403`: Missing or invalid API key

---

[API](https://skmtc.dev/bluefox/apis/bluefox-email-public-api.md) · [All operations](https://skmtc.dev/bluefox/apis/bluefox-email-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bluefox/apis/bluefox-email-public-api/revisions/fa1a0a835c7f?raw)