Omnisend

Omnisend Segments API

The Segments API from Omnisend — 6 operation(s) for segments. Version 2026-03-15, harvested from Omnisend's published contract.

Documentation GitHub OpenAPI

Operations 6

GET /segments List segments #

POST /segments Create segment #

DELETE /segments/{segmentID} Delete segment #

GET /segments/{segmentID} Get segment #

PUT /segments/{segmentID} Update segment #

GET /segments/{segmentID}/statistics Get segment statistics #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/omnisend-segments-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  contact: {}
  description: Manage contact segments using flexible condition-based rules.
  title: Segments API
  version: '5.0'
servers:
- url: https://api.omnisend.com/api
tags:
- name: Segments
paths:
  /segments:
    get:
      description: 'List segments with sorting and cursor-based pagination support.


        **Scopes:**

        `segments.read`


        **Pagination:**

        This endpoint uses cursor-based pagination. Use the `after` cursor from the response to get the next page,

        or the `before` cursor to get the previous page. Do not use both `after` and `before` parameters simultaneously.


        **Sorting:**

        - Only single-field sorting is supported. You cannot sort by multiple fields.

        - Available sort fields: `createdAt` (default), `name`.

        - When sorting by `name`, segments are sorted lexicographically (case-sensitive).

        - Sort parameters are only required on the first request. Subsequent requests using a cursor

        will automatically use the sort settings embedded in the cursor.


        **Cursor Behavior:**

        - Cursors are self-contained and include all parameters needed for pagination.

        - Once you have a cursor, you only need to pass the cursor for subsequent pages.

        - If sort parameters are provided with a cursor, they must match the cursor''s sort settings.

        - Cursors may become invalid if the underlying data changes significantly (e.g., the referenced segment is deleted).


        **Rate Limiting:**

        This endpoint is rate limited to 100 requests per minute.'
      parameters:
      - description: Page size (1-50)
        in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
      - description: Cursor for next page (base64-encoded, obtained from previous response)
        in: query
        name: after
        schema:
          type: string
      - description: Cursor for previous page (base64-encoded, obtained from previous response)
        in: query
        name: before
        schema:
          type: string
      - description: Sort field (only needed on first request)
        in: query
        name: sort
        schema:
          type: string
          enum:
          - createdAt
          - name
          default: createdAt
      - description: Sort direction (only needed on first request)
        in: query
        name: direction
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - $ref: '#/components/parameters/APIVersionHeader'
      responses:
        '200':
          description: Segments list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSegmentsResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - segments.read
      - ApiKeyAuth: []
      summary: List segments
      tags:
      - Segments
      operationId: getSegments
      x-operation-id-source: derived
    post:
      description: Creates a new segment.
      parameters:
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSegmentRequest'
        description: Segment creation request
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSegmentResponse'
        '400':
          description: Invalid request body or validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - segments.write
      - ApiKeyAuth: []
      summary: Create segment
      tags:
      - Segments
      operationId: postSegments
      x-operation-id-source: derived
  /segments/{segmentID}:
    delete:
      description: 'Permanently deletes a segment by its unique identifier.

        The segment must not be in a building state to be deleted.

        If the segment is currently being built, a `409 Conflict` error is returned.


        **Scopes:**

        `segments.write`


        **Rate Limiting:**

        This endpoint is rate limited to 100 requests per minute.'
      parameters:
      - description: Segment ID
        in: path
        name: segmentID
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      responses:
        '204':
          description: No Content
        '400':
          description: Request contains invalid or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Segment is currently being built and cannot be deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - segments.write
      - ApiKeyAuth: []
      summary: Delete segment
      tags:
      - Segments
      operationId: deleteSegmentsBySegmentID
      x-operation-id-source: derived
    get:
      description: 'Returns a segment by its unique identifier.


        **Scopes:**

        `segments.read`


        **Rate Limiting:**

        This endpoint is rate limited to 100 requests per minute.'
      parameters:
      - description: Segment ID (24 character hexadecimal)
        in: path
        name: segmentID
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      responses:
        '200':
          description: Segment resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSegmentResponse'
        '400':
          description: Request contains invalid or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Segment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - segments.read
      - ApiKeyAuth: []
      summary: Get segment
      tags:
      - Segments
      operationId: getSegmentsBySegmentID
      x-operation-id-source: derived
    put:
      description: 'Updates an existing segment by ID.

        The segment must not be in a building state to be updated.

        If the segment is currently being built, a `409 Conflict` error is returned.


        **Scopes:**

        `segments.write`


        **Rate Limiting:**

        This endpoint is rate limited to 15 requests per minute.


        The request body structure (`name` and `conditionGroups`) is identical to Create segment.

        See the Create segment endpoint for detailed examples of condition groups, filters, and advanced segmentation patterns.'
      parameters:
      - description: Segment ID
        in: path
        name: segmentID
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSegmentRequest'
        description: Segment update request
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSegmentResponse'
        '400':
          description: Invalid request body or validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Segment with the given ID was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Segment is currently being built and cannot be updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - segments.write
      - ApiKeyAuth: []
      summary: Update segment
      tags:
      - Segments
      operationId: putSegmentsBySegmentID
      x-operation-id-source: derived
  /segments/{segmentID}/statistics:
    get:
      description: 'Returns statistics for a segment, including the total number of matching contacts.


        **Scopes:**

        `segments.read`


        **Rate Limiting:**

        This endpoint is rate limited to 100 requests per minute.'
      parameters:
      - description: Segment ID (24 character hexadecimal)
        in: path
        name: segmentID
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/APIVersionHeader'
      responses:
        '200':
          description: Segment statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSegmentStatisticsResponse'
        '400':
          description: Request contains invalid or missing fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Segment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - Bearer:
        - segments.read
      - ApiKeyAuth: []
      summary: Get segment statistics
      tags:
      - Segments
      operationId: getSegmentsBySegmentIDStatistics
      x-operation-id-source: derived
