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

# Create a new workflow

> Creates a workflow definition: a named, ordered sequence of steps (email or webhook), each with a delay relative to the previous step. Optional `triggers` start it automatically on events from connected integrations, e.g. Stripe's trial_started, and `exitConditions` stop a person's active run on others.



## OpenAPI

````yaml /openapi.json post /workflows
openapi: 3.1.0
info:
  title: subscriber.dev API
  description: >-
    Trigger workflows, manage subscribers and send broadcasts. Authenticate with
    an API key in the X-API-Key header: the key decides the environment. Docs:
    https://docs.subscriber.dev
  version: '1.0'
  contact: {}
servers:
  - url: https://api.subscriber.dev
    description: Cloud
security: []
tags: []
paths:
  /workflows:
    post:
      tags:
        - Workflows
      summary: Create a new workflow
      description: >-
        Creates a workflow definition: a named, ordered sequence of steps (email
        or webhook), each with a delay relative to the previous step. Optional
        `triggers` start it automatically on events from connected integrations,
        e.g. Stripe's trial_started, and `exitConditions` stop a person's active
        run on others.
      operationId: createWorkflow
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowRequest'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Environment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited. Wait a second and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearer: []
        - api-key:
            - workflows:write
components:
  schemas:
    CreateWorkflowRequest:
      type: object
      properties:
        key:
          type: string
          minLength: 1
          maxLength: 255
          description: >-
            Stable identifier used to trigger this workflow, e.g. "user-signup".
            Unique within the environment.
        name:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          maxLength: 2000
        type:
          default: automation
          description: >-
            Purely organizational: automation workflows are meant to be
            triggered individually per-subscriber; broadcast workflows are meant
            to be fanned out via the broadcast endpoint. Either can technically
            still be used either way.
          type: string
          enum:
            - automation
            - broadcast
        channels:
          type: object
          properties:
            email:
              type: object
              properties:
                fromName:
                  description: >-
                    Sender name for every email in this workflow, e.g. "Jane
                    from Acme". Defaults to the email integration's fromName.
                    The from address always comes from the integration.
                  type: string
                  maxLength: 255
                replyTo:
                  description: >-
                    Where replies to this workflow's emails go. Defaults to the
                    email integration's replyTo, or the from address.
                  type: string
                  format: email
                  pattern: >-
                    ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
              description: >-
                Email settings for every email in this workflow. Leave a field
                out to use the email integration's.
          description: >-
            Settings for each channel this workflow sends on. Channel-specific,
            so the workflow itself stays channel-neutral.
        steps:
          minItems: 1
          maxItems: 50
          type: array
          items:
            oneOf:
              - type: object
                properties:
                  type:
                    type: string
                    const: email
                  delayMs:
                    default: 0
                    description: >-
                      Milliseconds to wait after the previous step (or after
                      trigger, for the first step) before sending this step.
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  subject:
                    type: string
                    minLength: 1
                    maxLength: 500
                  body:
                    type: string
                    minLength: 1
                    description: >-
                      HTML (or plain text) email body, rendered as a Liquid
                      template (https://liquidjs.com). Supports {{
                      subscriber.firstName }} etc. interpolation from subscriber
                      fields and custom attributes (an attribute called company
                      is {{ subscriber.company }}), and trigger payload fields
                      at the top level (payload {"plan": "pro"} is {{ plan }}),
                      plus {{unsubscribeUrl}} for this subscriber's unsubscribe
                      link, and {% if %}/{% else %}/{% endif %} conditionals,
                      e.g. {% if subscriber.firstName %}Hey {{
                      subscriber.firstName }}{% else %}Hey there{% endif %}.
                      With the default layout, write just the content (<p>,
                      <h1>, <h2>, <a>, <ul>, <img>, <hr>, <blockquote>…) —
                      fonts, spacing and the centred column are applied for you.
                      Add class="button" to a link to render it as a
                      call-to-action button.
                  layout:
                    default: default
                    description: >-
                      "default" wraps the body in a centred, readable layout
                      (system font stack, 600px width, unsubscribe footer).
                      "none" sends the body as-is, for bringing your own full
                      HTML template. A body that is already a full HTML document
                      (has <html> or <body>) is always sent as-is.
                    type: string
                    enum:
                      - default
                      - none
                  previewText:
                    description: >-
                      Short summary inboxes show next to the subject. Supports
                      Liquid. Only used with the default layout.
                    type: string
                    maxLength: 255
                required:
                  - type
                  - subject
                  - body
              - type: object
                properties:
                  type:
                    type: string
                    const: webhook
                  delayMs:
                    default: 0
                    description: >-
                      Milliseconds to wait after the previous step (or after
                      trigger, for the first step) before sending this step.
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  url:
                    type: string
                    format: uri
                    description: Destination URL the JSON payload is POSTed to.
                  body:
                    type: string
                    minLength: 1
                    description: >-
                      JSON payload template, rendered via Liquid
                      (https://liquidjs.com) then POSTed as-is with
                      Content-Type: application/json. e.g. {"content": "{{
                      subscriber.email | json }} just signed up!"} for a Discord
                      webhook. Use the `json` filter around interpolated values
                      to keep the result valid JSON.
                required:
                  - type
                  - url
                  - body
        triggers:
          maxItems: 50
          type: array
          items:
            type: object
            properties:
              source:
                type: string
                minLength: 1
                description: Connected integration that fires the trigger, e.g. "stripe".
              event:
                type: string
                minLength: 1
                maxLength: 255
                description: >-
                  One of the source's events (see list_trigger_sources), e.g.
                  "trial_started", or a raw event type such as
                  "checkout.session.completed".
            required:
              - source
              - event
          description: >-
            Events from connected integrations that start this workflow for the
            person they're about. Automation workflows only; the integration
            must be connected first.
        exitConditions:
          maxItems: 50
          type: array
          items:
            type: object
            properties:
              source:
                type: string
                minLength: 1
                description: Connected integration that fires the trigger, e.g. "stripe".
              event:
                type: string
                minLength: 1
                maxLength: 255
                description: >-
                  One of the source's events (see list_trigger_sources), e.g.
                  "trial_started", or a raw event type such as
                  "checkout.session.completed".
            required:
              - source
              - event
          description: >-
            Events from connected integrations that stop this workflow for the
            person they're about: their active runs are cancelled and unsent
            steps never send. Checked before triggers, so an event in both
            restarts the workflow. Automation workflows only; the integration
            must be connected first.
      required:
        - key
        - name
        - steps
    WorkflowResponse:
      type: object
      properties:
        publicId:
          type: string
        key:
          type: string
        name:
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
        status:
          type: string
          enum:
            - active
            - paused
        type:
          type: string
          enum:
            - automation
            - broadcast
        channels:
          type: object
          properties:
            email:
              type: object
              properties:
                fromName:
                  type: string
                replyTo:
                  type: string
          description: Settings for each channel this workflow sends on.
        steps:
          type: array
          items:
            type: object
            properties:
              publicId:
                type: string
              stepOrder:
                type: number
              type:
                type: string
              delayMs:
                type: number
              subject:
                type: string
              body:
                type: string
              layout:
                description: >-
                  Email steps only. Steps saved before layouts existed have no
                  value and use "default".
                type: string
                enum:
                  - default
                  - none
              previewText:
                description: Email steps only.
                type: string
              url:
                description: >-
                  Webhook URL, redacted to origin + last 4 characters since it
                  usually contains a secret. Sending the redacted value back in
                  an update keeps the stored URL.
                type: string
            required:
              - publicId
              - stepOrder
              - type
              - delayMs
        triggers:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
                minLength: 1
                description: Connected integration that fires the trigger, e.g. "stripe".
              event:
                type: string
                minLength: 1
                maxLength: 255
                description: >-
                  One of the source's events (see list_trigger_sources), e.g.
                  "trial_started", or a raw event type such as
                  "checkout.session.completed".
              label:
                type: string
                description: Human-readable name of the event.
              active:
                type: boolean
                description: >-
                  False while the source's integration is disconnected; it
                  resumes once it's reconnected.
            required:
              - source
              - event
              - label
              - active
        exitConditions:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
                minLength: 1
                description: Connected integration that fires the trigger, e.g. "stripe".
              event:
                type: string
                minLength: 1
                maxLength: 255
                description: >-
                  One of the source's events (see list_trigger_sources), e.g.
                  "trial_started", or a raw event type such as
                  "checkout.session.completed".
              label:
                type: string
                description: Human-readable name of the event.
              active:
                type: boolean
                description: >-
                  False while the source's integration is disconnected; it
                  resumes once it's reconnected.
            required:
              - source
              - event
              - label
              - active
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        editUrl:
          description: >-
            Link to edit this workflow's emails in the web editor. Share it when
            someone wants to tweak the copy or preview an email.
          type: string
      required:
        - publicId
        - key
        - name
        - description
        - status
        - type
        - channels
        - steps
        - triggers
        - exitConditions
        - createdAt
        - updatedAt
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 404
        message:
          type: string
          example: Workflow not found
        error:
          type: string
          example: Not Found
        errors:
          description: Which fields failed validation, on a 400.
          type: array
          items:
            type: object
            properties:
              path:
                type: array
                items:
                  anyOf:
                    - type: string
                    - type: number
              message:
                type: string
              code:
                type: string
            required:
              - path
              - message
      required:
        - statusCode
        - message
  securitySchemes:
    bearer:
      scheme: bearer
      type: http
      description: >-
        A session token from `subscriber login`, used by subscriber.dev's own
        apps. Requests about an environment also need its ID in the
        `x-environment-id` header. From your own code, use an API key.
    api-key:
      type: apiKey
      in: header
      name: X-API-Key
      description: An environment API key. Keep it on your server.

````

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