". **Scopes:** `automations.write`
- [Disable automation workflow](https://api-docs.omnisend.com/reference/post_automations-id-disable.md): Disable an automation workflow. Once disabled, the workflow stops accepting new trigger events. Use `contactsInWorkflow` to control what happens to contacts currently progressing through the workflow: - `keep`: contacts remain and continue through the remaining blocks until completion. No new contacts enter. - `exit`: all contacts are immediately removed from the workflow. Contacts who have not yet received their messages will not receive them. Disabling an already-disabled automation is idempotent — returns the current state without side effects. **Scopes:** `automations.write`
- [Enable automation workflow](https://api-docs.omnisend.com/reference/post_automations-id-enable.md): Enable an automation workflow. Once enabled, the workflow starts processing trigger events in real time. The request body is optional. Use `enrollExisting` to also enroll contacts who already qualify at the time of enabling. When the body is omitted (or `enrollExisting` is omitted or false), only future trigger events are processed. Enabling an already-enabled automation is idempotent — returns the current state without side effects. **Scopes:** `automations.write`
- [Create automation workflow](https://api-docs.omnisend.com/reference/post_automations.md): Create a new automation workflow. **Scopes:** `automations.write` ## Trigger condition examples The `trigger.condition` field defines the event that enrolls contacts into the automation. Most trigger events use standard Events API event names and may require `origin`. Built-in trigger events, such as `"birthday"`, do not use `origin`. For the `"birthday"` trigger, omit `trigger.condition.filterGroups` to enroll contacts on the day of their birthday. To shift the trigger time, add one filter group with exactly one filter: | Field | Operator | Value shape | |---|---|---| | `birthdate` | `eq` | Hour offset string from the birthday, e.g. `"-24h"`, `"48h"` | Birthday trigger on the contact birthday
```json { "condition": { "event": "birthday" } } ``` Birthday trigger before the contact birthday
```json { "condition": { "event": "birthday", "filterGroups": [ { "logicalOperator": "and", "filters": [ {"field": "birthdate", "operator": "eq", "value": "-24h"} ] } ] } } ``` Birthday trigger after the contact birthday
```json { "condition": { "event": "birthday", "filterGroups": [ { "logicalOperator": "and", "filters": [ {"field": "birthdate", "operator": "eq", "value": "48h"} ] } ] } } ``` To trigger an automation when a contact enters a specific segment, use the `entered segment` event with `origin: "omnisend"` and filter the trigger condition by `segment_id`. This is different from `audienceFilterGroup`, which only restricts who can enter after the trigger fires. Trigger when a contact enters a specific segment
```json { "condition": { "event": "entered segment", "origin": "omnisend", "filterGroups": [ { "logicalOperator": "and", "filters": [ {"field": "segment_id", "operator": "eq", "value": "000000000000000000000001"} ] } ] } } ``` ## Audience filter group examples The `trigger.audienceFilterGroup` field is optional. When set, only contacts matching the filters are enrolled when the trigger fires — omit it to enroll everyone who triggers the event. ### Supported fields | Field | Operators | Value shape | |---|---|---| | `segmentID` | `eq`, `neq` | Segment ID string, e.g. `"000000000000000000000001"` | | `tag` | `eq`, `neq` | Tag name, e.g. `"vip"` | | `dateAdded` | `eq`, `neq`, `gt`, `lt` | ISO-8601 date, e.g. `"2025-03-15"` | | `firstName` | `eq`, `neq`, `contains`, `notContains` | Free string, e.g. `"John"` | | `lastName` | `eq`, `neq`, `contains`, `notContains` | Free string, e.g. `"Smith"` | | `gender` | `eq` | `"m"` or `"f"` | | `country` | `eq`, `neq`, `contains`, `notContains` | ISO-2 country code, e.g. `"US"` | | `state` | `eq`, `neq`, `contains`, `notContains` | State / region name, e.g. `"California"` | | `city` | `eq`, `neq`, `contains`, `notContains` | City name, e.g. `"New York"` | | `postalCode` | `eq`, `neq`, `contains`, `notContains` | Postal code string, e.g. `"10001"` | ### Where it fits `audienceFilterGroup` is a sibling of `condition` inside `trigger`: ```json { "name": "...", "trigger": { "condition": { "event": "...", "origin": "..." }, "audienceFilterGroup": { ... } }, "blocks": [ ... ] } ``` Each example below shows only the `audienceFilterGroup` value — slot it into the skeleton above. Restrict to a single segment
```json { "logicalOperator": "and", "filters": [ {"field": "segmentID", "operator": "eq", "value": "000000000000000000000001"} ] } ``` Include one tag, exclude another
```json { "logicalOperator": "and", "filters": [ {"field": "tag", "operator": "eq", "value": "early-adopter"}, {"field": "tag", "operator": "neq", "value": "beta-churned"} ] } ``` Gender (only `eq`, only `"m"` or `"f"`)
```json { "logicalOperator": "and", "filters": [ {"field": "gender", "operator": "eq", "value": "f"} ] } ``` Country + city substring match
```json { "logicalOperator": "and", "filters": [ {"field": "country", "operator": "eq", "value": "US"}, {"field": "city", "operator": "contains", "value": "York"} ] } ``` Recent contacts only (date cohort)
```json { "logicalOperator": "and", "filters": [ {"field": "dateAdded", "operator": "gt", "value": "2025-01-01"} ] } ``` OR across multiple tags
```json { "logicalOperator": "or", "filters": [ {"field": "tag", "operator": "eq", "value": "vip"}, {"field": "tag", "operator": "eq", "value": "beta"} ] } ``` AND across name, country, and tag
```json { "logicalOperator": "and", "filters": [ {"field": "firstName", "operator": "contains", "value": "John"}, {"field": "country", "operator": "eq", "value": "US"}, {"field": "tag", "operator": "eq", "value": "vip"} ] } ```
- [Update UTM tags for an automation block](https://api-docs.omnisend.com/reference/put_automations-id-blocks-blockid-utm.md): Set UTM tracking tags for a specific send-action block. All three tag fields are replaced atomically. Send an empty string to clear a field — the next read will return its default value. **Scopes:** `automations.write`
- [Replace automation workflow blocks](https://api-docs.omnisend.com/reference/put_automations-id-blocks.md): Replace the full block tree for an automation workflow. Blocks identified by `id` are updated in place. Blocks identified by `temporaryID` are created as new blocks. Existing blocks not included in this array are removed. Enabled automations cannot be restructured. Disable the automation via `POST /automations/{id}/disable`, send the new block tree, then re-enable via `POST /automations/{id}/enable` when ready. When disabling, `contactsInWorkflow` controls whether contacts already in the workflow continue through the remaining blocks (`keep`) or exit immediately (`exit`). **Scopes:** `automations.write`
- [Get batch items](https://api-docs.omnisend.com/reference/get_batches-batchid-items.md): Get batch items **Scopes:** `products.read`, `contacts.read`, `events.read`
Open Postman collection
- [Get batch information](https://api-docs.omnisend.com/reference/get_batches-batchid.md): Get batch information **Scopes:** `products.read`, `contacts.read`, `events.read`
Open Postman collection
- [Get batches](https://api-docs.omnisend.com/reference/get_batches.md): Get batches **Scopes:** `products.read`, `contacts.read`, `events.read`
Open Postman collection
- [Batches](https://api-docs.omnisend.com/reference/batch.md)
- [Create batch](https://api-docs.omnisend.com/reference/post_batches.md): Batch operations allow for multiple actions of a similar type to be executed in a single request. Utilizing the batch endpoint is recommended to avoid hitting rate limits and to enhance overall performance. Creating batches is an asynchronous process that initiates the creation or updating of the specified items. * POST batch operations to create multiple items simultaneously. * PUT batch operations to apply multiple updates to multiple items. Each batch operation can include up to 100 actions. The required scopes depend on the type of batch operation being performed. **WARNING**: Before sending a batch of **events**, ensure there are no automations configured in Omnisend that could send messages to customers based on the imported data. This could result in duplicate messages being sent to customers. **Scopes:** `products.write`, `contacts.write`, `events.write`
Open Postman collection
- [Get information about brand](https://api-docs.omnisend.com/reference/get_brands-current.md): With this endpoint you can get brand's information. **Scopes:** `brands.read`
Open Postman collection
- [Brands](https://api-docs.omnisend.com/reference/brands.md)
- [Connect brand](https://api-docs.omnisend.com/reference/post_brands-current.md): With this endpoint you can connect your site to Omnisend. Note it's only possible to connect store with [oAuth flow](https://api-docs.omnisend.com/reference/oauth). **Scopes:** `brands.write`
Open Postman collection
- [Delete campaign](https://api-docs.omnisend.com/reference/delete_campaigns-id.md): Delete a campaign. **Scopes:** `campaigns.write`
- [Get campaign UTM settings](https://api-docs.omnisend.com/reference/get_campaigns-id-utm.md): Get UTM tag settings for a campaign. The response shape is the same for all campaign types: `tags` is populated for regular campaigns, `variants` for A/B campaigns. The absent field is omitted. **Scopes:** `campaigns.read`
- [Get campaign](https://api-docs.omnisend.com/reference/get_campaigns-id.md): Get a single campaign by ID. **Scopes:** `campaigns.read`
- [List campaigns](https://api-docs.omnisend.com/reference/get_campaigns.md): List campaigns with filtering, sorting, and cursor-based pagination. **Scopes:** `campaigns.read` **Pagination:** This endpoint uses cursor-based pagination. - Use the `paging.cursors.after` value from the response to get the next page - Use the `paging.cursors.before` value to get the previous page - The `paging.hasMore` field indicates if more results are available - Maximum page size is 250 items. Default: 100
- [Campaigns](https://api-docs.omnisend.com/reference/campaigns.md)
- [Update campaign](https://api-docs.omnisend.com/reference/patch_campaigns-id.md): Update a campaign draft. **Scopes:** `campaigns.write`
- [Resume A/B test](https://api-docs.omnisend.com/reference/post_campaigns-id-ab-test-resume.md): Resume a stopped A/B test. Automatic winner selection becomes eligible to pick this campaign again. Available only while the campaign is in `stopped` status. **Scopes:** `campaigns.write`
- [Stop A/B test](https://api-docs.omnisend.com/reference/post_campaigns-id-ab-test-stop.md): Halt the A/B test winner-selection phase. While stopped, automatic winner selection no longer considers this campaign until it is resumed. Available only while the campaign is in `started` status. **Scopes:** `campaigns.write`
- [Select A/B test winner](https://api-docs.omnisend.com/reference/post_campaigns-id-ab-test-winner.md): Manually pick a variant as the winner. The chosen variant is routed into the send pipeline immediately. **Scopes:** `campaigns.write`
- [Cancel campaign](https://api-docs.omnisend.com/reference/post_campaigns-id-cancel.md): Cancel a campaign and mark it as canceled. **Cancelable source states:** `scheduled` or `paused` (all channel types), or `started` (email only). Any other status (e.g. `draft`, `sent`, `canceled`) returns 409. Supported cases: - Any scheduled or paused campaign (all channel types) - Started email campaigns **Note:** For started campaigns, cancellation is best-effort — messages already in flight may still be delivered. **Scopes:** `campaigns.write`
- [Copy campaign](https://api-docs.omnisend.com/reference/post_campaigns-id-copy.md): Create a draft copy of an existing campaign, copying content, audience, and settings from the original. The copied campaign name will be prefixed with "Copy of: ". **Scopes:** `campaigns.write`
- [Send campaign](https://api-docs.omnisend.com/reference/post_campaigns-id-send.md): Submit a campaign draft for sending. Supports both email and SMS campaigns. Behavior depends on the campaign's sending strategy: - **Immediate**: Campaign will be sent immediately - **Scheduled**: Campaign will be queued for the scheduled time with optional timezone optimization **Scopes:** `campaigns.write`
- [Create campaign](https://api-docs.omnisend.com/reference/post_campaigns.md): Create a new campaign draft. **Scopes:** `campaigns.write`
- [Update campaign UTM settings](https://api-docs.omnisend.com/reference/put_campaigns-id-utm.md): Replace UTM tag settings for a campaign. For regular campaigns send a `tags` object. For A/B test campaigns send a `variants` object. The campaign must be in draft status. **Scopes:** `campaigns.write`
- [Batch remove tags](https://api-docs.omnisend.com/reference/delete_contacts-tags.md): Removes the specified tags from multiple contacts. **Scopes:** `contacts.write`
- [Get contact](https://api-docs.omnisend.com/reference/get_contacts-id.md): Returns the contact with the specified ID. **Scopes:** `contacts.read`
- [List contacts](https://api-docs.omnisend.com/reference/get_contacts.md): Returns a paginated list of contacts filtered by the provided query parameters. **Scopes:** `contacts.read` **Filter restrictions:** - `tag` and `status` cannot be used together in the same request. - `updatedAtFrom` cannot be combined with `email`, `phone`, `status`, `segmentID`, or `tag`.
- [Contacts](https://api-docs.omnisend.com/reference/contacts.md)
- [Update contact by ID](https://api-docs.omnisend.com/reference/patch_contacts-id.md): Updates the contact with the specified ID. **Scopes:** `contacts.write`
- [Update contact by email](https://api-docs.omnisend.com/reference/patch_contacts.md): Updates the contact matching the provided email address. **Scopes:** `contacts.write`
- [Batch add tags](https://api-docs.omnisend.com/reference/post_contacts-tags.md): Adds the specified tags to multiple contacts. **Scopes:** `contacts.write`
- [Create or update existing contact](https://api-docs.omnisend.com/reference/post_contacts.md): Creates a new contact. If a contact with the provided email identifier already exists, it will be updated instead. Returns `201 Created` for new contacts and `200 OK` when an existing contact was updated. **Scopes:** `contacts.write`
- [Get email content](https://api-docs.omnisend.com/reference/get_email-content-id.md): With this endpoint you can get email content by ID. **Scopes:** `email-templates.read`
- [Email Content](https://api-docs.omnisend.com/reference/email-content.md)
- [Render email content](https://api-docs.omnisend.com/reference/post_email-content-id-render.md): With this endpoint you can render email content to HTML by ID. The content is rendered with an empty data context (no contact, no marketing activity). **Scopes:** `email-templates.write`
- [Update email content](https://api-docs.omnisend.com/reference/put_email-content-id.md): With this endpoint you can update (fully replace) email content by ID. The full content structure must be provided in the request body. **Scopes:** `email-templates.write`
- [Delete email template](https://api-docs.omnisend.com/reference/delete_email-templates-id.md): With this endpoint you can delete email template by ID. **Scopes:** `email-templates.write`
- [Get email template](https://api-docs.omnisend.com/reference/get_email-templates-id.md): With this endpoint you can get email template by ID. **Scopes:** `email-templates.read`
- [Get email templates](https://api-docs.omnisend.com/reference/get_email-templates.md): With this endpoint you can get a paginated list of email templates. **Sorting:** Use `sort` and `direction` to control the order of results. Supported sort fields: `createdAt` (default), `name`. Supported directions: `asc`, `desc` (default). **Filtering:** Use `nameContains` to filter templates by name (case-insensitive partial match, max 200 characters) **Pagination:** This endpoint uses cursor-based pagination for efficient traversal of large datasets. - Use the `paging.cursors.after` value from the response to get the next page - Use the `paging.cursors.before` value from the response to get the previous page - The `paging.hasMore` field indicates if more results are available - Do not use both `after` and `before` parameters simultaneously - Maximum page size is 100 items (default 50) - If `limit` is less than 1 or greater than 100, returns 400 Bad Request **Scopes:** `email-templates.read`
- [Email Templates](https://api-docs.omnisend.com/reference/email-templates.md)
- [Render email template](https://api-docs.omnisend.com/reference/post_email-templates-id-render.md): With this endpoint you can render an email template by ID and get the full HTML body for preview purposes. **Scopes:** `email-templates.write`
- [Import email template from HTML](https://api-docs.omnisend.com/reference/post_email-templates-import.md): With this endpoint you can import email template from raw HTML content. The HTML will be parsed, styles extracted, and structured into a template. **Request body size limit:** 1 MB **Scopes:** `email-templates.write`
- [Create email template](https://api-docs.omnisend.com/reference/post_email-templates.md): With this endpoint you can create a new email template. **Scopes:** `email-templates.write`
- [Update email template](https://api-docs.omnisend.com/reference/put_email-templates-id.md): With this endpoint you can update (fully replace) an email template by ID. **Scopes:** `email-templates.write`
- [Delete universal layout](https://api-docs.omnisend.com/reference/delete_email-universal-layouts-id.md): With this endpoint you can delete a universal layout by ID. **Scopes:** `email-templates.write`
- [Get universal layout](https://api-docs.omnisend.com/reference/get_email-universal-layouts-id.md): With this endpoint you can get a universal layout by ID. **Scopes:** `email-templates.read`
- [Get universal layouts](https://api-docs.omnisend.com/reference/get_email-universal-layouts.md): With this endpoint you can get a paginated list of universal layouts. **Sorting:** Items are returned in descending order by creation time (newest first). This is based on the internal document ID which contains a timestamp. **Pagination:** This endpoint uses cursor-based pagination for efficient traversal of large datasets. - Use the `paging.cursors.after` value from the response to get the next page - Use the `paging.cursors.before` value from the response to get the previous page - The `paging.hasMore` field indicates if more results are available - Do not use both `after` and `before` parameters simultaneously - Maximum page size is 250 items (default 100) - If `limit` is less than 1 or greater than 250, returns 400 Bad Request **Filtering:** Use `nameContains` to filter layouts by name (case-insensitive partial match, max 200 characters) **Scopes:** `email-templates.read`
- [Email Universal Layouts](https://api-docs.omnisend.com/reference/email-universal-layouts.md)
- [Create universal layout](https://api-docs.omnisend.com/reference/post_email-universal-layouts.md): With this endpoint you can create a new universal layout. **Scopes:** `email-templates.write`
- [Update universal layout](https://api-docs.omnisend.com/reference/put_email-universal-layouts-id.md): With this endpoint you can update (fully replace) a universal layout by ID. **Scopes:** `email-templates.write`
- [Events](https://api-docs.omnisend.com/reference/events.md)
- [Send Customer event](https://api-docs.omnisend.com/reference/post_events.md): With this endpoint you can send customer events to Omnisend. Customer events are used to track customer behavior and trigger automations based on that behavior. You can either format and send custom customer events or use predefined events. **Scopes:** `events.write`
Open Postman collection
- [added product to cart](https://api-docs.omnisend.com/reference/added-product-to-cart.md)
- [Events Overview](https://api-docs.omnisend.com/reference/events-overview.md)
- [order canceled](https://api-docs.omnisend.com/reference/order-cancelled.md)
- [order fulfilled](https://api-docs.omnisend.com/reference/order-fulfilled.md)
- [order refunded](https://api-docs.omnisend.com/reference/order-refunded.md)
- [ordered product](https://api-docs.omnisend.com/reference/ordered-product.md)
- [paid for order](https://api-docs.omnisend.com/reference/paid-for-order.md)
- [placed order](https://api-docs.omnisend.com/reference/placed-order.md)
- [started checkout](https://api-docs.omnisend.com/reference/started-checkout.md)
- [viewed product](https://api-docs.omnisend.com/reference/viewed-product.md)
- [Delete image](https://api-docs.omnisend.com/reference/delete_images-id.md): With this endpoint you can delete an image by ID. **Scopes:** `images.write`
- [Get image](https://api-docs.omnisend.com/reference/get_images-id.md): With this endpoint you can get a single image by ID. **Scopes:** `images.read`
- [List images](https://api-docs.omnisend.com/reference/get_images.md): With this endpoint you can get a paginated list of images for a brand. **Sorting:** Supported sort fields: `createdAt` (default), `name` Supported directions: `asc`, `desc` (default) **Filtering:** Use `nameContains` to filter images by name (case-insensitive, partial match) **Pagination:** This endpoint uses cursor-based pagination for efficient traversal of large datasets. - Use the `cursors.after` value from the response to get the next page - Use the `cursors.before` value from the response to get the previous page - The `hasMore` field indicates if more results are available - Do not use both `after` and `before` parameters simultaneously - Maximum page size is 250 items (default 100) **Scopes:** `images.read`
- [Images](https://api-docs.omnisend.com/reference/images.md)
- [Upload image file](https://api-docs.omnisend.com/reference/post_images-upload.md): With this endpoint you can upload an image file directly from your computer. **File Requirements:** - Supported formats: JPEG, PNG, GIF, WebP - Maximum file size: 5MB **Scopes:** `images.write`
- [Upload image by URL](https://api-docs.omnisend.com/reference/post_images.md): With this endpoint you can upload an image from a publicly accessible URL. If the name is not provided, the filename will be extracted from the URL. **Scopes:** `images.write`
- [Cookie consent](https://api-docs.omnisend.com/reference/cookie-consent.md)
- [Event tracking](https://api-docs.omnisend.com/reference/event-tracking.md)
- [Javascript snippet](https://api-docs.omnisend.com/reference/javascript-snippet.md)
- [Omnisend forms custom trigger](https://api-docs.omnisend.com/reference/omnisend-forms-custom-trigger.md)
- [Omnisend forms events](https://api-docs.omnisend.com/reference/omnisend-forms-events.md)
- [Authentication](https://api-docs.omnisend.com/reference/authentication.md)
- [Getting started](https://api-docs.omnisend.com/reference/getting-started.md): Start using API and send the first Omnisend API request.
- [HTTP methods](https://api-docs.omnisend.com/reference/http-methods.md)
- [Omnisend MCP Server v2](https://api-docs.omnisend.com/reference/mcp-server-v2.md): Connect Omnisend to MCP clients using the v2 MCP server at mcp.omnisend.com/v2/mcp — with action-specific tools and embedded reference documentation.
- [Omnisend MCP Server](https://api-docs.omnisend.com/reference/mcp-server.md): Connect Omnisend to MCP clients such as Claude, ChatGPT, or Cursor using the Model Context Protocol (MCP).
- [OAuth](https://api-docs.omnisend.com/reference/oauth.md)
- [Overview](https://api-docs.omnisend.com/reference/overview.md)
- [Pagination](https://api-docs.omnisend.com/reference/pagination.md)
- [Rate limit, timeouts, errors](https://api-docs.omnisend.com/reference/rate-limit-timeouts-errors.md)
- [Responses](https://api-docs.omnisend.com/reference/responses.md)
- [Sorting](https://api-docs.omnisend.com/reference/sorting.md)
- [URL encoding](https://api-docs.omnisend.com/reference/url-encoding.md)
- [Delete product category](https://api-docs.omnisend.com/reference/delete_product-categories-categoryid.md): With this endpoint you can delete product category. **Scopes:** `products.write`
Check POSTMAN documentation
- [Get product category](https://api-docs.omnisend.com/reference/get_product-categories-categoryid.md): Get product category by ID. **Scopes:** `products.read`
Check POSTMAN documentation
- [List product categories](https://api-docs.omnisend.com/reference/get_product-categories.md): List products categories **Scopes:** `products.read`
Guide: Sync products catalog, categories
Check POSTMAN documentation
- [Product Categories](https://api-docs.omnisend.com/reference/product-categories.md)
- [Update product category](https://api-docs.omnisend.com/reference/patch_product-categories-categoryid.md): Update product category by ID. **Scopes:** `products.write`
Check POSTMAN documentation
- [Create product category](https://api-docs.omnisend.com/reference/post_product-categories.md): Creates a new product category **Scopes:** `products.write`
Check POSTMAN documentation
- [Delete product](https://api-docs.omnisend.com/reference/delete_products-productid.md): Delete product by ID
Open Postman collection
- [Get product](https://api-docs.omnisend.com/reference/get_products-productid.md): Get product by ID **Scopes:** `products.read`
Open Postman collection
- [List products](https://api-docs.omnisend.com/reference/get_products.md): List products **Scopes:** `products.read`
Guide: Sync products catalog, categories
Open Postman collection
- [Products](https://api-docs.omnisend.com/reference/products.md)
- [Create product](https://api-docs.omnisend.com/reference/post_products.md): Creates a new product **Scopes:** `products.write`
Open Postman collection
- [Replace product](https://api-docs.omnisend.com/reference/put_products-productid.md): Replace product by ID **Scopes:** `products.write`
Open Postman collection
- [Delete segment](https://api-docs.omnisend.com/reference/delete_segments-segmentid.md): 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.
- [Get segment statistics](https://api-docs.omnisend.com/reference/get_segments-segmentid-statistics.md): Returns statistics for a segment, including the total number of matching contacts. **Scopes:** `segments.read`
- [Get segment](https://api-docs.omnisend.com/reference/get_segments-segmentid.md): Returns a segment by its unique identifier. **Scopes:** `segments.read` **Rate Limiting:** This endpoint is rate limited to 100 requests per minute.
- [List segments](https://api-docs.omnisend.com/reference/get_segments.md): 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.
- [Segments](https://api-docs.omnisend.com/reference/segments.md)
- [Create segment](https://api-docs.omnisend.com/reference/post_segments.md): Creates a new segment. **Scopes:** `segments.write` **Rate Limiting:** This endpoint is rate limited to 15 requests per minute. # Segmentation examples ## Event filter fields reference For `entity: "event"` conditions, each filter in the `filters` array supports the following fields: | Field | Required | Description | |---|---|---| | `name` | Yes | Event name (e.g., `"placed order"`, `"opened message"`) | | `operator` | Yes | `has` or `hasNot` | | `count` | Yes | `atLeast` or `equals` | | `value` | Yes | Integer threshold (e.g., `1`) | | `origin` | No | Event source (e.g., `"shopify"`, `"omnisend"`). See the `origin` note below. | | `period` | No | Time window — see period operators below | | `filters` | No | Array of property sub-filters on the event payload | | `junction` | No | `and` or `or` — logical operator for `filters` | > **`origin` is usually optional.** Most events belong to a single origin, so the API resolves it for you. > You only need to specify `origin` when an event exists under multiple origins — otherwise the API returns an error with the list of valid values to choose from. ### Period operators The `period` object is optional on every event filter. When omitted, the filter matches across all time. #### Relative periods Use `value` (positive integer) + `unit` (`days` \| `weeks` \| `months` \| `years`). | `operator` | Meaning | Example JSON | |---|---|---| | `inTheLast` | Event occurred within the last N units | `{ "operator": "inTheLast", "unit": "days", "value": 7 }` | | `notInTheLast` | Event did **not** occur within the last N units | `{ "operator": "notInTheLast", "unit": "months", "value": 3 }` | #### Absolute periods Use ISO 8601 date strings (`YYYY-MM-DD`). | `operator` | Meaning | Example JSON | |---|---|---| | `equals` | Event occurred on an exact date | `{ "operator": "equals", "value": "2026-01-13" }` | | `before` | Event occurred before a date (exclusive) | `{ "operator": "before", "value": "2026-01-13" }` | | `after` | Event occurred after a date (exclusive) | `{ "operator": "after", "value": "2026-04-01" }` | | `between` | Event occurred within a date range (inclusive) | `{ "operator": "between", "valueFrom": "2025-01-01", "valueTo": "2025-01-31" }` | --- ## Contact filter properties reference For `entity: "contact"` conditions, valid `property` values are: - Text: `email`, `phoneNumber`, `firstName`, `lastName`, `gender`, `country`, `state`, `city`, `address`, `postalCode`, `lastDetectedCity`, `lastDetectedCountry`, `customerLifecycleStage` - List: `tags`, `consent` - Number: `averageOrderValue`, `totalSpent` - Date: `dateAdded` - Subscription status: `subscriptionStatus` - Variadic: `birthday` (`valueType` can be `date` or `text`), `custom` (`valueType` can be `text`, `number`, `bool`, or `date`) > **Important**: > - Use `tags` (plural), not `tag`. > - When `property` is `custom`, provide both `name` and `valueType`. This section provides a deeper technical reference for building complex segments using the API segment model. --- Example: Combining contact and event conditions (AND logic)
Shows how to combine different entity types (`contact` and `event`) within a single group. **AND logic is automatically inferred** between multiple conditions inside the `conditions` array.
```json { "name": "Combining Contact and Event Conditions", "conditionGroups": [ { "conditions": [ { "entity": "contact", "junction": "and", "filters": [ { "operator": "anyOf", "property": "country", "value": ["US", "Canada"] }, { "channels": ["email"], "operator": "equals", "property": "subscriptionStatus", "value": "subscribed" } ] }, { "entity": "event", "junction": "and", "filters": [ { "count": "atLeast", "name": "opened message", "operator": "has", "period": { "operator": "inTheLast", "unit": "days", "value": 7 }, "value": 1 } ] } ] } ] } ``` **Target audience:** Contacts who are from the US and subscribed to the email channel, **AND** who have opened at least one message in the last 7 days.
--- Example: Multiple event conditions in a single group
Multiple `event` conditions within the same group, with an **OR** junction on filters within one condition.
```json { "name": "Multiple Event Conditions in a Group", "conditionGroups": [ { "conditions": [ { "entity": "event", "junction": "and", "filters": [ { "count": "atLeast", "name": "opened message", "operator": "has", "period": { "operator": "inTheLast", "unit": "days", "value": 7 }, "value": 1 } ] }, { "entity": "event", "junction": "or", "filters": [ { "count": "atLeast", "name": "clicked message", "operator": "has", "value": 1 }, { "count": "equals", "name": "marked message as spam", "operator": "has", "value": 0 } ] }, { "entity": "contact", "junction": "and", "filters": [ { "operator": "anyOf", "property": "country", "value": ["US", "Mexico"] } ] } ] } ] } ``` **Target audience:** Contacts from the US who have opened a message in the last 7 days, **AND** who have either clicked a message **OR** have never marked a message as spam.
--- Example: Multiple condition groups (OR logic)
Demonstrates the **OR** relationship between different `conditionGroups`. A contact is included if they match any of the groups.
```json { "name": "Multiple Condition Groups", "conditionGroups": [ { "conditions": [ { "entity": "contact", "junction": "and", "filters": [ { "operator": "anyOf", "property": "tags", "value": ["vip", "imported"] } ] }, { "entity": "event", "junction": "and", "filters": [ { "count": "atLeast", "name": "placed order", "operator": "has", "origin": "shopify", "value": 1 } ] } ] }, { "conditions": [ { "entity": "contact", "junction": "or", "filters": [ { "operator": "anyOf", "property": "country", "value": ["US", "Canada"] }, { "channels": ["email"], "operator": "equals", "property": "subscriptionStatus", "value": "subscribed" } ] } ] } ] } ``` **Target audience:** Contacts who are either (tagged as "vip" **AND** have placed at least one Shopify order) **OR** (are from the US **OR** are subscribed to the email channel).
--- Example: Filtering by contact properties
Common contact property filters, including text matching, subscription status, and location.
```json { "name": "Contact Property Filters", "conditionGroups": [ { "conditions": [ { "entity": "contact", "junction": "and", "filters": [ { "operator": "anyOf", "property": "firstName", "value": ["Jane", "John"] }, { "operator": "contains", "property": "lastName", "value": ["Smith"] }, { "channels": ["email", "browserPush", "sms"], "operator": "equals", "property": "subscriptionStatus", "value": "subscribed" }, { "operator": "anyOf", "property": "tags", "value": ["vip"] }, { "operator": "noneOf", "property": "tags", "value": ["excluded"] }, { "operator": "anyOf", "property": "country", "value": ["US", "Canada"] }, { "operator": "doesNotExist", "property": "postalCode" } ] }, { "entity": "contact", "junction": "or", "filters": [ { "operator": "anyOf", "property": "gender", "value": ["f"] }, { "operator": "anyOf", "property": "lastDetectedCity", "value": ["New York"] } ] } ] } ] } ``` **Target audience:** Contacts who match all the primary criteria (named Jane/John Smith, subscribed on all channels, tagged "vip", not tagged "excluded", from US, no zip code) **AND** who are also either female **OR** located in New York.
--- Example: Filtering by birthday
Date-based filtering for birthdays, including date ranges, upcoming anniversaries, and month matching.
```json { "name": "Birthday Filters", "conditionGroups": [ { "conditions": [ { "entity": "contact", "junction": "or", "filters": [ { "operator": "between", "property": "birthday", "valueFrom": "2000-01-01", "valueTo": "2005-01-15", "valueType": "date" }, { "operator": "anniversaryIsInTheNext", "property": "birthday", "unit": "days", "value": 7, "valueType": "date" }, { "operator": "contains", "property": "birthday", "value": ["-05-"], "valueType": "text" } ] } ] } ] } ``` **Target audience:** Contacts whose birth date falls between January 1, 2000 and January 15, 2005, **OR** whose birthday anniversary is in the next 7 days, **OR** whose birthday is in the month of May.
--- Example: Lifecycle stages and computed metrics
Filtering contacts based on their RFM lifecycle stage and financial metrics like average order value.
```json { "name": "Lifecycle and Metrics", "conditionGroups": [ { "conditions": [ { "entity": "contact", "junction": "and", "filters": [ { "property": "customerLifecycleStage", "operator": "anyOf", "value": ["champions", "loyalists", "highPotential"] }, { "operator": "moreThan", "property": "averageOrderValue", "value": 50 }, { "operator": "between", "property": "totalSpent", "valueFrom": 100, "valueTo": 500 } ] } ] } ] } ``` **Target audience:** High-value contacts (Champions, Loyalists, or High Potential) with an average order value over 50 and a total lifetime spend between 100 and 500.
--- Example: Filtering by custom fields
Filtering by user-defined custom fields, which require an explicit `valueType`.
```json { "name": "Custom Field Filters", "conditionGroups": [ { "conditions": [ { "entity": "contact", "junction": "and", "filters": [ { "name": "is_vip", "operator": "equals", "property": "custom", "value": true, "valueType": "bool" }, { "name": "favorite_category", "operator": "anyOf", "property": "custom", "value": ["Electronics"], "valueType": "text" }, { "name": "lifetime_orders", "operator": "moreThan", "property": "custom", "value": 5, "valueType": "number" }, { "name": "first_purchase_date", "operator": "inTheLast", "property": "custom", "unit": "days", "value": 30, "valueType": "date" } ] } ] } ] } ``` **Target audience:** Contacts who are marked as VIP in custom fields, whose favorite category is Electronics, who have more than 5 lifetime orders, and who made their first purchase in the last 30 days.
--- Example: Behavioral events (engagement)
Behavioral segmentation based on message engagement (clicks, opens) and page views.
```json { "name": "Behavioral Engagement", "conditionGroups": [ { "conditions": [ { "entity": "event", "junction": "and", "filters": [ { "count": "atLeast", "name": "clicked message", "operator": "has", "value": 1 }, { "count": "atLeast", "name": "opened message", "operator": "has", "period": { "operator": "inTheLast", "unit": "days", "value": 7 }, "value": 1 }, { "count": "equals", "name": "marked message as spam", "operator": "has", "period": { "operator": "before", "value": "2026-01-13" }, "value": 0 } ] } ] } ] } ``` **Target audience:** Contacts who have clicked a message, opened a message in the last 7 days, viewed a page in the last month, **AND** have never marked a message as spam (prior to Jan 13, 2026).
--- Example: Platform event property filters
Deep filtering on properties of platform-defined events, such as Shopify order details. > **Note**: Use the `[]` wildcard syntax to match any element within an array. This can be chained for nested arrays; for example, `raw.fulfillments.[].line_items.[].title` matches any line item title within any fulfillment in the order. > **Important**: When using events defined by other platforms (e.g., Shopify, Omnisend), you must use predefined event names and their specific properties. Filter values must strictly match the predefined `valueType` for each property.
```json { "name": "Platform Event Filters", "conditionGroups": [ { "conditions": [ { "entity": "event", "junction": "and", "filters": [ { "count": "atLeast", "name": "placed order", "operator": "has", "origin": "shopify", "value": 1, "filters": [ { "operator": "moreThan", "property": "raw._total_price", "value": 50 }, { "operator": "contains", "property": "raw.fulfillments.[].line_items.[].title", "value": ["Book"] } ], "junction": "and" } ] } ] } ] } ``` **Target audience:** Contacts who have placed at least one Shopify order where the total price was over 50 **AND** the order contained an item with "Book" in the title.
--- Example: Custom event property filters
Filtering custom events based on their specific properties. > **Important**: Mandatory `valueType` must be provided for every property filter (e.g., `text`, `number`). The event and its properties must have been sent at least once before they can be used in a segment filter.
```json { "name": "Custom Event Filters", "conditionGroups": [ { "conditions": [ { "entity": "event", "junction": "and", "filters": [ { "count": "atLeast", "name": "app_feature_used", "origin": "my_mobile_app", "operator": "has", "value": 5, "junction": "and", "filters": [ { "operator": "equals", "property": "feature_name", "value": ["dark_mode_toggle"], "valueType": "text" }, { "operator": "moreThan", "property": "session_duration", "value": 120, "valueType": "number" } ] } ] } ] } ] } ``` **Target audience:** Contacts who have used the "dark_mode_toggle" feature in the custom "my_mobile_app" at least 5 times, where the session duration was greater than 120 seconds.
--- Example: Filtering events by date range
Filtering events using a specific date range with the `between` period operator. Uses `valueFrom` and `valueTo` to define the time window.
```json { "name": "Shopify Orders in Date Range", "conditionGroups": [ { "conditions": [ { "entity": "event", "junction": "and", "filters": [ { "count": "atLeast", "name": "placed order", "operator": "has", "origin": "shopify", "value": 1, "period": { "operator": "between", "valueFrom": "2025-01-01", "valueTo": "2025-01-31" }, "filters": [ { "operator": "contains", "property": "raw.line_items.[].title", "value": ["Summer T-Shirt"], "valueType": "text" } ], "junction": "and" } ] } ] } ] } ``` **Target audience:** Contacts who placed at least one Shopify order between January 1 and January 31, 2025, where the order contained an item with "Summer T-Shirt" in the title.
--- Example: Filtering events by exact date
Filtering contacts who did not view a page on a specific date using the `equals` period operator.
```json { "name": "Did Not View Page on April 13", "conditionGroups": [ { "conditions": [ { "entity": "event", "junction": "and", "filters": [ { "count": "atLeast", "name": "viewed page", "operator": "hasNot", "value": 1, "period": { "operator": "equals", "value": "2026-04-13" } } ] } ] } ] } ``` **Target audience:** Contacts who did not view a page on April 13, 2026.
--- - [Events and Properties Reference](/docs/segments-events-properties) — Explore available event names and properties to build powerful segment filters.
- [Update segment](https://api-docs.omnisend.com/reference/put_segments-segmentid.md): 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](post_segments). See the Create segment endpoint for detailed examples of condition groups, filters, and advanced segmentation patterns.