components:
  schemas:
    FieldError:
      description: A single field validation failure within a validation error response.
      properties:
        code:
          description: Error code indicating the type of failure
          example: invalid_format
          type: string
        field:
          description: Dot-separated path to the field that failed validation
          example: content.email.subject
          type: string
        message:
          description: Human-readable explanation of what is wrong with the field value
          example: Must be a valid email address
          type: string
      type: object
    GetSegmentStatisticsResponse:
      description: Segment statistics resource.
      properties:
        contactsCount:
          description: Segment contacts count (read-only)
          example: 1234
          readOnly: true
          type: integer
      type: object
    RateLimitProblem:
      description: Error response returned when the rate limit is exceeded. Use the retryAfter value to know when it is safe to retry the request.
      properties:
        detail:
          description: Human-readable explanation of this specific error occurrence
          example: A human-readable explanation of the error.
          type: string
        instance:
          description: Request trace identifier for support and debugging
          example: urn:omnisend:request:00000000-0000-0000-0000-000000000001
          type: string
        retryAfter:
          description: Seconds to wait before retrying the request
          example: 60
          type: integer
        status:
          description: HTTP status code
          example: 0
          type: integer
        title:
          description: Short description of the error type
          example: Problem
          type: string
        type:
          description: URI that identifies the error type
          example: https://problems.omnisend.com/problem
          type: string
      type: object
    ListSegmentsResponse:
      description: Paginated list of segments.
      properties:
        paging:
          allOf:
          - $ref: '#/components/schemas/PagingResponse'
          description: Pagination metadata for navigating results
        segments:
          description: List of segments on the current page
          items:
            $ref: '#/components/schemas/GetSegmentResponse'
          type: array
      type: object
    ValidationProblem:
      description: Error response returned when the request contains invalid input. The errors array lists every field that failed validation.
      properties:
        detail:
          description: Human-readable explanation of this specific error occurrence
          example: A human-readable explanation of the error.
          type: string
        errors:
          description: List of fields that failed validation
          items:
            $ref: '#/components/schemas/FieldError'
          type: array
        instance:
          description: Request trace identifier for support and debugging
          example: urn:omnisend:request:00000000-0000-0000-0000-000000000001
          type: string
        status:
          description: HTTP status code
          example: 0
          type: integer
        title:
          description: Short description of the error type
          example: Problem
          type: string
        type:
          description: URI that identifies the error type
          example: https://problems.omnisend.com/problem
          type: string
      type: object
    CreateSegmentRequest:
      description: Request body for creating a new segment.
      properties:
        conditionGroups:
          description: Condition groups defining the segment rules
          items:
            $ref: '#/components/schemas/SegmentConditionGroup'
          type: array
        name:
          description: Name of the segment
          example: My Segment
          maxLength: 256
          type: string
      required:
      - conditionGroups
      - name
      type: object
    GetSegmentResponse:
      description: Segment resource representation.
      properties:
        archivedAt:
          description: Segment archival timestamp, null if not archived (read-only)
          example: '2026-06-01T00:00:00Z'
          readOnly: true
          type:
          - string
          - 'null'
        conditionGroups:
          description: Condition groups defining the segment rules
          items:
            $ref: '#/components/schemas/SegmentConditionGroup'
          type: array
        createdAt:
          description: Segment creation timestamp (read-only)
          example: '2026-01-15T10:30:00Z'
          readOnly: true
          type: string
        isStarred:
          description: Whether the segment is marked as a favourite
          example: false
          type: boolean
        name:
          description: Segment name
          example: VIP Customers
          type: string
        segmentID:
          description: Segment unique identifier (read-only)
          example: '000000000000000000000001'
          readOnly: true
          type: string
        status:
          description: Segment processing status (read-only)
          enum:
          - ready
          - building
          - archived
          example: ready
          readOnly: true
          type: string
        updatedAt:
          description: Segment last update timestamp (read-only)
          example: '2026-01-20T14:45:00Z'
          readOnly: true
          type: string
      type: object
    CursorsResponse:
      description: Cursor pointers for paginating forward and backward through results
      properties:
        after:
          description: Opaque cursor for fetching the next page of results
          example: eyJpZCI6ImNhbXAtNDU2In0
          type:
          - string
          - 'null'
        before:
          description: Opaque cursor for fetching the previous page of results
          example: eyJpZCI6ImNhbXAtMTIzIn0
          type:
          - string
          - 'null'
      type: object
    UpdateSegmentRequest:
      description: Request body for updating an existing segment.
      properties:
        conditionGroups:
          description: Condition groups defining the segment rules
          items:
            $ref: '#/components/schemas/SegmentConditionGroup'
          type: array
        name:
          description: Name of the segment
          example: My Segment
          maxLength: 256
          type: string
      required:
      - conditionGroups
      - name
      type: object
    PagingResponse:
      description: Cursor-based pagination metadata
      properties:
        cursors:
          allOf:
          - $ref: '#/components/schemas/CursorsResponse'
          description: Cursor values for navigating between pages
        hasMore:
          description: Whether there are more items available beyond the current page
          example: true
          type: boolean
        limit:
          description: Maximum number of items returned per page
          example: 50
          type: integer
      type: object
    SegmentConditionGroup:
      description: Group of conditions combined with a logical junction.
      properties:
        conditions:
          description: List of conditions in this group
          items:
            $ref: '#/components/schemas/SegmentCondition'
          type: array
      type: object
    SegmentCondition:
      description: A single filter condition applied to a specific entity.
      properties:
        entity:
          description: Entity type this condition applies to
          example: contact
          type: string
        filters:
          description: List of filter criteria. Must contain at least one item.
          items: {}
          minItems: 1
          type: array
        junction:
          description: Logical operator combining the filters within this condition
          example: and
          type: string
      required:
      - filters
      type: object
    Problem:
      description: Standard error response returned by all API endpoints on failure.
      properties:
        detail:
          description: Human-readable explanation of this specific error occurrence
          example: A human-readable explanation of the error.
          type: string
        instance:
          description: Request trace identifier for support and debugging
          example: urn:omnisend:request:00000000-0000-0000-0000-000000000001
          type: string
        status:
          description: HTTP status code
          example: 0
          type: integer
        title:
          description: Short description of the error type
          example: Problem
          type: string
        type:
          description: URI that identifies the error type
          example: https://problems.omnisend.com/problem
          type: string
      type: object
  parameters:
    APIVersionHeader:
      description: API version that specifies the response format and behaviour (e.g., 2026-preview)
      in: header
      name: Omnisend-Version
      required: true
      schema:
        type: string
        default: '2026-03-15'
  securitySchemes:
    ApiKeyAuth:
      description: 'API Key authentication. Value format: ''Omnisend-API-Key {api-key}'''
      in: header
      name: Authorization
      type: apiKey
      x-default: Omnisend-API-Key your-api-key
    Bearer:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://app.omnisend.com/oauth2/token
          scopes:
            segments.read: Read segments
            segments.write: Create, update and delete segments

Omnisend Segments API

Operations 6

Documentation

Specifications

Schemas & Data

Other Resources