> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an email template

> Creates a template, a draft unless you publish it. It opens in the app's HTML editor. Its HTML must be valid Jinja using only the workspace's merge tags (GET /v1/templates/merge-tags): an unknown one would render empty in every email, or, for {{user.*}}, fail the send. A name is unique among templates of its type, deleted ones included (a 409).



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/templates
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/templates:
    post:
      tags:
        - templates
      summary: Create an email template
      description: >-
        Creates a template, a draft unless you publish it. It opens in the app's
        HTML editor. Its HTML must be valid Jinja using only the workspace's
        merge tags (GET /v1/templates/merge-tags): an unknown one would render
        empty in every email, or, for {{user.*}}, fail the send. A name is
        unique among templates of its type, deleted ones included (a 409).
      operationId: templates_create
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                creator:
                  anyOf:
                    - maxLength: 320
                      minLength: 3
                      pattern: ^[^@\s]+@[^@\s]+$
                      type: string
                    - type: 'null'
                  default: null
                  description: >-
                    The email of a current member of your workspace, credited as
                    its creator; left out, a person's own key credits that
                    person, and any other key (an org key, a digital worker, a
                    Statisfy staff grant) is credited as itself
                  title: Creator
                description:
                  anyOf:
                    - maxLength: 2000
                      type: string
                    - type: 'null'
                  default: null
                  title: Description
                html:
                  default: ''
                  description: >-
                    The email's HTML, with Jinja merge tags such as
                    {{contact.first_name}}, {{account.name}}, {{user.name}} (the
                    sender) and {{unsubscribe_this}} (the unsubscribe link's
                    address). GET /v1/templates/merge-tags lists the
                    workspace's. A merge tag with no value for a recipient
                    renders empty, except a {{user.*}} tag (the sender): it
                    takes its value from the person the campaign sends as
                    through an owner role, and when there is no such person or
                    their field is blank, the campaign's send fails
                  maxLength: 2000000
                  title: Html
                  type: string
                name:
                  description: Unique among templates of its type, deleted ones included
                  maxLength: 255
                  minLength: 1
                  title: Name
                  type: string
                sender_email:
                  anyOf:
                    - maxLength: 320
                      minLength: 3
                      pattern: ^[^@\s]+@[^@\s]+$
                      type: string
                    - type: 'null'
                  default: null
                  description: The address it's sent from
                  title: Sender Email
                sender_name:
                  anyOf:
                    - maxLength: 255
                      type: string
                    - type: 'null'
                  default: null
                  title: Sender Name
                state:
                  default: draft
                  description: >-
                    published needs a subject, a sender and HTML, and the
                    unsubscribe link unless it is an updates email
                  enum:
                    - draft
                    - published
                  title: State
                  type: string
                subject:
                  anyOf:
                    - maxLength: 998
                      type: string
                    - type: 'null'
                  default: null
                  description: 'Sent as written: merge tags in a subject are not filled in'
                  title: Subject
                type:
                  description: >-
                    promotion, newsletter, updates or custom, as the app offers
                    them. An updates email may go without an unsubscribe link;
                    the others need one to be published
                  enum:
                    - promotion
                    - newsletter
                    - updates
                    - custom
                  title: Type
                  type: string
              required:
                - name
                - type
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplate'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    EmailTemplate:
      properties:
        attachments:
          description: Files sent with it, added in the app
          items:
            $ref: '#/components/schemas/EmailTemplateAttachment'
          title: Attachments
          type: array
        created_at:
          format: date-time
          title: Created At
          type: string
        creator:
          anyOf:
            - type: string
            - type: 'null'
          description: The email of the member who created it; null when an API key did
          title: Creator
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        editor:
          description: >-
            Which of the app's editors opens it: visual (the drag-and-drop
            builder, which keeps its own design of the email) or html (its HTML
            editor)
          enum:
            - visual
            - html
          title: Editor
          type: string
        html:
          description: >-
            The email's HTML, with Jinja merge tags such as
            {{contact.first_name}}, {{account.name}}, {{user.name}} (the sender)
            and {{unsubscribe_this}} (the unsubscribe link's address). GET
            /v1/templates/merge-tags lists the workspace's. A merge tag with no
            value for a recipient renders empty, except a {{user.*}} tag (the
            sender): it takes its value from the person the campaign sends as
            through an owner role, and when there is no such person or their
            field is blank, the campaign's send fails
          title: Html
          type: string
        id:
          title: Id
          type: string
        merge_tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: >-
            The merge tags its HTML uses, as group.key (account.name) or a name
            (unsubscribe_this); null when the HTML isn't valid Jinja (a preview
            says why)
          title: Merge Tags
        name:
          description: Unique among templates of its type (deleted ones included)
          title: Name
          type: string
        sender_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Sender Email
        sender_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Sender Name
        state:
          description: >-
            draft or published. The app offers only published templates when
            someone sets up a campaign or flow, but a campaign or flow already
            using a template reads it each time it sends, draft or published: a
            change goes out on its next send. Deleting a template is what stops
            it
          enum:
            - draft
            - published
          title: State
          type: string
        subject:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Sent as written: merge tags in a subject are not filled in'
          title: Subject
        type:
          description: >-
            promotion, newsletter, updates or custom, as the app offers them. An
            updates email may go without an unsubscribe link; the others need
            one to be published
          title: Type
          type: string
        updated_at:
          format: date-time
          title: Updated At
          type: string
        used_by_campaigns:
          description: >-
            How many campaigns point at it, whatever their status. Each reads
            the template when it sends; a campaign whose template is deleted
            skips sending. Agent Studio flows that send it are not counted
          title: Used By Campaigns
          type: integer
      required:
        - id
        - name
        - description
        - type
        - state
        - editor
        - subject
        - sender_name
        - sender_email
        - creator
        - created_at
        - updated_at
        - html
        - merge_tags
        - used_by_campaigns
        - attachments
      title: EmailTemplate
      type: object
    EmailTemplateAttachment:
      properties:
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        mime_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Mime Type
        size_bytes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Size Bytes
      required:
        - id
        - filename
        - mime_type
        - size_bytes
      title: EmailTemplateAttachment
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.