openapi: 3.1.0
info:
  title: Omnisend REST API
  description: |
    Omnisend's REST API for managing ecommerce email and SMS marketing
    automation. Exposes contacts, events, products, product categories,
    segments, campaigns, batches, email templates, email content, email
    universal layouts, images, brands, and analytics reports. Authentication
    uses an API key passed via the `X-API-KEY` header, or OAuth 2.0 with
    scopes such as `contacts.read`, `contacts.write`, `campaigns.read`,
    `campaigns.write`, `analytics.read`, etc.
  version: "v5"
  contact:
    name: Omnisend
    url: https://api-docs.omnisend.com/
servers:
  - url: https://api.omnisend.com/v5
    description: Omnisend REST API v5
security:
  - ApiKeyAuth: []
  - OAuth2: []
tags:
  - name: Contacts
  - name: Events
  - name: Products
  - name: ProductCategories
  - name: Segments
  - name: Campaigns
  - name: Batches
  - name: EmailTemplates
  - name: EmailContent
  - name: EmailUniversalLayouts
  - name: Images
  - name: Brands
  - name: Analytics
paths:
  /contacts:
    get:
      tags: [Contacts]
      summary: List contacts
      responses:
        "200":
          description: Paginated list of contacts
    post:
      tags: [Contacts]
      summary: Create or update a contact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        "200":
          description: Contact created or updated
    patch:
      tags: [Contacts]
      summary: Update contact by email
      responses:
        "200":
          description: Contact updated
  /contacts/{id}:
    get:
      tags: [Contacts]
      summary: Get a contact
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Contact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
    patch:
      tags: [Contacts]
      summary: Update contact by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Contact updated
  /contacts-tags:
    post:
      tags: [Contacts]
      summary: Add tags to contacts
      responses:
        "200":
          description: Tags added
    delete:
      tags: [Contacts]
      summary: Remove tags from contacts
      responses:
        "200":
          description: Tags removed
  /events:
    post:
      tags: [Events]
      summary: Send a customer event
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "202":
          description: Event accepted
  /products:
    get:
      tags: [Products]
      summary: List products
      responses:
        "200":
          description: List of products
    post:
      tags: [Products]
      summary: Create a product
      responses:
        "201":
          description: Product created
  /products/{productId}:
    get:
      tags: [Products]
      summary: Get a product
      parameters:
        - in: path
          name: productId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Product
    put:
      tags: [Products]
      summary: Replace a product
      parameters:
        - in: path
          name: productId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Product replaced
    delete:
      tags: [Products]
      summary: Delete a product
      parameters:
        - in: path
          name: productId
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Product deleted
  /product-categories:
    get:
      tags: [ProductCategories]
      summary: List product categories
      responses:
        "200":
          description: List of categories
    post:
      tags: [ProductCategories]
      summary: Create a product category
      responses:
        "201":
          description: Category created
  /product-categories/{categoryId}:
    get:
      tags: [ProductCategories]
      summary: Get a product category
      parameters:
        - in: path
          name: categoryId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Category
    patch:
      tags: [ProductCategories]
      summary: Update a product category
      parameters:
        - in: path
          name: categoryId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Category updated
    delete:
      tags: [ProductCategories]
      summary: Delete a product category
      parameters:
        - in: path
          name: categoryId
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Category deleted
  /segments:
    get:
      tags: [Segments]
      summary: List segments
      responses:
        "200":
          description: List of segments
    post:
      tags: [Segments]
      summary: Create a segment
      responses:
        "201":
          description: Segment created
  /segments/{segmentId}:
    get:
      tags: [Segments]
      summary: Get a segment
      parameters:
        - in: path
          name: segmentId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Segment
    put:
      tags: [Segments]
      summary: Update a segment
      parameters:
        - in: path
          name: segmentId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Segment updated
    delete:
      tags: [Segments]
      summary: Delete a segment
      parameters:
        - in: path
          name: segmentId
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Segment deleted
  /segments/{segmentId}/statistics:
    get:
      tags: [Segments]
      summary: Get segment statistics
      parameters:
        - in: path
          name: segmentId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Segment statistics
  /campaigns:
    get:
      tags: [Campaigns]
      summary: List campaigns
      responses:
        "200":
          description: List of campaigns
    post:
      tags: [Campaigns]
      summary: Create a campaign
      responses:
        "201":
          description: Campaign created
  /campaigns/{id}:
    get:
      tags: [Campaigns]
      summary: Get a campaign
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Campaign
    patch:
      tags: [Campaigns]
      summary: Update a campaign
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Campaign updated
    delete:
      tags: [Campaigns]
      summary: Delete a campaign
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Campaign deleted
  /campaigns/{id}/send:
    post:
      tags: [Campaigns]
      summary: Send a campaign
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "202":
          description: Campaign send queued
  /campaigns/{id}/cancel:
    post:
      tags: [Campaigns]
      summary: Cancel a campaign send
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Campaign cancelled
  /campaigns/{id}/copy:
    post:
      tags: [Campaigns]
      summary: Copy a campaign
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "201":
          description: Campaign copied
  /batches:
    get:
      tags: [Batches]
      summary: List batches
      responses:
        "200":
          description: List of batch operations
    post:
      tags: [Batches]
      summary: Create a batch operation
      responses:
        "202":
          description: Batch accepted
  /batches/{batchId}:
    get:
      tags: [Batches]
      summary: Get a batch
      parameters:
        - in: path
          name: batchId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Batch details
  /batches/{batchId}/items:
    get:
      tags: [Batches]
      summary: List items in a batch
      parameters:
        - in: path
          name: batchId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Batch items
  /email-templates:
    get:
      tags: [EmailTemplates]
      summary: List email templates
      responses:
        "200":
          description: Templates
    post:
      tags: [EmailTemplates]
      summary: Create an email template
      responses:
        "201":
          description: Template created
  /email-templates/{id}:
    get:
      tags: [EmailTemplates]
      summary: Get an email template
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Template
    put:
      tags: [EmailTemplates]
      summary: Replace an email template
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Template replaced
    delete:
      tags: [EmailTemplates]
      summary: Delete an email template
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Template deleted
  /email-templates/{id}/render:
    post:
      tags: [EmailTemplates]
      summary: Render an email template
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Rendered email
  /email-templates-import:
    post:
      tags: [EmailTemplates]
      summary: Import an email template from HTML
      responses:
        "201":
          description: Template imported
  /email-content/{id}:
    get:
      tags: [EmailContent]
      summary: Get email content
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Email content
    put:
      tags: [EmailContent]
      summary: Update email content
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Email content updated
  /email-content/{id}/render:
    post:
      tags: [EmailContent]
      summary: Render email content
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Rendered content
  /email-universal-layouts:
    get:
      tags: [EmailUniversalLayouts]
      summary: List universal layouts
      responses:
        "200":
          description: Layouts
    post:
      tags: [EmailUniversalLayouts]
      summary: Create a universal layout
      responses:
        "201":
          description: Layout created
  /email-universal-layouts/{id}:
    get:
      tags: [EmailUniversalLayouts]
      summary: Get a universal layout
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Layout
    put:
      tags: [EmailUniversalLayouts]
      summary: Update a universal layout
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Layout updated
    delete:
      tags: [EmailUniversalLayouts]
      summary: Delete a universal layout
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Layout deleted
  /images:
    get:
      tags: [Images]
      summary: List images
      responses:
        "200":
          description: Images
    post:
      tags: [Images]
      summary: Upload an image by URL
      responses:
        "201":
          description: Image created
  /images-upload:
    post:
      tags: [Images]
      summary: Upload an image file
      responses:
        "201":
          description: Image uploaded
  /images/{id}:
    get:
      tags: [Images]
      summary: Get an image
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Image
    delete:
      tags: [Images]
      summary: Delete an image
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Image deleted
  /brands/current:
    get:
      tags: [Brands]
      summary: Get current brand
      responses:
        "200":
          description: Brand
    post:
      tags: [Brands]
      summary: Connect a brand
      responses:
        "200":
          description: Brand connected
  /analytics-reports:
    post:
      tags: [Analytics]
      summary: Generate a marketing analytics report
      responses:
        "200":
          description: Report
  /analytics-statistics:
    post:
      tags: [Analytics]
      summary: Generate event-based statistics report
      responses:
        "200":
          description: Statistics report
components:
  schemas:
    Contact:
      type: object
      properties:
        contactID:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        status:
          type: string
          enum: [subscribed, unsubscribed, nonSubscribed]
        tags:
          type: array
          items:
            type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.omnisend.com/oauth/authorize
          tokenUrl: https://api.omnisend.com/v5/oauth/token
          scopes:
            contacts.read: Read contacts
            contacts.write: Manage contacts
            campaigns.read: Read campaigns
            campaigns.write: Manage campaigns
            analytics.read: Read analytics