Loops API

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.8.0
servers:
  - url: https://app.loops.so/api/v1
tags:
  - name: API key
  - name: Contacts
    description: Manage contacts in your audience
  - name: Contact properties
    description: Manage contact properties
  - name: Mailing lists
    description: View mailing lists
  - name: Campaigns
    description: Create and manage email campaigns
  - name: Email messages
    description: Manage email message content for campaigns
  - name: Themes
    description: View email themes
  - name: Components
    description: View email components
  - name: Events
    description: Trigger email sending with events
  - name: Transactional emails
    description: Send and view transactional emails
  - name: Dedicated sending IPs
    description: View dedicated sending IP addresses
paths:
  /api-key:
    get:
      tags:
        - API key
      summary: Test your API key
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    examples:
                      - true
                  teamName:
                    type: string
                    description: The name of the team the API key belongs to.
                    examples:
                      - Company name
                required:
                  - success
                  - teamName
        "401":
          description: Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    examples:
                      - false
                  message:
                    type: string
                    examples:
                      - Invalid API key
                  error:
                    type: string
                    examples:
                      - Invalid API key
      security:
        - apiKey: []
  /contacts/create:
    post:
      tags:
        - Contacts
      summary: Create a contact
      description: Add a contact to your audience.
      requestBody:
        description:
          You can add custom contact properties as keys in this request (of
          type `string`, `number`, `boolean` or `date` ([see available date
          formats](https://loops.so/docs/contacts/properties#dates))).<br>Make
          sure to create the properties in Loops before using them in API calls.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactRequest"
        required: true
      responses:
        "200":
          description: Successful create.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactSuccessResponse"
        "400":
          description: Bad request (e.g. invalid email address).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactFailureResponse"
        "405":
          description: Wrong HTTP request method.
        "409":
          description: Email or `userId` already exists.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactFailureResponse"
      security:
        - apiKey: []
  /contacts/update:
    put:
      tags:
        - Contacts
      summary: Update a contact
      description:
        Update a contact by `email` or `userId`. You must provide one of
        these parameters.<br>If you want to update a contact’s email address,
        the contact will first need a `userId` value. You can then make a
        request containing the userId field along with an updated email address.
      requestBody:
        description:
          You can add custom contact properties as keys in this request (of
          type `string`, `number`, `boolean` or `date` ([see available date
          formats](https://loops.so/docs/contacts/properties#dates))).<br>Make
          sure to create the properties in Loops before using them in API calls.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactUpdateRequest"
        required: true
      responses:
        "200":
          description: Successful update.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactSuccessResponse"
        "400":
          description: Bad request (e.g. `email` or `userId` are missing).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactFailureResponse"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
  /contacts/find:
    get:
      tags:
        - Contacts
      summary: Find a contact
      description:
        Search for a contact by `email` or `userId`. Only one parameter is
        allowed.
      parameters:
        - name: email
          in: query
          required: false
          description: Email address (URI-encoded)
          schema:
            type: string
        - name: userId
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description:
            List of contacts (or an empty array if no contact was found).
            Contact objects will include any custom properties.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Contact"
        "400":
          description: Bad request (e.g. invalid email address).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactFailureResponse"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
  /contacts/delete:
    post:
      tags:
        - Contacts
      summary: Delete a contact
      description: Delete a contact by `email` or `userId`.
      requestBody:
        description: Include only one of `email` or `userId`.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactDeleteRequest"
        required: true
      responses:
        "200":
          description: Successful delete.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactDeleteResponse"
        "400":
          description: Bad request (e.g. `email` and `userId` are both provided).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactFailureResponse"
        "404":
          description: Contact not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactFailureResponse"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
  /contacts/suppression:
    get:
      tags:
        - Contacts
      summary: Get suppression status for a contact
      description:
        Retrieve suppression status and removal quota for a contact by
        `email` or `userId`. Include only one query parameter.
      parameters:
        - name: email
          in: query
          required: false
          description: Email address (URI-encoded)
          schema:
            type: string
        - name: userId
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactSuppressionStatusResponse"
        "400":
          description: Bad request (e.g. invalid email address).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactFailureResponse"
        "404":
          description: Contact not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactFailureResponse"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
    delete:
      tags:
        - Contacts
      summary: Remove a contact from suppression list
      description:
        Remove a suppressed contact from the suppression list by `email` or
        `userId`. Include only one query parameter.
      parameters:
        - name: email
          in: query
          required: false
          description: Email address (URI-encoded)
          schema:
            type: string
        - name: userId
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Successful removal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactSuppressionRemoveResponse"
        "400":
          description: Bad request (e.g. contact is not suppressed).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactFailureResponse"
        "404":
          description: Contact not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactFailureResponse"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
  /contacts/properties:
    post:
      tags:
        - Contact properties
      summary: Create a contact property
      description: Add a contact property to your team.
      requestBody:
        description: The name value must be in camelCase, like `planName`.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContactPropertyCreateRequest"
        required: true
      responses:
        "200":
          description: Successful create.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactPropertySuccessResponse"
        "400":
          description: Bad request (e.g. invalid type).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactPropertyFailureResponse"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
    get:
      tags:
        - Contact properties
      summary: Get a list of contact properties
      description:
        Retrieve a list of your account's contact properties.<br>Use the
        `list` parameter to query "all" or "custom" properties.
      parameters:
        - name: list
          in: query
          required: false
          description: \"all\" (default) or \"custom\"
          schema:
            type: string
      responses:
        "200":
          description: Successful.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ContactProperty"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
  /dedicated-sending-ips:
    get:
      tags:
        - Dedicated sending IPs
      summary: Get dedicated sending IP addresses
      description: Retrieve a list of Loops' dedicated sending IP addresses.
      responses:
        "200":
          description: Successful.
          content:
            application/json:
              schema:
                type: array
                description: List of dedicated sending IP addresses
                items:
                  type: string
                  description: IP address
                  examples:
                    - 1.2.3.4
        "405":
          description: Wrong HTTP request method.
        "500":
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                required:
                  - success
                  - message
      security:
        - apiKey: []
  /lists:
    get:
      tags:
        - Mailing lists
      summary: Get a list of mailing lists
      description: Retrieve a list of your account's mailing lists.
      responses:
        "200":
          description: Successful.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/MailingList"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
  /events/send:
    post:
      tags:
        - Events
      summary: Send an event
      description: Send events to trigger emails in Loops.
      requestBody:
        description:
          Provide either `email` or `userId` to identify the contact ([read
          more](https://loops.so/docs/api-reference/send-event#body)).<br>You
          can add event properties, which will be available in emails sent by
          this event. Values can be of type string, number, boolean or date
          ([see allowed date
          formats](https://loops.so/docs/events/properties#important-information-about-event-properties)).<br>Make
          sure to create the properties in Loops before using them in API
          calls.<br>You can add contact properties as keys in this request (of
          type `string`, `number`, `boolean` or `date` ([see available date
          formats](https://loops.so/docs/contacts/properties#dates))).
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EventRequest"
        required: true
      parameters:
        - in: header
          name: Idempotency-Key
          description:
            Include a unique ID for this request (maximum 100 characters) to
            avoid duplicate events. [More
            info](https://loops.so/docs/api-reference/send-event#param-idempotency-key)
          schema:
            type: string
            maxLength: 100
      responses:
        "200":
          description: Successful send.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventSuccessResponse"
        "400":
          description: Bad request (e.g. `eventName` is missing).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventFailureResponse"
        "405":
          description: Wrong HTTP request method.
        "409":
          description: Idempotency key has been used.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdempotencyKeyFailureResponse"
      security:
        - apiKey: []
  /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.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionalRequest"
        required: true
      parameters:
        - in: header
          name: Idempotency-Key
          description:
            Include a unique ID for this request (maximum 100 characters) to
            avoid duplicate emails. [More
            info](https://loops.so/docs/api-reference/send-transactional-email#param-idempotency-key)
          schema:
            type: string
            maxLength: 100
      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/TransactionalFailureResponse"
                  - $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: []
    get:
      tags:
        - Transactional emails
      summary: List transactional emails
      description: Get a list of published transactional emails.
      parameters:
        - name: perPage
          in: query
          required: false
          description:
            How many results to return in each request. Must be between 10 and
            50. Default is 20.
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          description:
            A cursor, to return a specific page of results. Cursors can be
            found from the `pagination.nextCursor` value in each response.
          schema:
            type: string
      responses:
        "200":
          description: Successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListTransactionalsResponse"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
  "/themes/{themeId}":
    parameters:
      - name: themeId
        in: path
        required: true
        description: The ID of the theme.
        schema:
          type: string
    get:
      tags:
        - Themes
      summary: Get a theme
      description: Retrieve a single theme by ID.
      responses:
        "200":
          description: Successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ThemeResponse"
        "400":
          description: Invalid `themeId`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ThemeFailureResponse"
        "401":
          description: Invalid API key or content API not enabled for this team.
        "404":
          description: Theme not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ThemeFailureResponse"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
  /themes:
    get:
      tags:
        - Themes
      summary: List themes
      description: Retrieve a paginated list of email themes, most recently created first.
      parameters:
        - name: perPage
          in: query
          required: false
          description:
            How many results to return in each request. Must be between 10 and
            50. Default is 20.
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          description:
            A cursor to return a specific page of results. Cursors can be found
            from the `pagination.nextCursor` value in each response.
          schema:
            type: string
      responses:
        "200":
          description: Successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListThemesResponse"
        "400":
          description: Invalid `perPage` value.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ThemeFailureResponse"
        "401":
          description: Invalid API key or content API not enabled for this team.
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
  "/components/{componentId}":
    parameters:
      - name: componentId
        in: path
        required: true
        description: The ID of the component.
        schema:
          type: string
    get:
      tags:
        - Components
      summary: Get a component
      description: Retrieve a single component by ID.
      responses:
        "200":
          description: Successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComponentResponse"
        "400":
          description: Invalid `componentId`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComponentFailureResponse"
        "401":
          description: Invalid API key or content API not enabled for this team.
        "404":
          description: Component not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComponentFailureResponse"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
  /components:
    get:
      tags:
        - Components
      summary: List components
      description: Retrieve a paginated list of email components.
      parameters:
        - name: perPage
          in: query
          required: false
          description:
            How many results to return in each request. Must be between 10 and
            50. Default is 20.
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          description:
            A cursor to return a specific page of results. Cursors can be found
            from the `pagination.nextCursor` value in each response.
          schema:
            type: string
      responses:
        "200":
          description: Successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListComponentsResponse"
        "400":
          description: Invalid `perPage` value.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComponentFailureResponse"
        "401":
          description: Invalid API key or content API not enabled for this team.
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
  /campaigns:
    get:
      tags:
        - Campaigns
      summary: List campaigns
      description: Retrieve a paginated list of campaigns.
      parameters:
        - name: perPage
          in: query
          required: false
          description:
            How many results to return in each request. Must be between 10 and
            50. Default is 20.
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          description:
            A cursor to return a specific page of results. Cursors can be found
            from the `pagination.nextCursor` value in each response.
          schema:
            type: string
      responses:
        "200":
          description: Successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListCampaignsResponse"
        "400":
          description: Invalid `perPage` value.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CampaignFailureResponse"
        "401":
          description: Invalid API key or content API not enabled for this team.
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
    post:
      tags:
        - Campaigns
      summary: Create a campaign
      description:
        Create a new draft campaign. An empty email message is created
        automatically and its `emailMessageId` is returned. Use the
        `/email-messages/{emailMessageId}` endpoint to set subject, sender,
        preview text, and LMX content.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCampaignRequest"
      responses:
        "201":
          description: Campaign created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateCampaignResponse"
        "400":
          description: Invalid request body or no sending domain configured.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CampaignFailureResponse"
        "401":
          description: Invalid API key or content API not enabled for this team.
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
  "/campaigns/{campaignId}":
    parameters:
      - name: campaignId
        in: path
        required: true
        description: The ID of the campaign.
        schema:
          type: string
    get:
      tags:
        - Campaigns
      summary: Get a campaign
      description: Retrieve a single campaign by ID.
      responses:
        "200":
          description: Successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CampaignResponse"
        "400":
          description: Invalid `campaignId`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CampaignFailureResponse"
        "401":
          description: Invalid API key or content API not enabled for this team.
        "404":
          description: Campaign not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CampaignFailureResponse"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
    post:
      tags:
        - Campaigns
      summary: Update a campaign
      description:
        Update a draft campaign's name. Campaigns can only be updated while
        in draft status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateCampaignRequest"
      responses:
        "200":
          description: Campaign updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CampaignResponse"
        "400":
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CampaignFailureResponse"
        "401":
          description: Invalid API key or content API not enabled for this team.
        "404":
          description: Campaign not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CampaignFailureResponse"
        "405":
          description: Wrong HTTP request method.
        "409":
          description: Campaign is not in draft status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CampaignFailureResponse"
      security:
        - apiKey: []
  "/email-messages/{emailMessageId}":
    parameters:
      - name: emailMessageId
        in: path
        required: true
        description: The ID of the email message.
        schema:
          type: string
    get:
      tags:
        - Email messages
      summary: Get an email message
      description: Retrieve an email message, including its compiled LMX content.
      responses:
        "200":
          description: Successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailMessageResponse"
        "400":
          description: Invalid `emailMessageId` or no sending domain configured.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailMessageFailureResponse"
        "401":
          description: Invalid API key or content API not enabled for this team.
        "404":
          description: Email message not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailMessageFailureResponse"
        "405":
          description: Wrong HTTP request method.
      security:
        - apiKey: []
    post:
      tags:
        - Email messages
      summary: Update an email message
      description:
        Update fields on an email message (subject, preview text, sender,
        LMX content). The campaign must be in draft status. Supply
        `expectedRevisionId` matching the current `contentRevisionId` — the
        server rejects mismatched revisions with 409.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateEmailMessageRequest"
      responses:
        "200":
          description: Email message updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailMessageResponse"
        "400":
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailMessageFailureResponse"
        "401":
          description: Invalid API key or content API not enabled for this team.
        "404":
          description: Email message not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailMessageFailureResponse"
        "405":
          description: Wrong HTTP request method.
        "409":
          description:
            Campaign is not in draft status, `contentRevisionId` is stale, or
            content cannot be parsed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailMessageFailureResponse"
        "422":
          description: LMX failed to compile.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailMessageFailureResponse"
      security:
        - apiKey: []
components:
  schemas:
    Contact:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        firstName:
          type:
            - string
            - "null"
        lastName:
          type:
            - string
            - "null"
        source:
          type: string
        subscribed:
          type: boolean
        userGroup:
          type: string
        userId:
          type:
            - string
            - "null"
        mailingLists:
          type: object
          description: An object of mailing list IDs and boolean subscription statuses.
          examples:
            - list_123: true
        optInStatus:
          type:
            - string
            - "null"
          description: Double opt-in status.
          enum:
            - accepted
            - pending
            - rejected
            - null
    ContactRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        subscribed:
          type:

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/loops/refs/heads/main/openapi/loops-openapi.yaml