# Omnisend API Documentation > API reference and technical documentation for creating your Omnisend integration. ## Guides - [How to: connect the store](https://api-docs.omnisend.com/docs/how-to-connect-the-store.md) - [How to: sync historic orders](https://api-docs.omnisend.com/docs/how-to-sync-historic-orders.md) - [How to: sync contacts](https://api-docs.omnisend.com/docs/how-to-sync-contacts.md) - [How to: sync products catalog, categories](https://api-docs.omnisend.com/docs/how-to-sync-products-catalog-categories.md) - [How to: send events rest api](https://api-docs.omnisend.com/docs/how-to-send-events-rest-api.md) - [How to: enable javascript snippet](https://api-docs.omnisend.com/docs/how-to-enable-javascript-snippet.md) - [How to: track cart events(snippet)](https://api-docs.omnisend.com/docs/how-to-track-cart-events-snippet.md) - [How to: enable cart/checkout abandonment](https://api-docs.omnisend.com/docs/how-to-enable-cart-abandonment.md) - [How to: enable product abandonment](https://api-docs.omnisend.com/docs/how-to-enable-product-abandonment.md) - [How to: enable order confirmation flow](https://api-docs.omnisend.com/docs/how-to-enable-order-confirmation-flow.md) - [How to: track Omnisend forms activity using JavaScript](https://api-docs.omnisend.com/docs/how-to-track-omnisend-forms-activity-using-javascript.md) - [How to: send custom events to trigger custom automations](https://api-docs.omnisend.com/docs/how-to-send-custom-events-to-trigger-custom-automations.md) - [How to: send cookie consent to Omnisend](https://api-docs.omnisend.com/docs/how-to-integrate-cookie-consent.md) - [WordPress Plugin Integration](https://api-docs.omnisend.com/docs/wordpress-plugin-integration.md) - [Migrate from v5 to v2026-03-15](https://api-docs.omnisend.com/docs/migrate-from-v5-to-v2026-03-15.md) - [Migrate from v3 to v2026-03-15](https://api-docs.omnisend.com/docs/migrate-from-v3-to-v2026-03-15.md) - [Migrate from v3 with an AI agent](https://api-docs.omnisend.com/docs/migrate-from-v3-with-an-ai-agent.md) - [How to: integrate custom store](https://api-docs.omnisend.com/docs/how-to-integrate-custom-store.md) - [Create your own app](https://api-docs.omnisend.com/docs/create-your-own-app.md) - [How to create an account and log in](https://api-docs.omnisend.com/docs/how-to-create-account-and-login.md) - [How to send an email campaign](https://api-docs.omnisend.com/docs/how-to-send-email-campaign.md) - [How to update an email campaign](https://api-docs.omnisend.com/docs/how-to-update-email-campaign.md) - [How to boost a sent campaign](https://api-docs.omnisend.com/docs/how-to-boost-a-sent-campaign.md) - [How to configure UTM tags for campaigns](https://api-docs.omnisend.com/docs/how-to-configure-utm-tags-for-campaigns.md) - [How to send an A/B test campaign](https://api-docs.omnisend.com/docs/how-to-send-ab-test-campaign.md) - [How to send an SMS campaign](https://api-docs.omnisend.com/docs/how-to-send-sms-campaign.md) - [How to set up a booster for a new campaign](https://api-docs.omnisend.com/docs/how-to-set-up-a-booster-for-a-new-campaign.md) - [Segmentation Events & Properties Reference](https://api-docs.omnisend.com/docs/segments-events-properties.md) - [How to configure UTM tags for automations](https://api-docs.omnisend.com/docs/how-to-configure-utm-tags-for-automations.md) - [How to create an abandoned checkout automation](https://api-docs.omnisend.com/docs/how-to-create-abandoned-checkout-automation.md) - [How to send webhooks from automation workflows](https://api-docs.omnisend.com/docs/how-to-send-webhooks-from-automations.md) - [How to use splits and A/B testing in automations](https://api-docs.omnisend.com/docs/how-to-use-splits-and-ab-testing-in-automations.md) ## API Reference - [Overview](https://api-docs.omnisend.com/reference/overview.md) - [Getting started](https://api-docs.omnisend.com/reference/getting-started.md): Start using API and send the first Omnisend API request. - [Authentication](https://api-docs.omnisend.com/reference/authentication.md) - [Responses](https://api-docs.omnisend.com/reference/responses.md) - [URL encoding](https://api-docs.omnisend.com/reference/url-encoding.md) - [Sorting](https://api-docs.omnisend.com/reference/sorting.md) - [Pagination](https://api-docs.omnisend.com/reference/pagination.md) - [HTTP methods](https://api-docs.omnisend.com/reference/http-methods.md) - [Rate limit, timeouts, errors](https://api-docs.omnisend.com/reference/rate-limit-timeouts-errors.md) - [OAuth](https://api-docs.omnisend.com/reference/oauth.md) - [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). - [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. - [Javascript snippet](https://api-docs.omnisend.com/reference/javascript-snippet.md) - [Event tracking](https://api-docs.omnisend.com/reference/event-tracking.md) - [Omnisend forms events](https://api-docs.omnisend.com/reference/omnisend-forms-events.md) - [Omnisend forms custom trigger](https://api-docs.omnisend.com/reference/omnisend-forms-custom-trigger.md) - [Cookie consent](https://api-docs.omnisend.com/reference/cookie-consent.md) - [Events Overview](https://api-docs.omnisend.com/reference/events-overview.md) - [added product to cart](https://api-docs.omnisend.com/reference/added-product-to-cart.md) - [started checkout](https://api-docs.omnisend.com/reference/started-checkout.md) - [placed order](https://api-docs.omnisend.com/reference/placed-order.md) - [paid for order](https://api-docs.omnisend.com/reference/paid-for-order.md) - [ordered product](https://api-docs.omnisend.com/reference/ordered-product.md) - [order refunded](https://api-docs.omnisend.com/reference/order-refunded.md) - [order fulfilled](https://api-docs.omnisend.com/reference/order-fulfilled.md) - [order canceled](https://api-docs.omnisend.com/reference/order-cancelled.md) - [viewed product](https://api-docs.omnisend.com/reference/viewed-product.md) - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Open Postman collection - [Create custom event metadata](https://api-docs.omnisend.com/reference/post_event_metadata.md): Declares a new brand-custom event schema. The event identity is the combination of `name` and `origin`; `displayName` and at least one top-level property are required. Optional metadata fields must be omitted rather than sent as null. The created event is returned with every node flagged `explicitlyDefined`. **Scopes:** `events.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Update custom event metadata](https://api-docs.omnisend.com/reference/put_event_metadata.md): Merges changes into an existing brand-custom event, identified by `name` and `origin`. Only supplied fields are applied: omitted metadata and omitted properties are preserved, and no property is deleted. The type of an already explicitly-defined property cannot change. Optional metadata fields must be omitted rather than sent as null. The merged event is returned. **Scopes:** `events.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Query events metadata](https://api-docs.omnisend.com/reference/post_event_metadata_query.md): Returns event metadata entries for the given category, optionally filtered by event names and/or origins. **Supported categories:** `automations`, `events`, `segments` **API version scoping:** The events a category exposes depend on the requested `Omnisend-Version`; a date between releases resolves to the nearest earlier supported version. Brand-custom events are not version-scoped. **Event name filtering:** When `events` are provided, only events whose system name matches one of the given values are returned (exact, case-sensitive match). **Origin filtering:** By default the response includes Omnisend events together with events from every origin the brand has data for. When the brand is connected to a specific origin, that origin's events are included as well. The optional `origins` filter narrows the response to the requested origins (OR-combined) within what the brand can already see; an origin the brand is not entitled to is never returned, even if requested. **Property inclusion:** When `includeProperties` is `true`, each event item includes its nested property tree, keyed by property name, with struct properties nesting their children under a recursive `properties` map. When omitted or `false`, only event-level metadata (`name`, `displayName`, `origins`) is returned. **Custom event exclusion:** When `excludeCustomEvents` is `true`, brand-custom events are omitted. When omitted or `false`, custom events are included. Set this to `true` when only well-known standard events are needed, for a more predictable response size. **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Contacts](https://api-docs.omnisend.com/reference/contacts.md) - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. **Filter restrictions:** - `tag` and `status` cannot be used together in the same request. - `updatedAtFrom` cannot be combined with `email`, `phone`, `status`, `segmentID`, or `tag`. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Update contact by email](https://api-docs.omnisend.com/reference/patch_contacts.md): Updates the contact matching the provided email address. **Scopes:** `contacts.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Get contact](https://api-docs.omnisend.com/reference/get_contacts-id.md): Returns the contact with the specified ID. **Scopes:** `contacts.read` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Update contact by ID](https://api-docs.omnisend.com/reference/patch_contacts-id.md): Updates the contact with the specified ID. **Scopes:** `contacts.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Batch remove tags](https://api-docs.omnisend.com/reference/delete_contacts-tags.md): Removes the specified tags from contacts selected by contact IDs, emails, phone numbers or a segment. At least one of `contactIDs`, `emails`, `phones` or `segmentID` is required. Selectors can be combined and are applied additively — the tags are removed from the union of all matched contacts: every contact in `contactIDs`, every contact matched by an address in `emails`, every contact matched by a number in `phones` and every member of `segmentID`. A contact matched by more than one selector is processed once. Emails and phones with no matching contact are silently ignored. Untagging is performed asynchronously, so the tags may not disappear immediately. **Scopes:** `contacts.write` **Rate Limiting:** This endpoint is rate limited to 60 requests per minute. - [Batch add tags](https://api-docs.omnisend.com/reference/post_contacts-tags.md): Adds the specified tags to contacts selected by contact IDs, emails, phone numbers or a segment. At least one of `contactIDs`, `emails`, `phones` or `segmentID` is required. Selectors can be combined and are applied additively — the union of all matched contacts is tagged: every contact in `contactIDs`, every contact matched by an address in `emails`, every contact matched by a number in `phones` and every member of `segmentID`. A contact matched by more than one selector is tagged once. Emails and phones with no matching contact are silently ignored. Tagging is performed asynchronously, so the tags may not be visible immediately. **Scopes:** `contacts.write` **Rate Limiting:** This endpoint is rate limited to 60 requests per minute. - [Brands](https://api-docs.omnisend.com/reference/brands.md) - [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 - [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 - [Products](https://api-docs.omnisend.com/reference/products.md) - [List products](https://api-docs.omnisend.com/reference/get_products.md): List products **Scopes:** `products.read` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Guide: Sync products catalog, categories
Open Postman collection - [Create product](https://api-docs.omnisend.com/reference/post_products.md): Creates a new product **Scopes:** `products.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Open Postman collection - [Delete product](https://api-docs.omnisend.com/reference/delete_products-productid.md): Delete product by ID **Scopes:** `products.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Open Postman collection - [Get product](https://api-docs.omnisend.com/reference/get_products-productid.md): Get product by ID **Scopes:** `products.read` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Open Postman collection - [Replace product](https://api-docs.omnisend.com/reference/put_products-productid.md): Replace product by ID **Scopes:** `products.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Open Postman collection - [Product Categories](https://api-docs.omnisend.com/reference/product-categories.md) - [List product categories](https://api-docs.omnisend.com/reference/get_product-categories.md): List products categories **Scopes:** `products.read` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Guide: Sync products catalog, categories
Check POSTMAN documentation - [Create product category](https://api-docs.omnisend.com/reference/post_product-categories.md): Creates a new product category **Scopes:** `products.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Check POSTMAN documentation - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Check POSTMAN documentation - [Update product category](https://api-docs.omnisend.com/reference/patch_product-categories-categoryid.md): Update product category by ID. **Scopes:** `products.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Check POSTMAN documentation - [Batches](https://api-docs.omnisend.com/reference/batch.md) - [Get batches](https://api-docs.omnisend.com/reference/get_batches.md): Get batches **Scopes:** `products.read`, `contacts.read`, `events.read` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Open Postman collection - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Open Postman collection - [Get batch items](https://api-docs.omnisend.com/reference/get_batches-batchid-items.md): Get batch items **Scopes:** `products.read`, `contacts.read`, `events.read` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.
Open Postman collection - [Campaigns](https://api-docs.omnisend.com/reference/campaigns.md) - [List campaigns with filtering, sorting, and cursor pagination](https://api-docs.omnisend.com/reference/get_campaigns.md): List campaigns with filtering, sorting, and cursor-based pagination. **Scopes:** `campaigns.read` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. **Filtering & sorting:** Supported query parameters: `nameContains`, `status`, `channel`, `type`, `parentCampaignID`, `createdAtFrom`/`createdAtTo`, `updatedAtFrom`/`updatedAtTo`, `sort`, `direction`, `limit`, `after`, `before`. Only these documented parameters are accepted; any unknown parameter returns 400. - `sort` accepts `createdAt`, `updatedAt`, or `name`; `direction` (`asc`/`desc`) is only valid together with `sort`. **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 - Do not send `after` and `before` together, and keep filters and sorting unchanged while paginating with a cursor - [Create campaign](https://api-docs.omnisend.com/reference/post_campaigns.md): Create a new campaign draft. **Boosters (`type: booster`):** - The parent campaign (`boosterSettings.campaignID`) must be a regular email campaign in 'draft' or 'sent' status; 'scheduled' and 'started' parents return 409. - Each parent campaign supports at most one booster; creating another returns 409. Delete the existing booster first to replace it. - `sendingSettings` is only allowed when the parent is already sent; for a draft parent provide `boosterSettings.delay` instead (max 240 hours) and the booster is scheduled automatically when the parent sends. **Scopes:** `campaigns.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Delete campaign](https://api-docs.omnisend.com/reference/delete_campaigns-id.md): Delete a campaign. **Scopes:** `campaigns.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Get campaign](https://api-docs.omnisend.com/reference/get_campaigns-id.md): Get a single campaign by ID. **Scopes:** `campaigns.read` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Update campaign (draft status only)](https://api-docs.omnisend.com/reference/patch_campaigns-id.md): Update a campaign draft. Only campaigns in 'draft' status can be updated; any other status returns 409. To change a campaign that is no longer a draft, copy it and edit the new draft copy. **Scopes:** `campaigns.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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 copy is a new draft campaign with its own ID; the original campaign is left unchanged. The copied campaign name will be prefixed with "Copy of: ". **Scopes:** `campaigns.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Send campaign](https://api-docs.omnisend.com/reference/post_campaigns-id-send.md): Submit a campaign draft for sending. Only campaigns in 'draft' status can be sent; to send a campaign again, copy it and send the copy. 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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Send campaign test email](https://api-docs.omnisend.com/reference/post_campaigns-id-test-email.md): Render the campaign draft and email it to up to 5 recipients so the merchant (or their AI tool) can preview it without leaving the API. The test uses the campaign's saved subject, sender, and content; only email campaigns are supported. **Scopes:** `campaigns.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Segments](https://api-docs.omnisend.com/reference/segments.md) - [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. - [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. - [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](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. - [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. - [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` **Rate Limiting:** This endpoint is rate limited to 100 requests per minute. - [Email Content](https://api-docs.omnisend.com/reference/email-content.md) - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 40 requests per minute. - [Email Templates](https://api-docs.omnisend.com/reference/email-templates.md) - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 40 requests per minute. - [Email Universal Layouts](https://api-docs.omnisend.com/reference/email-universal-layouts.md) - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Images](https://api-docs.omnisend.com/reference/images.md) - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Reports](https://api-docs.omnisend.com/reference/reports.md) - [Generate report](https://api-docs.omnisend.com/reference/post_analytics-reports.md): Returns aggregated marketing analytics grouped by message send date. Covers delivery, engagement, and revenue attribution metrics for campaigns and automations. Supports optional dimensions (timestamp, channel, activity), filters, and up to 4 queries per request. **Scopes:** `analytics.read` **Rate Limiting:** This endpoint is rate limited to 10 requests per minute and 55 requests per 24 hours. Rate limits apply per brand. See [Rate limits](https://api-docs.omnisend.com/reference/reports#rate-limits). - [Statistics](https://api-docs.omnisend.com/reference/statistics.md) - [Generate report](https://api-docs.omnisend.com/reference/post_analytics-statistics.md): Returns aggregated marketing analytics grouped by event date (when opens, clicks, orders actually occurred). Covers delivery, engagement, revenue attribution, and audience growth metrics. Requires a timestamp dimension. Supports a rich set of dimensions (client, click, subscription, deliverability) and up to 4 queries per request. **Scopes:** `analytics.read` **Rate Limiting:** This endpoint is rate limited to 10 requests per minute and 55 requests per 24 hours. Rate limits apply per brand. See [Rate limits](https://api-docs.omnisend.com/reference/statistics#rate-limits). - [Automations](https://api-docs.omnisend.com/reference/automations.md) - [List automation workflows](https://api-docs.omnisend.com/reference/get_automations.md): List automation workflows with filtering, sorting, and cursor-based pagination. **Scopes:** `automations.read` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. **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 - [Create automation workflow](https://api-docs.omnisend.com/reference/post_automations.md): Create a new automation workflow. **Scopes:** `automations.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. ## 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"} ] } ```
- [Delete automation workflow](https://api-docs.omnisend.com/reference/delete_automations-id.md): Delete a single automation workflow by ID. This operation is idempotent — deleting a non-existent automation returns a success response. **Scopes:** `automations.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Get automation workflow](https://api-docs.omnisend.com/reference/get_automations-id.md): Get a single automation workflow by ID. **Scopes:** `automations.read` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Patch automation workflow](https://api-docs.omnisend.com/reference/patch_automations-id.md): Partially update an automation workflow. Only the fields provided in the request body are updated. Enabled automations cannot be patched. Disable the automation via `POST /automations/{id}/disable`, make changes, 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`). Enable/disable state is controlled exclusively via the `/automations/{id}/enable` and `/automations/{id}/disable` endpoints. `trigger` sub-fields (condition, audienceFilterGroup, inactivitySettings) are patched individually — each provided sub-field replaces the corresponding sub-field in full. `exitConditions` are **replaced in full** when provided. `blocks` are patched individually. **Scopes:** `automations.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. ## Audience filter group examples The `trigger.audienceFilterGroup` field in PATCH requests replaces the existing audience filter group in full (or sets it for the first time). Omit it to leave the existing audience filter group unchanged. ### 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` sits inside `trigger` in the PATCH request body, alongside `condition` and `inactivitySettings`: ```json { "trigger": { "audienceFilterGroup": { ... } } } ``` Each example below shows only the `audienceFilterGroup` value — slot it into the skeleton above.
Replace audience filter without touching trigger event or blocks ```json { "logicalOperator": "or", "filters": [ {"field": "tag", "operator": "eq", "value": "vip"}, {"field": "tag", "operator": "eq", "value": "beta"} ] } ```
Narrow to US women ```json { "logicalOperator": "and", "filters": [ {"field": "country", "operator": "eq", "value": "US"}, {"field": "gender", "operator": "eq", "value": "f"} ] } ```
Swap a segment-based audience for a tag-based one ```json { "logicalOperator": "and", "filters": [ {"field": "tag", "operator": "eq", "value": "vip"}, {"field": "tag", "operator": "neq", "value": "beta-churned"} ] } ```
- [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Get UTM tags for an automation block](https://api-docs.omnisend.com/reference/get_automations-id-blocks-blockid-utm.md): Retrieve UTM tracking tags for a specific send-action block. Missing or cleared tags are returned with their default values. **Scopes:** `automations.read` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Copy automation workflow](https://api-docs.omnisend.com/reference/post_automations-id-copy.md): Create a copy of an existing automation workflow. The copy is always created in a disabled state, regardless of the source automation's status. The request body is optional. When provided, you can specify a custom name for the copy. When omitted (or when name is empty), the copy is named "Copy of: ". **Scopes:** `automations.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [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` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Get aggregated UTM tags for all blocks](https://api-docs.omnisend.com/reference/get_automations-id-utm.md): Retrieve UTM tracking tags for all send-action blocks in an automation. Each block's tags include default-value synthesis for missing fields. **Scopes:** `automations.read` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute. - [Send test email](https://api-docs.omnisend.com/reference/post_automations-id-blocks-blockid-test-email.md): Send the saved email content of a specific email block as a test email to up to 5 recipients. The email is rendered and delivered asynchronously. **Scopes:** `automations.write` **Rate Limiting:** This endpoint is rate limited to 400 requests per minute.