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

# Send a transactional email

> Send a transactional email.

Send a transactional email, including optional data variables, to a single recipient.

To set dynamic Subject, From, Reply to, CC, BCC email header fields, add data variables to those fields in the editor, then include data for each variable in the API request. Read our [transactional email guide](/docs/docs/transactional) for more details.

To send a test preview of a transactional email, use the [Preview email message](/docs/api-reference/preview-email-message) endpoint.

<Note>Please [email us](mailto:help@loops.so) to enable attachments on your account before using them with the API.</Note>


## OpenAPI

````yaml /openapi.json post /v1/transactional
openapi: 3.1.0
info:
  title: Loops OpenAPI Spec
  description: This is the OpenAPI Spec for the [Loops API](https://loops.so/docs/api).
  version: 1.20.0
servers:
  - url: https://app.loops.so/api
security: []
tags:
  - name: API key
  - name: Audience segments
    description: View audience segments
  - name: Campaigns
    description: Create and manage email campaigns
  - name: Campaign groups
    description: Organize campaigns into groups
  - name: Components
    description: View email components
  - name: Configuration
    description: View configuration settings
  - name: Contacts
    description: Manage contacts in your audience
  - name: Contact properties
    description: Manage contact properties
  - name: Email messages
    description: Manage email message content for campaigns
  - name: Events
    description: Trigger workflows with events
  - name: Event patterns
    description: View workflow event patterns
  - name: Mailing lists
    description: View mailing lists
  - name: Themes
    description: View email themes
  - name: Transactional emails
    description: Create, manage, and send transactional emails
  - name: Transactional groups
    description: Organize transactional emails into groups
  - name: Uploads
    description: Upload image assets
  - name: Workflows
    description: View and mutate workflow graphs
  - name: Workflow nodes
    description: View and mutate workflow nodes
paths:
  /v1/transactional:
    post:
      tags:
        - Transactional emails
      summary: Send a transactional email
      description: >-
        Send a transactional email to a contact.<br>Please [email
        us](mailto:help@loops.so) to enable attachments on your account before
        using them with the API.


        To set dynamic Subject, From, Reply to, CC, BCC email header fields, add
        data variables to those fields in the editor, then include data for each
        variable in the API request. Read our transactional email guide for more
        details.
      parameters:
        - in: header
          name: Idempotency-Key
          description: >-
            Include a unique ID for this request (maximum 100 characters) to
            avoid duplicate emails.


            The value should be a string of up to 100 characters and should be
            unique for each request. We recommend using V4 UUIDs or some other
            method with enough guaranteed entropy to avoid collisions during a
            24 hour window.


            This endpoint will return a `409 Conflict` response if the
            idempotency key has been used in the previous 24 hours.
          schema:
            type: string
            maxLength: 100
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionalRequest'
        required: true
      responses:
        '200':
          description: Successful send.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionalSuccessResponse'
        '400':
          description: Bad request (e.g. transactional email is not published).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TransactionalSendFailureResponse'
                  - $ref: '#/components/schemas/TransactionalFailure2Response'
                  - $ref: '#/components/schemas/TransactionalFailure3Response'
                  - $ref: '#/components/schemas/TransactionalFailure4Response'
                  - $ref: '#/components/schemas/TransactionalFailure5Response'
        '404':
          description: Transactional email not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionalFailure3Response'
        '405':
          description: Wrong HTTP request method.
        '409':
          description: Idempotency key has been used.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdempotencyKeyFailureResponse'
      security:
        - apiKey: []
components:
  schemas:
    TransactionalRequest:
      type: object
      required:
        - email
        - transactionalId
      properties:
        email:
          type: string
          description: The recipient's email address.
        transactionalId:
          type: string
          description: The ID of the transactional email to send.
        addToAudience:
          type: boolean
          description: >-
            If `true`, a contact will be created in your audience using the
            `email` value (if a matching contact doesn't already exist).
        dataVariables:
          type: object
          description: >-
            An object containing data as defined by the data variables added to
            the transactional email template. Values can be of type string or
            number.


            If you have added optional data variables to your email, you can
            exclude them from the dataVariables object or set the value to "".


            If you have added an array data variable to your email, make sure to
            include an array matching the data variables you added to your array
            block.
          examples:
            - name: Chris
              passwordResetLink: https://example.com/reset-password
        attachments:
          type: array
          description: >-
            A list containing file objects to be sent along with an email
            message. Attachments must be enabled by Loops support before they
            can be used with the API.
          items:
            type: object
            required:
              - filename
              - contentType
              - data
            properties:
              filename:
                type: string
                description: The name of the file, shown in email clients.
              contentType:
                type: string
                description: The MIME type of the file.
              data:
                type: string
                description: The base64-encoded content of the file.
    TransactionalSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - true
      required:
        - success
    TransactionalSendFailureResponse:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
      required:
        - success
        - message
    TransactionalFailure2Response:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
        path:
          type: string
      required:
        - success
        - message
        - path
    TransactionalFailure3Response:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
        error:
          type: object
          properties:
            path:
              type: string
            message:
              type: string
      required:
        - success
        - message
        - error
    TransactionalFailure4Response:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
        error:
          type: object
          properties:
            path:
              type: string
            reason:
              type: string
      required:
        - success
        - message
        - error
    TransactionalFailure5Response:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
        error:
          type: object
          properties:
            path:
              type: string
            message:
              type: string
        transactionalId:
          type: string
      required:
        - success
        - message
        - error
        - transactionalId
    IdempotencyKeyFailureResponse:
      type: object
      properties:
        success:
          type: boolean
          examples:
            - false
        message:
          type: string
      required:
        - success
        - message
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer

````