> ## Documentation Index > Fetch the complete documentation index at: https://moengage.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update Campaign (V5) > Updates individual components of a campaign draft. **Campaign publishing is not yet available in V5.** This endpoint only supports updating draft components. To publish campaigns, use the V1 API at `PATCH /core-services/v1/campaigns/{campaign_id}` in the interim. Publishing via V5 will be available in a future release. Send a `PATCH` request without a `status` key in the body. The API merges each submitted component into the existing draft, then validates the full merged state (`DRAFT_PATCH`). After all individual components pass validation, cross-component checks run on the combined result. Only the fields you include in the request body are updated. Fields you omit retain their current values. For the full field reference per delivery type, see the [Create Campaign API](/docs/api/campaigns/create-campaign). #### Update restrictions by campaign state | Campaign state | Editable fields | Non-editable fields | | :------------------------------------------------------------ | :--------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | | **DRAFT** | All fields | — | | **SCHEDULED:** One-time (no instance sent) | All fields | `scheduling_type` | | **SCHEDULED:** Periodic or Event-triggered (no instance sent) | All fields | `scheduling_type` | | **ACTIVE** | All fields except those listed as non-editable | `trigger_condition`, `segmentation_details`, `conversion_goal_details`, `scheduling_type`, `scheduling_start_date` | | **STOPPED** or **ARCHIVED** | — | All fields (no updates allowed) | For **Event-triggered campaigns**, updated content is cached and takes up to 30 minutes to take effect. #### Rate Limits | Rate Limit Name | Rate Limit | | :------------------------- | :--------------------------------------------------------------------------------- | | Update campaign per second | The total number of update campaign requests per second per client allowed is 10. | | Update campaign per minute | The total number of update campaign requests per minute per client allowed is 100. | | Update campaign per hour | The total number of update campaign requests per hour per client allowed is 6000. | **Notes** * Breaching the limits will reject the request. * Per-hour and per-day limits use a rolling window of the last 1 hour and last 24 hours respectively. ## OpenAPI ````yaml /api/campaigns/campaign-draft.yaml patch /v5/campaigns/{campaign_id} openapi: 3.0.3 info: title: MoEngage Campaigns API version: '2025-11-20' description: > The Campaigns V5 API manages the draft campaign lifecycle — draft creation, incremental updates, validation, test sends, and post-publish management. **Note:** Campaign publishing is not yet supported in V5. To publish campaigns, use the V1 API (`PATCH /core-services/v1/campaigns/{campaign_id}`) in the interim. **Supported channels:** - Push (Android, iOS, Web) - Email **Supported delivery types:** - ONE_TIME - PERIODIC - EVENT_TRIGGERED - BUSINESS_EVENT_TRIGGERED - DEVICE_TRIGGERED (Push only) - LOCATION_TRIGGERED (Push only) - BROADCAST_LIVE_ACTIVITY (Push iOS only) **Campaign lifecycle:** 1. **Create** - Start a draft with only the required fields (`channel`, `campaign_delivery_type`, `created_by`). Add content, audience, and scheduling incrementally across subsequent update calls. 2. **Update** - Patch individual components as you refine the setup. Each submitted component is validated in full before the draft is updated. 3. **Validate** - Check whether a draft would pass publish-time validation without committing any changes. 4. **Test** - Send a test message to specific users from either a saved draft or inline content before going live. 5. **Manage** - Pause, resume, or stop a live campaign. Search your workspace and retrieve lightweight metadata across all campaigns. **Campaign versioning** is optional per workspace: - When enabled, publishing an update to a live campaign creates a new document with an incremented `version_number`. - `campaign_id` is the stable identifier across all versions; each version has its own raw `id` (ObjectId). **Authentication header:** Pass your Workspace ID in the `MOE-APPKEY` request header, the same as in V1. contact: name: MoEngage Developer Team email: support@moengage.com url: https://developers.moengage.com servers: - url: https://api-{dc}.moengage.com/ description: MoEngage Campaigns API Server variables: dc: default: '01' description: >- Data center (DC) segment in the hostname. Replace `OX` with your workspace DC (01–06 or 101). See [Data centers](/api/introduction#data-centers). security: - BasicAuth: [] paths: /v5/campaigns/{campaign_id}: patch: tags: - Update Campaigns summary: Update Campaign (V5) description: | Updates individual components of a campaign draft. operationId: patch_draft_campaign_v5 parameters: - $ref: '#/components/parameters/MOE-APPKEY' - $ref: '#/components/parameters/X-MOE-Request-Id' - name: campaign_id in: path required: true description: > The unique ID of the campaign to update. You can fetch the campaign ID using the [Get Campaign Details API](/api/get-campaign-details/search-campaigns-v5) by filtering with campaign name, channel, or other criteria. schema: type: string - $ref: '#/components/parameters/Idempotency-Key-Required' - $ref: '#/components/parameters/X-MOE-Scopes' requestBody: description: > In this payload, you can include the fields you want to update. **Notes:** - Pass only the fields you want to update. You don't need to send the complete payload. - If updating a field within an object, you must pass the complete object. - If updating a nested field, you must pass the complete parent object. For example, to update the title of a Push notification, pass the complete campaign_content object. - Use the tabs below to select your campaign type. The schema will adapt based on the selected channel. required: true content: application/json: schema: $ref: '#/components/schemas/CampaignPatchV5Request' examples: push_update_campaign_content: summary: Push - Update campaign_content value: request_id: '{{request_id}}' channel: PUSH campaign_delivery_type: '{{campaign_delivery_type}}' updated_by: '{{user_email}}' campaign_content: content: push: android: template_type: BASIC basic_details: title: '{{notification_title}}' message: '{{notification_message}}' email_update_campaign_content: summary: Email - Update campaign_content value: request_id: '{{request_id}}' channel: EMAIL campaign_delivery_type: '{{campaign_delivery_type}}' updated_by: '{{user_email}}' campaign_content: content: email: subject: '{{email_subject}}' sender_name: '{{sender_name}}' from_address: '{{from_email}}' html_content: '{{html_body}}' email_editor: Froala Editor push_update_basic_details: summary: Push - Update basic_details value: request_id: '{{request_id}}' updated_by: '{{user_email}}' basic_details: name: '{{campaign_name}}' platforms: - ANDROID - IOS tags: - '{{tag}}' team: '{{team_name}}' push_update_segmentation_details: summary: Push - Update segmentation_details value: request_id: '{{request_id}}' updated_by: '{{user_email}}' segmentation_details: included_filters: filter_operator: and filters: - filter_type: actions action_name: '{{event_name}}' execution: type: atleast count: 1 executed: true push_update_scheduling_details: summary: Push - Update scheduling_details value: request_id: '{{request_id}}' updated_by: '{{user_email}}' scheduling_details: delivery_type: AT_FIXED_TIME start_time: '{{start_time}}' expiry_time: '{{expiry_time}}' push_update_trigger_condition: summary: Push - Update trigger_condition value: request_id: '{{request_id}}' updated_by: '{{user_email}}' trigger_condition: included_filters: filter_operator: and filters: - filter_type: actions action_name: '{{trigger_event_name}}' execution: type: atleast count: 1 executed: true trigger_delay_type: DELAY trigger_delay_value: 30 trigger_delay_granularity: MINUTES trigger_relation: AFTER push_update_delivery_controls: summary: Push - Update delivery_controls value: request_id: '{{request_id}}' updated_by: '{{user_email}}' delivery_controls: bypass_dnd: false send_limit_value: '{{max_sends_per_user}}' send_limit_granularity_in_hours: '{{send_limit_window_hours}}' push_update_utm_params: summary: Push - Update utm_params value: request_id: '{{request_id}}' updated_by: '{{user_email}}' utm_params: utm_source: '{{utm_source}}' utm_medium: push utm_campaign: '{{utm_campaign}}' push_update_campaign_audience_limit: summary: >- Push - Update campaign_audience_limit (PERIODIC or EVENT_TRIGGERED) value: request_id: '{{request_id}}' updated_by: '{{user_email}}' campaign_audience_limit: is_campaign_audience_limit_enabled: true metric: SENT frequency: TOTAL limit: 100000 push_update_conversion_goal_details: summary: Push - Update conversion_goal_details value: request_id: '{{request_id}}' updated_by: '{{user_email}}' conversion_goal_details: attribution_window_in_hours: 36 goals: - goal_name: Goal 1 goal_event_name: '{{conversion_event_name}}' is_primary_goal: true email_update_basic_details: summary: Email - Update basic_details value: request_id: '{{request_id}}' updated_by: '{{user_email}}' basic_details: name: '{{campaign_name}}' content_type: PROMOTIONAL subscription_category: '{{subscription_category}}' tags: - '{{tag}}' email_update_connector: summary: Email - Update connector value: request_id: '{{request_id}}' updated_by: '{{user_email}}' connector: connector_type: '{{connector_type}}' connector_name: '{{connector_name}}' email_update_scheduling_details: summary: Email - Update scheduling_details value: request_id: '{{request_id}}' updated_by: '{{user_email}}' scheduling_details: delivery_type: AT_FIXED_TIME start_time: '{{start_time}}' email_update_utm_params: summary: Email - Update utm_params value: request_id: '{{request_id}}' updated_by: '{{user_email}}' utm_params: utm_source: '{{utm_source}}' utm_medium: email utm_campaign: '{{utm_campaign}}' push_update_advanced: summary: Push - Update advanced value: request_id: '{{request_id}}' updated_by: '{{user_email}}' advanced: expiration_settings: expire_notification_after_value: 24 expire_notification_after_type: HOUR platform_level_priority: ios_specific_priority: apns_priority: '10' interruption_level: ACTIVE android_specific_priority: send_with_priority: true push_update_control_group_details: summary: Push - Update control_group_details value: request_id: '{{request_id}}' updated_by: '{{user_email}}' control_group_details: is_campaign_control_group_enabled: true campaign_control_group_percentage: 10 push_update_basic_details_geofences: summary: Push - Update basic_details.geofences value: request_id: '{{request_id}}' updated_by: '{{user_email}}' basic_details: geofences: name: '{{geofence_name}}' latitude: '{{latitude}}' longitude: '{{longitude}}' radius: '{{radius_meters}}' response_time_value: '5' response_time_granularity: MINUTES triggered_at: ENTRY push_update_platform_specific_details: summary: Push - Update platform_specific_details value: request_id: '{{request_id}}' updated_by: '{{user_email}}' basic_details: platform_specific_details: android: push_amp_plus_enabled: true ios: send_to_all_eligible_device: true email_update_segmentation_details: summary: Email - Update segmentation_details value: request_id: '{{request_id}}' channel: EMAIL campaign_delivery_type: '{{campaign_delivery_type}}' updated_by: '{{user_email}}' segmentation_details: included_filters: filter_operator: and filters: - filter_type: user_attributes data_type: string name: city operator: in value: '{{city_value}}' email_update_delivery_controls: summary: Email - Update delivery_controls value: request_id: '{{request_id}}' channel: EMAIL campaign_delivery_type: '{{campaign_delivery_type}}' updated_by: '{{user_email}}' delivery_controls: bypass_dnd: false campaign_throttle_rpm: 2000 count_for_frequency_capping: true email_update_conversion_goal_details: summary: Email - Update conversion_goal_details value: request_id: '{{request_id}}' channel: EMAIL campaign_delivery_type: '{{campaign_delivery_type}}' updated_by: '{{user_email}}' conversion_goal_details: attribution_window_in_hours: 36 goals: - goal_name: Goal 1 goal_event_name: '{{conversion_event_name}}' is_primary_goal: true email_update_control_group_details: summary: Email - Update control_group_details value: request_id: '{{request_id}}' channel: EMAIL campaign_delivery_type: '{{campaign_delivery_type}}' updated_by: '{{user_email}}' control_group_details: is_campaign_control_group_enabled: true campaign_control_group_percentage: 10 email_update_campaign_audience_limit: summary: >- Email - Update campaign_audience_limit (PERIODIC or EVENT_TRIGGERED) value: request_id: '{{request_id}}' channel: EMAIL campaign_delivery_type: '{{campaign_delivery_type}}' updated_by: '{{user_email}}' campaign_audience_limit: is_campaign_audience_limit_enabled: true metric: SENT frequency: TOTAL limit: 100000 responses: '200': description: > Draft updated successfully. **Note:** V1 returned `204 No Content` for successful updates. V5 returns `200 OK` with a response body. Update any integration that checks for `204` to expect `200` instead. content: application/json: schema: allOf: - $ref: '#/components/schemas/V5SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/CampaignPatchAcceptedData' examples: component_updated: summary: Component update accepted value: response_id: abc-301 type: campaign data: id: 64a1b2c3d4e5f6a7b8c9d0e1 '400': $ref: '#/components/responses/V5ValidationError' '401': $ref: '#/components/responses/V5Unauthorized' '403': description: > The caller does not have the required permission to update this campaign. This occurs when the API credential's scope does not include campaign update rights, or when the caller attempts to update a campaign owned by a different team with restricted access. content: application/json: schema: $ref: '#/components/schemas/V5ErrorEnvelope' example: response_id: abc-403 error: code: FORBIDDEN message: Caller does not have permission to update this campaign. details: [] '409': description: > The campaign is not in a state that allows updates. This occurs when the campaign is not in `DRAFT` state - for example, it is `ACTIVE`, `PAUSED`, or `STOPPED`. Only `DRAFT` campaigns can be updated via this endpoint. content: application/json: schema: $ref: '#/components/schemas/V5ErrorEnvelope' example: response_id: abc-409 error: code: BAD_REQUEST message: Campaign is not in DRAFT state and cannot be patched. details: [] '429': description: > The per-app rate limit for this endpoint has been exceeded. Retry after the window indicated in the `Retry-After` response header (in seconds). content: application/json: schema: $ref: '#/components/schemas/V5ErrorEnvelope' example: response_id: abc-429 error: code: RATE_LIMITED message: Rate limit exceeded. Retry after 60 seconds. details: [] '500': $ref: '#/components/responses/V5InternalError' components: parameters: MOE-APPKEY: name: MOE-APPKEY in: header required: true description: > Your MoEngage Workspace ID (App ID). Find it in the dashboard at **Settings** > **Account** > **APIs** > **Workspace ID**. schema: type: string example: '{{workspace_id}}' X-MOE-Request-Id: name: X-MOE-Request-Id in: header required: true description: > Correlates with `response_id`. Supply this header or `request_id` in the body; if both are set, they must match. schema: type: string Idempotency-Key-Required: name: Idempotency-Key in: header required: true description: > UUID v4. Required on all `POST` and `PATCH` requests except `POST /v5/campaigns/{campaign_id}/validate`. Repeating the same key returns the same response body. schema: type: string format: uuid X-MOE-Scopes: name: X-MOE-Scopes in: header required: false description: > Caller's effective Campaigns permissions. When requests pass through the MoEngage IAM gateway, the gateway injects this header from the permissions tied to your API key, and the service treats it as the source of truth. The service reads only the `campaigns:` entry. Action vocabulary: `view` (read), `create_manage` (create and edit drafts), and `create_manage_publish` (reserved for future publish support). The hierarchy is `create_manage_publish` ⟹ `create_manage` ⟹ `view`. Required action by operation: - `PATCH /v5/campaigns/{campaign_id}` (component edits) requires `create_manage`. If your effective permissions do not satisfy the required action, the API returns `403`. Other V5 routes are not gated by this header in the current release. schema: type: string example: campaigns:create_manage schemas: CampaignPatchV5Request: description: Used for component-level edits on a campaign draft. oneOf: - $ref: '#/components/schemas/PushComponentPatchRequest' - $ref: '#/components/schemas/EmailComponentPatchRequest' V5SuccessEnvelope: type: object properties: response_id: type: string type: type: string example: campaign data: type: object CampaignPatchAcceptedData: type: object required: - id description: Returned after a successful component PATCH. properties: id: type: string description: Raw 24-character campaign ObjectId. example: 64a1b2c3d4e5f6a7b8c9d0e1 V5ErrorEnvelope: type: object properties: response_id: type: string error: type: object properties: code: type: string enum: - VALIDATION_FAILED - UNPROCESSABLE_ENTITY - BAD_REQUEST - RATE_LIMITED - UNAUTHORIZED - INTERNAL_ERROR - FORBIDDEN message: type: string target: type: string details: type: array items: type: object properties: target: type: string message: type: string request_id: type: string description: > The `request_id` from the originating request. Use this to correlate a failed response back to the specific call that triggered it, particularly useful in high-volume or retry scenarios. In V1, `request_id` appeared inside the `error` object. V5 preserves this field in the same location. PushComponentPatchRequest: title: Update Push Campaign Draft type: object description: > Update one or more components of a Push campaign draft. Only fields you include are changed, omitted fields retain their current values. When updating a nested field, include its complete parent object. properties: request_id: type: string description: A unique identifier for this update request. example: '{{request_id}}' channel: type: string enum: - PUSH description: Must be `PUSH` for a Push update. campaign_delivery_type: type: string enum: - ONE_TIME - PERIODIC - EVENT_TRIGGERED - BUSINESS_EVENT_TRIGGERED - DEVICE_TRIGGERED - LOCATION_TRIGGERED - BROADCAST_LIVE_ACTIVITY description: > The delivery type of the campaign being updated. **Note:** `BROADCAST_LIVE_ACTIVITY` is included in this enum for campaigns created via the V1 API or legacy paths. Draft creation via `POST /v5/campaigns` does not support `BROADCAST_LIVE_ACTIVITY`. A draft cannot be transitioned to a Live Activity campaign through V5. updated_by: type: string format: email description: > The email address of the user making this update, used for audit trail purposes. If omitted, the update is attributed to the authenticated API credential. example: marketer@example.com basic_details: $ref: '#/components/schemas/PushBasicDetailsV5' trigger_condition: $ref: '#/components/schemas/PushTriggerCondition' campaign_content: $ref: '#/components/schemas/PushCampaignContent' segmentation_details: $ref: '#/components/schemas/SegmentationDetails' scheduling_details: $ref: '#/components/schemas/SchedulingDetails' delivery_controls: $ref: '#/components/schemas/PushDeliveryControls' advanced: $ref: '#/components/schemas/AdvancedDetails' conversion_goal_details: $ref: '#/components/schemas/ConversionGoalDetails' control_group_details: $ref: '#/components/schemas/ControlGroupDetails' utm_params: $ref: '#/components/schemas/UTMParams' campaign_audience_limit: allOf: - $ref: '#/components/schemas/CampaignAudienceLimit' description: > Configuration for capping how many users this campaign can reach. **Flag-gated feature** — must be enabled for your workspace by your MoEngage account team before use. EmailComponentPatchRequest: title: Update Email Campaign Draft type: object description: > Update one or more components of an Email campaign draft. Only fields you include are changed, omitted fields retain their current values. When updating a nested field, include its complete parent object. properties: request_id: type: string description: A unique identifier for this update request. example: '{{request_id}}' channel: type: string enum: - EMAIL description: Must be `EMAIL` for an Email update. campaign_delivery_type: type: string enum: - ONE_TIME - PERIODIC - EVENT_TRIGGERED - BUSINESS_EVENT_TRIGGERED description: The delivery type of the campaign being updated. updated_by: type: string format: email description: > The email address of the user making this update, used for audit trail purposes. If omitted, the update is attributed to the authenticated API credential. example: marketer@example.com basic_details: $ref: '#/components/schemas/EmailBasicDetailsV5' connector: $ref: '#/components/schemas/Connector' trigger_condition: $ref: '#/components/schemas/EmailTriggerCondition' campaign_content: $ref: '#/components/schemas/EmailCampaignContent' segmentation_details: $ref: '#/components/schemas/SegmentationDetails' scheduling_details: $ref: '#/components/schemas/SchedulingDetails' delivery_controls: $ref: '#/components/schemas/EmailDeliveryControls' advanced: $ref: '#/components/schemas/AdvancedDetails' conversion_goal_details: $ref: '#/components/schemas/ConversionGoalDetails' control_group_details: $ref: '#/components/schemas/ControlGroupDetails' utm_params: $ref: '#/components/schemas/UTMParams' campaign_audience_limit: allOf: - $ref: '#/components/schemas/CampaignAudienceLimit' description: > Configuration for capping how many users this campaign can reach. **Flag-gated feature** — must be enabled for your workspace by your MoEngage account team before use. PushBasicDetailsV5: type: object description: > Identifying metadata for the Push campaign, including name, team, tags, and platform targeting. For field-by-field rules, conditional requirements, and platform-specific delivery flags (Android `push_amp_plus_enabled`, iOS provisional-push audience flags), refer to [Push campaign metadata](/api/campaigns/campaign-content-reference#push-campaign-metadata). properties: name: type: string description: The name of the campaign. example: Summer Sale Push Notification business_event: type: string description: | The business event to be mapped to the campaign. **Required** for BUSINESS_EVENT_TRIGGERED campaigns. example: user_signup tags: type: array items: type: string description: Tags that provide context about the campaign's nature or theme. example: - activation - summer_sale team: type: string description: > The name of the team collaborating on this campaign. For more information, refer to [Teams in MoEngage](https://help.moengage.com/hc/en-us/articles/360028586211-Teams-in-MoEngage). example: marketing_team platforms: type: array items: type: string enum: - ANDROID - IOS - WEB description: The platforms to target for this Push campaign. example: - ANDROID - IOS broadcast_live_activity_id: type: string description: > The broadcast live activity ID for iOS Live Activities. **Required** when platform is iOS and delivery_type is BROADCAST_LIVE_ACTIVITY. **Not applicable in the draft-based creation flow.** `BROADCAST_LIVE_ACTIVITY` is not supported via POST `/v5/campaigns`. example: live_check123 geofences: $ref: '#/components/schemas/Geofences' send_to_triggered_platform_only: type: boolean description: >- Whether to send the campaign only to the platform that triggered the event. Applicable for event-triggered campaigns. platform_specific_details: $ref: '#/components/schemas/PlatformSpecificDetails' PushTriggerCondition: type: object description: > Trigger condition details for Push event-triggered, device-triggered, and related campaigns. **Required** for `EVENT_TRIGGERED`, `DEVICE_TRIGGERED`, and `LOCATION_TRIGGERED` Push campaigns. For per-delay-type runnable payloads (`ASAP`, `DELAY` with `AFTER`/`BEFORE`, `INTELLIGENT_DELAY`), filter primitives, and primary/secondary filter combinations, refer to [Trigger conditions](/api/campaigns/audience-scheduling-delivery-reference#trigger-conditions). properties: included_filters: $ref: '#/components/schemas/FilterGroup' secondary_included_filters: allOf: - $ref: '#/components/schemas/FilterGroup' description: >- Additional filters that must also be satisfied for the trigger to fire. For runnable examples, refer to [Primary and secondary trigger filters](/api/campaigns/audience-scheduling-delivery-reference#primary-and-secondary-trigger-filters). trigger_delay_type: type: string enum: - DELAY - ASAP - INTELLIGENT_DELAY description: | The type of triggered delay. When set to DELAY, the following fields are mandatory: - trigger_delay_value - trigger_delay_granularity - trigger_relation trigger_delay_value: type: integer minimum: 0 description: The numeric value of the triggered delay. trigger_delay_granularity: type: string enum: - MINUTES - HOURS - DAYS description: The time unit for the trigger delay. trigger_relation: type: string enum: - BEFORE - AFTER description: | The trigger relation with delay. **Required** when trigger_delay_type is DELAY. trigger_attr: type: string description: >- The attribute value of the trigger. Pass the string `"If Action"` for event-triggered campaigns. intelligent_delay_optimization: type: object description: > Configuration for intelligent delay optimization. Used when trigger_delay_type is INTELLIGENT_DELAY. Defines a time window (min/max delay) within which the system finds the optimal moment to send the message. properties: min_delay_value: type: integer description: >- The numeric component of the lower bound for the intelligent delay window. min_delay_granularity: type: string enum: - MINUTES - HOURS description: The time unit that qualifies the min_delay_value. max_delay_value: type: integer description: >- The numeric component of the upper bound for the intelligent delay window. max_delay_granularity: type: string enum: - HOURS - DAYS description: The time unit that qualifies the max_delay_value. PushCampaignContent: type: object description: > Push message content, locales, and A/B variations. For full `POST /v5/campaigns` request examples that include `campaign_content`, refer to `campaign_delivery_type` on `PushCampaignCreateV5Request`, `VariationDetails`, and the Create Campaign Draft code samples. For per-template-type runnable payloads, refer to [Android push content](/api/campaigns/campaign-content-reference#android-push-content), [iOS push content](/api/campaigns/campaign-content-reference#ios-push-content), or [Web push content](/api/campaigns/campaign-content-reference#web-push-content). properties: locales: type: array items: type: string description: > Additional locale names for multi-language campaigns. List only the non-default locales here (for example, `"en-US"`, `"es-ES"`). The `"default"` locale is always implicitly present and must not be included in this array. example: - en-US - es-ES variation_details: $ref: '#/components/schemas/VariationDetails' content: type: object description: > The campaign message payload. Two shapes are accepted: - **Flat shape (no locales or variations):** Pass a flat `push` object directly under `content`. - **Locale-keyed and variation-keyed shape:** Key by locale name, then by variation name: `content[locale_name][variation_name] = { push: { ... } }`. The `"default"` locale key is always required and serves as the fallback. Additional locale keys must match values listed in `locales`. If your V1 integration used locale-variation wrapping, you must continue using that structure in V5. The flat format is only valid when no locales or A/B variations are configured on the campaign. For runnable payloads for both shapes, refer to [Content payload structure](/api/campaigns/campaign-content-reference#content-payload-structure). properties: push: $ref: '#/components/schemas/PushContent' additionalProperties: type: object description: Variation-keyed content blocks for a single locale. additionalProperties: type: object properties: push: $ref: '#/components/schemas/PushContent' SegmentationDetails: type: object description: > Defines the target audience for the campaign. For included/excluded filter combinations, filter primitives (`user_attributes`, `actions`, `custom_segments`), and opt-out targeting, refer to [Campaign audience](/api/campaigns/audience-scheduling-delivery-reference#campaign-audience). properties: included_filters: $ref: '#/components/schemas/FilterGroup' excluded_filters: allOf: - $ref: '#/components/schemas/FilterGroup' description: | Filters that exclude users from the campaign audience. is_all_user_campaign: type: boolean description: Whether to include all users in the campaign. send_campaign_to_opt_out_users: type: boolean description: >- Whether to send the campaign to users who have opted out. For runnable examples, refer to [Campaign audience](/api/campaigns/audience-scheduling-delivery-reference#campaign-audience). SchedulingDetails: type: object description: > Defines when the campaign should be sent. For per-delivery-type runnable payloads (`ASAP`, `AT_FIXED_TIME`, `SEND_IN_BTS`, `SEND_IN_USER_TIMEZONE`, and `PERIODIC` with `periodic_details`), refer to [Campaign delivery schedule](/api/campaigns/audience-scheduling-delivery-reference#campaign-delivery-schedule). properties: delivery_type: type: string enum: - ASAP - AT_FIXED_TIME - SEND_IN_BTS - SEND_IN_USER_TIMEZONE description: | When to deliver the campaign. start_time: type: string format: date-time description: > The start time for the campaign in ISO 8601 format. Interpreted in the timezone specified by the `timezone` field. If `timezone` is not provided, pass this value in UTC. Example: "2024-06-21T12:59:00" expiry_time: type: string format: date-time description: > The expiry time for the campaign in ISO 8601 format. Interpreted in the timezone specified by the `timezone` field. If `timezone` is not provided, pass this value in UTC. timezone: type: string description: > IANA timezone string for the campaign schedule (for example, `Asia/Kolkata`). Required when `delivery_type` is `AT_FIXED_TIME` or `SEND_IN_BTS`. Optional for `SEND_IN_USER_TIMEZONE`, where each user's own timezone is used. example: Asia/Kolkata periodic_details: $ref: '#/components/schemas/PeriodicDetails' bts_details: $ref: '#/components/schemas/BTSDetails' user_timezone_details: $ref: '#/components/schemas/UserTimezoneDetails' geo_fence_timelimit: type: object description: > Defines the delivery time window for location-triggered campaigns. When configured, notifications are delivered only within the specified schedule. **Applicable for:** `LOCATION_TRIGGERED` campaigns. properties: notification_schedule: type: string enum: - ALWAYS - LIMITED_TIME description: >- Controls when delivery is permitted. Set to `ALWAYS` to allow delivery at any time, or `LIMITED_TIME` to restrict delivery to the configured time bounds. timebounds: type: array description: > One or more start and end time windows within which delivery is permitted. **Required** when `notification_schedule` is `LIMITED_TIME`. items: type: object properties: start_time: type: string format: date-time description: Start of the delivery window in ISO 8601 format. example: '2027-06-19T11:02:00' end_time: type: string format: date-time description: End of the delivery window in ISO 8601 format. example: '2029-06-20T13:55:00' PushDeliveryControls: type: object description: > Controls for Push campaign delivery behavior. For per-delivery-type runnable examples (throttle, event-triggered, device-triggered, location-triggered, queuing), refer to [Push delivery controls](/api/campaigns/audience-scheduling-delivery-reference#push-delivery-controls). properties: bypass_dnd: type: boolean description: | Whether to bypass Do Not Disturb settings. Required for event-triggered campaigns. campaign_throttle_rpm: type: integer description: > The campaign throttle in requests per minute. Not applicable for device-triggered, location-triggered, and event-triggered campaigns. example: 50000 count_for_frequency_capping: type: boolean description: Whether to count this campaign for frequency capping. ignore_frequency_capping: type: boolean description: Whether to ignore frequency capping for this campaign. minimum_delay_between_two_notification_in_hour: type: integer description: | Minimum delay between two notifications in hours. Applies to event-triggered and device-triggered campaigns. max_time_to_show_message_of_same_camapign: type: string description: > Maximum duration (in hours) that a message from this campaign will be displayed to a user. Applicable for device-triggered campaigns. expiry_time_of_sync_data_in_hour: type: string description: > Duration (in hours) after which synced campaign data will expire if trigger condition is not met. Applicable for device-triggered campaigns. send_message_in_offline_mode: type: boolean description: | Whether to store and deliver the message when the device is offline. Applicable for device-triggered campaigns. send_limit_value: type: string description: > Maximum number of times a user can receive this campaign within the specified time granularity. Applicable for location-triggered campaigns. send_limit_granularity_in_hours: type: string description: > Time window (in hours) during which the send_limit_value is enforced. Applicable for location-triggered campaigns. ignore_global_minimum_delay: type: boolean description: > Whether to bypass the global minimum delay setting configured at the workspace level. When `true`, this campaign ignores the workspace-wide minimum interval between push notifications and can be delivered to a user regardless of how recently they received another push. Use this for time-sensitive campaigns (for example, transactional or alert-style messages) where respecting the global delay would reduce delivery timeliness. Applies to event-triggered campaigns. queuing_enabled: type: boolean description: > Enables message queuing for this campaign. When set to `true`, messages that are temporarily blocked by DND, frequency capping, or minimum delay restrictions are held in a queue and delivered as soon as the restriction clears, rather than being dropped. **Supported delivery types:** `ONE_TIME`, `PERIODIC`, `EVENT_TRIGGERED`, `BUSINESS_EVENT_TRIGGERED`. Not applicable to `DEVICE_TRIGGERED` or `LOCATION_TRIGGERED` campaigns. **DND interaction:** - When `bypass_dnd` is `false` (DND respected): messages blocked during a DND window are queued and delivered once the window passes. - When `bypass_dnd` is `true` (DND ignored): queuing applies to frequency capping and minimum delay blocks only. **Auto-disabled:** When both `ignore_frequency_capping` and `minimum_delay_between_two_notification_in_hour` are configured to bypass all delivery restrictions, queuing is automatically disabled. **Queue limits:** Up to 10,000,000 messages for `ONE_TIME`, `PERIODIC`, and `BUSINESS_EVENT_TRIGGERED` campaigns; up to 1,000,000 for `EVENT_TRIGGERED` campaigns. **Delivery order:** Queued messages are delivered in first-in, first-out (FIFO) order. queue_duration: type: integer minimum: 0 maximum: 48 description: > The duration in hours during which a queued message will be retried for delivery. Accepted range: `1`–`48` hours. Set to `0` when `queuing_enabled` is `false`. If a user does not become eligible for delivery within the configured window, the message is dropped and the outcome is recorded in campaign analytics. For active `PERIODIC` and triggered campaigns, changes to this value apply only to messages queued after the update. Messages already in the queue retain the original duration. AdvancedDetails: type: object description: > Advanced Push delivery settings, including notification expiration and per-platform priority. For runnable iOS APNS priority and Android priority examples, refer to [Advanced Push settings](/api/campaigns/audience-scheduling-delivery-reference#advanced-push-settings). properties: expiration_settings: type: object properties: expire_notification_after_value: type: integer description: The numeric value for the notification expiration time. expire_notification_after_type: type: string enum: - HOUR - DAY description: The time unit for notification expiration. remove_from_inbox_after_value: type: integer description: The numeric value for when to remove the message from the inbox. remove_from_inbox_after_type: type: string enum: - DAY description: The time unit for removing the message from the inbox. platform_level_priority: type: object properties: android_specific_priority: type: object properties: send_with_priority: type: boolean description: Whether to send with priority. ios_specific_priority: type: object properties: apns_priority: type: string enum: - '1' - '5' - '10' description: The priority of notification delivery for APNS. interruption_level: type: string enum: - PASSIVE - ACTIVE - TIME_SENSITIVE - CRITICAL description: The interruption level for iOS notifications. relevance_score: type: number enum: - 0 - 0.5 - 1 description: The relevance score for iOS notifications. ConversionGoalDetails: type: object description: > Configuration for tracking campaign conversion goals. For runnable single-goal and multi-goal examples, refer to [Conversion goal tracking](/api/campaigns/audience-scheduling-delivery-reference#conversion-goal-tracking). properties: attribution_window_in_hours: type: integer description: The attribution window in hours. example: 36 goals: type: array items: $ref: '#/components/schemas/Goal' description: List of conversion goals to track. ControlGroupDetails: type: object description: > Configuration for control groups. For runnable campaign-control-group and global-control-group examples, refer to [Control groups](/api/campaigns/audience-scheduling-delivery-reference#control-groups). properties: is_campaign_control_group_enabled: type: boolean description: Whether the campaign control group is enabled. campaign_control_group_percentage: type: integer minimum: 0 maximum: 100 description: | The percentage of users added to the exclusion list. **Required** if is_campaign_control_group_enabled is true. is_global_control_group_enabled: type: boolean description: | Whether the global control group is enabled. UTMParams: type: object description: > UTM parameters for tracking campaign performance. The five standard keys (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`) are explicitly defined. **Custom UTM parameters:** Up to 5 additional custom parameters can be passed as separate keys directly inside the `utm_params` object. Custom keys accept arbitrary names — the `utm_` prefix is a convention, not a requirement (for example, `utm_cust` or `campaign_source` are both accepted). For runnable examples, refer to [UTM parameters](/api/campaigns/audience-scheduling-delivery-reference#utm-parameters). properties: utm_source: type: string description: | The source of the traffic (for example, YouTube, Instagram, Google). **Required** when using UTM parameters. example: '{{utm_source}}' utm_medium: type: string description: | The channel type (for example, Push, SMS, Email). **Required** when using UTM parameters. example: '{{utm_medium}}' utm_campaign: type: string description: The name of the campaign (for example, Newyear, Bigbillionday). example: '{{utm_campaign}}' utm_term: type: string description: Search terms for paid traffic (for example, Mobile+sale). utm_content: type: string description: >- The content element that differentiates links (for example, banner, video). utm_custom: type: string description: > A single custom UTM parameter value. For multiple custom parameters, pass them as separate top-level keys inside the `utm_params` object using arbitrary `utm_`-prefixed names (for example, `utm_cust`, `utm_c1ust`, `utm_c2ust`). A maximum of 5 custom parameters is supported in total. additionalProperties: type: string description: > Arbitrary custom UTM parameters with `utm_`-prefixed key names (for example, `utm_cust`, `utm_c1ust`). Up to 5 custom parameters are supported in total across all custom keys. CampaignAudienceLimit: type: object description: > Configuration for capping the number of users a campaign can reach (max-send). Campaign Audience Limit (also called max-send) caps how many users a single campaign can reach. Use it to control reach on high-volume campaigns and protect users from over-messaging. The cap can apply across the campaign's full lifetime (`frequency: TOTAL`) or per send instance (`frequency: INSTANCE`). For runnable `TOTAL` (lifetime cap), `INSTANCE` (per-send cap, Periodic Push only), and disabled-cap examples, refer to [Campaign audience cap](/api/campaigns/audience-scheduling-delivery-reference#campaign-audience-cap). **Supported channels:** Email, Push. **Supported delivery types:** - All delivery types support `frequency: TOTAL` (lifetime cap). - `frequency: INSTANCE` (per-send cap) is supported only for **Periodic Push** campaigns. - `campaign_audience_limit` is not supported for `BROADCAST_LIVE_ACTIVITY`. **Flag-gated feature:** This feature is not enabled by default for any workspace and requires explicit activation by your MoEngage account team. If you include `campaign_audience_limit` in a request on a workspace where the flag has not been enabled, the API returns a `400` with the following error body: ```json { "error": { "code": "VALIDATION_FAILED", "message": "Campaign Audience Limit feature is not enabled for this db", "target": "campaign_audience_limit", "details": [ { "target": "campaign_audience_limit", "message": "Campaign Audience Limit feature is not enabled for this db" } ] }, "response_id": "{{response_id}}" } ``` When `is_campaign_audience_limit_enabled` is `true`, the fields `metric`, `frequency`, and `limit` are all required. When set to `false`, those three fields must not be provided. For `ONE_TIME` campaigns, only `limit` and `is_campaign_audience_limit_enabled` are supported. Do not pass `metric` or `frequency`, they are only valid for `PERIODIC` and `EVENT_TRIGGERED` campaigns. Passing them for a ONE_TIME campaign causes the validate API to fail. properties: is_campaign_audience_limit_enabled: type: boolean description: > Whether the campaign audience limit is active. Set to `true` to enforce the cap; `false` to disable. When `true`, `metric`, `frequency`, and `limit` are all required. When `false`, `metric`, `frequency`, and `limit` must not be provided. metric: type: string description: | The type of send event counted toward the limit. Must be uppercase. **Required** when `is_campaign_audience_limit_enabled` is `true`. enum: - SENT example: SENT frequency: type: string description: > The window over which the limit is applied. Must be uppercase. - `TOTAL` - applies the cap across the full lifetime of the campaign. Supported for all delivery types on both Email and Push. - `INSTANCE` - applies the cap per campaign instance (for example, per periodic send). **Valid only for Push `PERIODIC` campaigns.** For all other delivery types, use `TOTAL`. **Required** when `is_campaign_audience_limit_enabled` is `true`. enum: - TOTAL - INSTANCE example: TOTAL limit: type: integer minimum: 1 maximum: 9999999999 description: > The maximum number of users who can receive this campaign (or per instance, when `frequency` is `INSTANCE`). Must be between 1 and 9,999,999,999. **Required** when `is_campaign_audience_limit_enabled` is `true`. example: 100000 EmailBasicDetailsV5: type: object description: > Identifying metadata for the Email campaign, including name, team, tags, and subscription category. **Conditional requirements:** `name`, `content_type`, `user_attribute_identifier`, and `subscription_category` are strictly required only when using the `/v5/campaigns/test` endpoint in **inline mode**. They are not required at campaign creation time (V5 supports progressive creation, where components are added later via PATCH) and are not needed in **draft mode** tests, where content comes from the saved draft. properties: name: type: string description: Any string name for the test or campaign. example: Summer Sale Email business_event: type: string description: The business event to be mapped to the campaign. example: user_signup content_type: type: string enum: - PROMOTIONAL - TRANSACTIONAL description: >- The type of content in the campaign. "PROMOTIONAL" or "TRANSACTIONAL". subscription_category: type: string description: > The subscription category for promotional email campaigns. **Must match a valid category configured in your workspace.** **Required** for PROMOTIONAL email campaigns and inline tests. example: marketing tags: type: array items: type: string description: Tags that provide context about the campaign's nature or theme. example: - activation - summer_sale team: type: string description: The name of the team collaborating on this campaign. example: marketing_team user_attribute_identifier: type: string default: Email (Standard) description: > The user attribute that stores the recipient email address. Use "Email (Standard)" for email channels. example: Email (Standard) Connector: type: object description: > Email connector configuration for sending email campaigns. Required for inline Email test requests and before an Email campaign can be published or sent for testing. Not required at draft create time — it can be added later via `PATCH`. For runnable examples, refer to [Email delivery connector](/api/campaigns/campaign-content-reference#email-delivery-connector). required: - connector_type - connector_name properties: connector_type: type: string enum: - SENDGRID - AMAZON_SES - SPARKPOST - MANDRILL - CUSTOM_SMTP - CUSTOM_API - NETCORE description: > The email service provider for this campaign. Must match a connector configured in your MoEngage workspace. Accepted values: `SENDGRID`, `AMAZON_SES`, `SPARKPOST`, `MANDRILL`, `CUSTOM_SMTP`, `CUSTOM_API`, `NETCORE`. To find which connectors are active, go to **Settings** > **Email** > **Connectors** in the MoEngage dashboard. connector_name: type: string description: >- The name of the connector configuration as configured in your MoEngage workspace. EmailTriggerCondition: type: object description: > Trigger condition details for Email event-triggered campaigns. **Required** for EVENT_TRIGGERED campaigns. For per-delay-type runnable payloads (`ASAP`, `DELAY` with `AFTER`/`BEFORE`), filter primitives, and primary/secondary filter combinations, refer to [Trigger conditions](/api/campaigns/audience-scheduling-delivery-reference#trigger-conditions). properties: included_filters: $ref: '#/components/schemas/FilterGroup' secondary_included_filters: allOf: - $ref: '#/components/schemas/FilterGroup' description: >- Additional filters that must also be satisfied for the Email trigger to fire. For runnable examples, refer to [Primary and secondary trigger filters](/api/campaigns/audience-scheduling-delivery-reference#primary-and-secondary-trigger-filters). trigger_delay_type: type: string enum: - DELAY - ASAP description: | The type of triggered delay. When set to DELAY, the following fields are mandatory: - trigger_delay_value - trigger_delay_granularity - trigger_relation trigger_delay_value: type: integer minimum: 0 description: The numeric value of the triggered delay. trigger_delay_granularity: type: string enum: - MINUTES - HOURS - DAYS description: The time unit for the trigger delay. trigger_relation: type: string enum: - BEFORE - AFTER description: | The trigger relation with delay. **Required** when trigger_delay_type is DELAY. trigger_attr: type: string description: >- The attribute value of the trigger. Pass the string `"If Action"` for event-triggered campaigns. EmailCampaignContent: type: object description: > Email content, locales, and A/B variations. For full `POST /v5/campaigns` request examples that include `campaign_content`, refer to `campaign_delivery_type` on `EmailCampaignCreateV5Request`, `VariationDetails`, and the Create Campaign Draft code samples. For Email content variants, including `html_content` versus `custom_template_id`, CC/BCC, attachments, and editor selection (`Froala Editor` versus `Ace Editor`), refer to [Email content](/api/campaigns/campaign-content-reference#email-content). properties: locales: type: array items: type: string description: > Additional locale names for multi-language campaigns. List only the non-default locales here (for example, `"en-US"`, `"es-ES"`). The `"default"` locale is always implicitly present and must not be included in this array. example: - en-US - es-ES variation_details: $ref: '#/components/schemas/VariationDetails' content: type: object description: > The campaign message payload. Two shapes are accepted: - **Flat shape (no locales or variations):** Pass a flat `email` object directly under `content`. - **Locale-keyed and variation-keyed shape:** Key by locale name, then by variation name: `content[locale_name][variation_name] = { email: { ... } }`. The `"default"` locale key is always required and serves as the fallback. Additional locale keys must match values listed in `locales`. For runnable payloads for both shapes, refer to [Content payload structure](/api/campaigns/campaign-content-reference#content-payload-structure). properties: email: $ref: '#/components/schemas/EmailContent' additionalProperties: type: object description: Variation-keyed content blocks for a single locale. additionalProperties: type: object properties: email: $ref: '#/components/schemas/EmailContent' EmailDeliveryControls: type: object description: > Controls for Email campaign delivery behavior. For runnable examples, refer to [Email delivery controls](/api/campaigns/audience-scheduling-delivery-reference#email-delivery-controls). properties: bypass_dnd: type: boolean description: Whether to bypass Do Not Disturb settings. campaign_throttle_rpm: type: integer description: The campaign throttle in requests per minute. example: 2000 count_for_frequency_capping: type: boolean description: Whether to count this campaign for frequency capping. ignore_frequency_capping: type: boolean description: Whether to ignore frequency capping for this campaign. minimum_delay_between_two_notification_in_hour: type: integer description: Minimum delay between two notifications in hours. Geofences: type: object description: > Geofence location details for location-triggered campaigns. **Required** for LOCATION_TRIGGERED campaigns. For per-`triggered_at` runnable payloads (`ENTRY`, `EXIT`, `dwell`) and the casing distinction between `ENTRY`/`EXIT` (uppercase) and `dwell` (lowercase), refer to [Geofence targeting](/api/campaigns/audience-scheduling-delivery-reference#geofence-targeting). required: - name - latitude - longitude - radius - response_time_value - response_time_granularity - triggered_at properties: name: type: string description: The unique name of the geofence location being targeted. latitude: type: string description: The latitude coordinate for the center of the geofence area. longitude: type: string description: The longitude coordinate for the center of the geofence area. radius: type: string description: >- The radius in meters from the center point that defines the boundary of the geofence. dwell_time_value: type: string description: > The numeric value for the time to wait before sending the message after the trigger condition is met. **Required** when triggered_at is set to "dwell". dwell_time_granularity: type: string enum: - MINUTES - HOURS - DAYS description: | The time unit for the dwell_time_value. **Required** when triggered_at is set to "dwell". response_time_value: type: string description: >- The numeric value for the time to wait before sending the message after the trigger condition is met. response_time_granularity: type: string enum: - MINUTES - HOURS - DAYS description: The time unit for the response_time_value. triggered_at: type: string enum: - ENTRY - EXIT - dwell description: > The user action that triggers the campaign (when user enters/exits the geofence). PlatformSpecificDetails: type: object description: > Platform-specific configuration details for Push. For runnable Android and iOS examples and the mutual-exclusion rule on iOS audience flags, refer to [Platform-specific delivery flags](/api/campaigns/campaign-content-reference#platform-specific-delivery-flags). properties: android: type: object properties: push_amp_plus_enabled: type: boolean default: false description: Whether Push Amp+ feature is enabled for this campaign. ios: type: object description: | **Note:** You must pass one of these keys as true for iOS. properties: send_to_all_eligible_device: type: boolean description: Whether to send the campaign to all eligible devices. exclude_provisional_push_devices: type: boolean description: Whether to exclude provisional push devices. send_to_only_provisional_push_enabled_devices: type: boolean description: Whether to send only to provisional push-enabled devices. FilterGroup: type: object description: > A group of filters combined with a logical operator. For detailed segmentation payload and supported fields, refer to [Create Custom Segment](https://developers.moengage.com/hc/en-us/articles/13277936457748). properties: filter_operator: type: string enum: - and - or description: The logical operator to combine filters. filters: type: array items: oneOf: - $ref: '#/components/schemas/UserAttributeFilter' - $ref: '#/components/schemas/ActionFilter' - $ref: '#/components/schemas/CustomSegmentFilter' description: | The list of filters to be combined using the filter operator. Supported filter types: - User attributes-based filters - Action-based filters (with or without attributes) - Custom segments VariationDetails: type: object description: > Configuration for A/B testing variations. For runnable `MANUAL` (fixed split) and `SHERPA` (auto-optimized) examples, refer to [A/B test variations](/api/campaigns/campaign-content-reference#a-b-test-variations). properties: distribution_type: type: string enum: - SHERPA - MANUAL description: > The traffic distribution method for A/B test variations. - `MANUAL` - you specify a fixed percentage split across variations. - `SHERPA` - MoEngage's AI-powered optimizer automatically shifts traffic toward the best-performing variation during the campaign run. no_of_variations: type: integer minimum: 1 description: The number of A/B test variations. example: 2 manual_distribution_percentage: type: object additionalProperties: type: integer description: > Fixed percentage of audience assigned to each variation. **Note:** Variation keys must follow the `variation_N` naming format (e.g. `variation_1`, `variation_2`). Keys with any other format like `var_1`, `1`, `2` will be rejected with a validation error. **Required** when `distribution_type` is `MANUAL`. example: variation_1: 50 variation_2: 50 sherpa_campaign_duration: type: integer description: > Duration in hours over which MoEngage Sherpa collects performance data before declaring a winning variation. **Required** when `distribution_type` is `SHERPA`. sherpa_distribution_metric: type: string enum: - OPEN_RATE - CLICK_RATE - BOTH description: | The engagement metric Sherpa uses to evaluate and rank variations. **Required** when `distribution_type` is `SHERPA`. PushContent: type: object description: Push notification content for Android, iOS, and Web platforms. properties: android: $ref: '#/components/schemas/AndroidPushContent' ios: $ref: '#/components/schemas/IOSPushContent' web: $ref: '#/components/schemas/WebPushContent' PeriodicDetails: type: object description: > Configuration for periodic campaigns. **Required** for PERIODIC campaigns. For runnable Daily, Weekly, Monthly (specific dates), and Monthly (first Monday) examples, refer to [Periodic schedules](/api/campaigns/audience-scheduling-delivery-reference#periodic-schedules). properties: sending_frequency: type: string enum: - DAILY - WEEKLY - MONTHLY description: The frequency to send the campaign. repeat_frequency: type: integer description: The repeat frequency of the campaign. no_of_occurences: type: integer description: The number of occurrences of the campaign. repeat_on_date_of_month: type: array items: type: integer description: | The dates of the month on which the campaign should be repeated. Example: [5, 25] to send on the 5th and 25th of each month. repeat_on_days_of_week: type: array items: type: string enum: - MONDAY - TUESDAY - WEDNESDAY - THURSDAY - FRIDAY - SATURDAY - SUNDAY description: | The days of the week on which the campaign should repeat. repeat_on_days_of_week_for_month: type: array items: type: object properties: week_granularity: type: string enum: - FIRST - SECOND - THIRD - FOURTH - LAST repeat_on_days_of_week: type: array items: type: string enum: - MONDAY - TUESDAY - WEDNESDAY - THURSDAY - FRIDAY - SATURDAY - SUNDAY description: | Configuration for repeating on specific weeks of the month. BTSDetails: type: object description: > Best Time to Send (BTS) configuration. BTS selects an optimal send time per user based on historical engagement patterns. For the field schema and required-when-`SEND_IN_BTS` rule, refer to [Best Time to Send](/api/campaigns/audience-scheduling-delivery-reference#best-time-to-send). properties: send_in_bts: type: boolean description: Whether to send the campaign at the best time. if_user_bts_is_not_available: type: string description: When to send the campaign if the user's best time is not available. if_user_bts_outside_time_window: type: string description: >- When to send the campaign if the user's best time is outside the time window. window_end_time: type: string description: The window end time. example: 6:43 am UserTimezoneDetails: type: object description: > Configuration for sending in the user's timezone. For the field schema and required-when-`SEND_IN_USER_TIMEZONE` rule, refer to [User timezone](/api/campaigns/audience-scheduling-delivery-reference#user-timezone). properties: send_in_user_timezone: type: boolean description: >- Whether to send the campaign on a specific date and time within the user's timezone. send_if_user_timezone_has_passed: type: boolean description: Whether to send the campaign if the user's timezone has passed. Goal: type: object description: A single conversion goal configuration. properties: goal_name: type: string description: The name of the goal. example: Goal 1 goal_event_name: type: string description: The event name associated with this goal. goal_event_attribute: $ref: '#/components/schemas/GoalEventAttribute' is_primary_goal: type: boolean description: Whether this is the primary goal. revenue_attribute: type: string description: The revenue attribute to track. revenue_currency: type: string description: The currency for revenue tracking. EmailContent: type: object description: Email campaign content. properties: subject: type: string description: The subject line of the email. example: Exclusive Summer Sale - 50% Off! preview_text: type: string description: The preview text shown in email clients. example: Don't miss out on our biggest sale of the season sender_name: type: string description: The name of the sender that appears in the email. example: MoEngage Team from_address: type: string format: email description: The sender's email address. example: noreply@example.com reply_to_address: type: string format: email description: The reply-to email address. example: support@example.com cc_ids: type: array items: type: string format: email description: >- Email addresses to CC. For runnable examples, refer to [Email content variants](/api/campaigns/campaign-content-reference#email-content-variants). bcc_ids: type: array items: type: string format: email description: >- Email addresses to BCC. For runnable examples, refer to [Email content variants](/api/campaigns/campaign-content-reference#email-content-variants). html_content: type: string description: | The HTML content of the email. **Optional** if custom_template_id is provided. example: >-

Hello {{UserAttribute['First Name']}}

email_editor: type: string enum: - Froala Editor - Ace Editor description: > The HTML editor used for the email campaign. - **Required** if you want to create the campaign using the `Ace Editor`. - **Optional** if you want to use the default `Froala Editor`. example: Ace Editor custom_template_id: type: string description: | The ID of a custom email template. **Optional** if html_content is provided. When this field is provided, the following fields are not required: - subject - preview_text - sender_name custom_template_version: type: integer description: The version of the custom template. attachments: type: array items: type: object properties: file_type: type: string enum: - URL - PERSONALIZED_ATTACHMENT url: type: string description: | Attachments to include in the email. UserAttributeFilter: type: object title: User attributes-based filters description: Filter based on user attributes. properties: filter_type: type: string enum: - user_attributes data_type: type: string enum: - string - double - datetime - bool description: The data type of the attribute being filtered. category: type: string description: The category of the attribute (e.g., "Tracked Standard Attribute"). name: type: string description: The name of the attribute to filter on (e.g., "uid"). operator: type: string description: > The operator to use in the filter. Allowed values depend on data_type: - bool: is, exists - double: in, between, lessThan, greaterThan, exists - string: in, contains, containsInTheFollowing, startWithInTheFollowing, endsWithInTheFollowing, exists, is - datetime: inTheLast, on, between, before, after, inTheNext, exists, today value: description: The value to filter on (not required for 'exists' operator). case_sensitive: type: boolean description: Whether the filter comparison should be case-sensitive. negate: type: boolean description: Whether to negate the filter condition. is_dynamic_value: type: boolean description: > When `true`, the filter value is treated as a dynamic expression and resolved at send time rather than evaluated as a literal string. Set this to `true` for Business Event-triggered campaigns where the filter value references a Business Event attribute, for example, `{{BusinessEventAttribute['season']}}`. project_name: type: string description: | The name of the project associated with the user attributes. **Required** if the Portfolio feature is enabled in your workspace. ActionFilter: type: object title: Action-based filters (with or without attributes) description: > Filter based on user actions/events. Use inside `segmentation_details.included_filters.filters` or `trigger_condition.included_filters.filters`. properties: filter_type: type: string enum: - actions action_name: type: string description: The name of the action/event to filter on. execution: type: object properties: type: type: string enum: - atleast - atmost - exactly count: type: integer executed: type: boolean description: Whether the action was executed. attributes: $ref: '#/components/schemas/FilterGroup' condition: type: string description: The condition type. Must be passed as the string "IF". CustomSegmentFilter: type: object title: Custom segments description: Filter using a custom segment. properties: filter_type: type: string enum: - custom_segments name: type: string description: The name of the custom segment. id: type: string description: The ID of the custom segment. AndroidPushContent: type: object description: Android push notification content. properties: template_type: type: string enum: - BASIC - STYLIZED_BASIC - SIMPLE_IMAGE_CAROUSEL - IMAGE_BANNER_WITH_TEXT - TIMER - TIMER_WITH_PROGRESS_BAR - Custom description: > The type of Android push template. **Note:** If you are passing a template ID, set template_type to "Custom" and use `custom_template_id`. custom_template_id: type: string description: | The ID of the custom template. **Required** when template_type is "Custom". custom_template_version: type: integer description: The version of the custom template. basic_details: $ref: '#/components/schemas/AndroidBasicDetails' timer: $ref: '#/components/schemas/AndroidTimer' buttons: type: array items: $ref: '#/components/schemas/AndroidButton' description: Action buttons for the notification. advanced: $ref: '#/components/schemas/AndroidAdvanced' template_backup: $ref: '#/components/schemas/AndroidTemplateBackup' IOSPushContent: type: object description: iOS push notification content. properties: template_type: type: string enum: - BASIC - STYLIZED_BASIC - SIMPLE_IMAGE_CAROUSEL - Custom description: | The type of iOS push template. custom_template_id: type: string description: | The ID of the custom template. **Required** when template_type is "Custom". custom_template_version: type: integer description: The version of the custom template. basic_details: $ref: '#/components/schemas/IOSBasicDetails' buttons: type: array items: $ref: '#/components/schemas/IOSButton' description: Action buttons for the notification. advanced: $ref: '#/components/schemas/IOSAdvanced' template_backup: $ref: '#/components/schemas/IOSTemplateBackup' WebPushContent: type: object description: Web push notification content. properties: template_type: type: string enum: - BASIC description: The template type for web push (currently only BASIC is supported). basic_details: $ref: '#/components/schemas/WebBasicDetails' buttons: type: array items: $ref: '#/components/schemas/WebButton' description: | Action buttons for the notification. advanced: $ref: '#/components/schemas/WebAdvanced' GoalEventAttribute: type: object description: Attributes associated with the conversion goal event. properties: name: type: string description: The name of the goal event attribute. condition: type: string description: >- The condition used while creating the goal (e.g., "is", "contains", "between"). data_type: type: string enum: - STRING - DOUBLE - BOOL - NUMBER - GEOPOINT - DATETIME - ARRAY_DOUBLE - ARRAY_STRING - OBJECT - ARRAY_OBJECT description: The data type of the attribute. value: type: string description: > The value of the goal event attribute. Supported data types: STRING, DOUBLE, BOOL, NUMBER, GEOPOINT, DATETIME, ARRAY_DOUBLE, ARRAY_STRING. value1: type: string description: > A secondary value, used for conditions like 'between'. Supported data types: STRING, DOUBLE, BOOL, NUMBER, GEOPOINT, DATETIME, ARRAY_DOUBLE, ARRAY_STRING. negate: type: boolean description: Whether to negate the filter condition. value_type: type: string description: The type of value being filtered. array_filter_type: type: string description: The logical filter type for array attributes. filters: type: array items: type: object description: A list of sub-filters used when data_type is OBJECT or ARRAY_OBJECT. is_case_sensitive: type: boolean description: Whether the goal event attribute is case-sensitive. AndroidBasicDetails: type: object description: > Basic details for the Android push notification. Fields vary by template_type. All templates support common fields like title, message, default_click_action. properties: notification_channel: type: string description: The Android notification channel where the push will be sent. example: general include_app_name_and_time: type: boolean description: > Whether to include the application's name and timestamp within the banner image. **Supported Templates:** Image Banner with Text background_color_code: type: string description: > The hex code for the notification's background color. **Supported Templates:** Stylized Basic, Simple Image Carousel, Image Banner with Text example: '#9a4444' app_name_color_code: type: string description: > The hex code for the color of the application's name text. **Supported Templates:** Stylized Basic, Simple Image Carousel, Image Banner with Text example: '#dea1a1' notification_control_color: type: string enum: - LIGHT - DARK description: > The color scheme for the notification's control elements (action buttons). **Supported Templates:** Stylized Basic, Simple Image Carousel, Image Banner with Text include_title_and_message: type: boolean description: > Whether to include the notification's title and message text within the banner image. **Supported Templates:** Image Banner with Text apply_background_color_in_text_editor: type: boolean description: > Whether to apply the specified background color within the rich text editor for preview. **Supported Templates:** Stylized Basic, Simple Image Carousel, Image Banner with Text title: type: string description: The main title of the push notification. example: Limited Time Offer! message: type: string description: > The message body of the push notification. You can use HTML in the message parameter to apply rich text formatting, including text color and styles. example: Get 50% off on all items. Shop now! summary: type: string description: The summary text for the notification. image_url: type: string format: uri description: The image URL for the push notification. example: https://example.com/images/promo.jpg image_scaling: type: string enum: - FIT_INSIDE_IMAGE_CONTAINER - FILL_IMAGE_CONTAINER description: > The scaling behavior for images within the carousel template. **Supported Templates:** Simple Image Carousel, Image Banner with Text banner_image_url: type: string format: uri description: > The URL for the background image used in the Image Banner Text template. **Required for:** Image Banner with Text template input_gif_url: type: string format: uri description: | The URL for the GIF media used in the push campaign content. **Supported Templates:** Basic collapsed_push_notification: type: string description: > The configuration for the notification's collapsed state (view before user expands it). **Supported Templates:** Image Banner with Text example: SAME_AS_TEMPLATE_BACKUP carousel_content: $ref: '#/components/schemas/CarouselContent' default_click_action: type: string enum: - DEEPLINKING - NAVIGATE_TO_A_SCREEN - RICH_LANDING description: >- The action performed when the main body of the notification is clicked. default_click_action_value: type: string description: The URL or deep link to open when the notification is clicked. example: https://example.com/sale key_value_pairs: type: array items: $ref: '#/components/schemas/KeyValuePair' description: Custom key-value pairs for the notification payload. AndroidTimer: type: object description: | Timer configuration for Timer and Timer with Progress Bar templates. **Required for:** TIMER and TIMER_WITH_PROGRESS_BAR templates properties: timer_ends_at: type: string enum: - DURATION - SPECIFIC_TIME_USER_TIMEZONE - SPECIFIC_TIME_CAMPAIGN_TIMEZONE description: How the timer's endpoint is determined. specific_time: type: string format: date-time description: | The specific time when the timer ends. **Required** when personalized_value is true. time_period: type: string description: > The time period for the timer. **Required** when timer_ends_at is SPECIFIC_TIME_USER_TIMEZONE or SPECIFIC_TIME_CAMPAIGN_TIMEZONE. personalized_value: type: boolean description: | Whether the timer duration is personalized per user. If false, all users get the same duration. duration_hour: type: string description: | The number of hours the timer will run for. **Required** when personalized_value is false. example: '2' duration_minute: type: string description: | The number of minutes the timer will run for (in addition to hours). **Required** when personalized_value is false. example: '30' AndroidButton: type: object description: Action button configuration for Android push notifications. properties: btn_name: type: string description: The text to be displayed on the button. example: Shop Now click_action_type: type: string enum: - DEEPLINKING - NAVIGATE_TO_A_SCREEN - RICH_LANDING - CALL - SHARE - COPY - SET_USER_ATTRIBUTE - TRACK_EVENT - CUSTOM_ACTION - SNOOZE - REMIND_LATER description: The type of action to perform when the button is clicked. click_action_name: type: string description: The name of the click action. click_action_value: type: string description: The URL or deep link to open for the button's action. example: https://example.com/product key_value_pairs: type: array items: $ref: '#/components/schemas/KeyValuePair' description: Custom key-value pairs specific to this button's click event. AndroidAdvanced: type: object description: >- Platform-level advanced settings for push delivery - TTL, priority, badge count, and similar controls. properties: coupon_code: type: string description: The coupon code to be included in the push payload. example: SUMMER50 icon_type_in_notification: type: string description: The icon type to be included in the push payload. example: app_icon use_large_icon: type: boolean description: Whether to use a large icon in the notification. make_notification_sticky: type: boolean description: | When enabled, the user cannot swipe away the notification. dismiss_button_text: type: string description: > The text to display on the dismiss button. **Required** when make_notification_sticky is true or auto_dismiss_notification is true. auto_dismiss_notification: type: boolean description: Whether the notification can be auto-dismissed. auto_dismiss_notification_time_value: type: integer description: | The time value after which to auto-dismiss the notification. **Required** when auto_dismiss_notification is true. auto_dismiss_notification_time_granularity: type: string enum: - DAYS - HOURS - MINUTES description: | The time unit for auto-dismiss. **Required** when auto_dismiss_notification is true. group_key: type: string description: > The group key used to identify and categorize related push notifications. **Note:** - Use the same group key for all push notifications you want to group - MoEngage automatically modifies the group key to ensure it doesn't exceed 45 characters - Non-Latin scripts, special characters, and spaces are removed collapse_replace_key: type: string description: > The update key used to identify and update related push notifications. Ensure you use the same update key for all push notifications intended to update each other. AndroidTemplateBackup: type: object description: > Fallback notification content for when the template cannot be rendered. **Required for:** Stylized Basic, Simple Image Carousel, Image Banner with Text, Timer, and Timer with Progress Bar templates properties: title: type: string description: The title for the fallback notification. message: type: string description: The message body for the fallback notification. summary: type: string description: The summary for the fallback notification. image_url: type: string format: uri description: The URL of an image for the fallback notification. default_click_action: type: string enum: - DEEPLINKING - NAVIGATE_TO_A_SCREEN - RICH_LANDING description: The default click action for the fallback notification. default_click_action_value: type: string description: The URL or deep link for the fallback's click action. key_value_pairs: type: array items: $ref: '#/components/schemas/KeyValuePair' description: Custom key-value pairs specific to the fallback payload. IOSBasicDetails: type: object description: Basic details for the iOS push notification. properties: background_color_code: type: string description: | The hexadecimal color code for the notification's background. **Supported Templates:** Simple Image Carousel, Stylized Basic example: '#a0a0a0' apply_background_color_in_text_editor: type: boolean description: | Whether to apply the background color within the text editor view. **Supported Templates:** Simple Image Carousel, Stylized Basic title: type: string description: The main title of the push notification. example: New Message message: type: string description: The main body text of the notification. example: You have a new message waiting for you subtitle: type: string description: The subtitle displayed below the main title. allow_bg_refresh: type: boolean description: >- Whether to allow the app to be woken up in the background to refresh content. rich_media_type: type: string enum: - Image - Video - GIF description: | The type of rich media to be included in the notification. **Supported Templates:** Basic rich_media_value: type: string format: uri description: > The URL of the rich media asset specified in the rich_media_type field. **Supported Templates:** Basic image_url: type: string format: uri description: > The URL of a large image to be displayed within the notification content. **Note:** Required when template_type is SIMPLE_IMAGE_CAROUSEL. input_gif_url: type: string format: uri description: | The URL for the GIF media used in the push campaign content. **Supported Templates:** Basic, Stylized Basic carousel_content: $ref: '#/components/schemas/IOSCarouselContent' default_click_action: type: string enum: - DEEPLINKING - NAVIGATE_TO_A_SCREEN - RICH_LANDING description: >- The action performed when the main body of the notification is tapped. default_click_action_value: type: string description: The URL or deep link associated with the default click action. key_value_pairs: type: array items: $ref: '#/components/schemas/KeyValuePair' description: >- Custom key-value pairs sent with the push payload for in-app handling. IOSButton: type: object description: Action button configuration for iOS push notifications. properties: button_category: type: string description: > The pre-defined category name for a set of interactive buttons configured in the app. example: MOE_PUSH_TEMPLATE IOSAdvanced: type: object description: >- Platform-level advanced settings for push delivery - TTL, priority, badge count, and similar controls. properties: coupon_code: type: string description: The coupon code to be included in the push payload. sound_file: type: string description: >- The name of a custom sound file located in the app bundle to play upon receiving the notification. enable_ios_badge: type: boolean description: >- Whether this campaign allows the notification to increment the app's badge count. group_key: type: string description: > The group key used to identify and categorize related push notifications. **Note:** - Use the same group key for all push notifications you want to group - MoEngage automatically modifies the group key to ensure it doesn't exceed 45 characters - Non-Latin scripts, special characters, and spaces are removed collapse_replace_key: type: string description: > The update key used to identify and update related push notifications. Ensure you use the same update key for all push notifications intended to update each other. IOSTemplateBackup: type: object description: | Fallback notification content for when the template cannot be rendered. **Required for:** Stylized Basic and Simple Image Carousel templates properties: title: type: string description: The title for the fallback notification. message: type: string description: The message body for the fallback notification. subtitle: type: string description: The subtitle for the fallback notification. allow_bg_refresh: type: boolean description: >- Whether to enable background app refresh for the fallback notification. rich_media_type: type: string enum: - Image - Video - GIF description: The type of media attachment for the fallback. rich_media_value: type: string format: uri description: The URL of the media attachment for the fallback. default_click_action: type: string enum: - DEEPLINKING - NAVIGATE_TO_A_SCREEN - RICH_LANDING description: The default click action for the fallback notification. default_click_action_value: type: string description: The URL or deep link for the fallback's click action. key_value_pairs: type: array items: $ref: '#/components/schemas/KeyValuePair' description: Custom key-value pairs specific to the fallback payload. WebBasicDetails: type: object description: Basic details for the Web push notification. properties: title: type: string description: The title text displayed at the top of the notification. example: Special Offer message: type: string description: The main body text of the notification. example: Check out our latest deals! redirect_url: type: string format: uri description: >- The URL that the user is redirected to when they click the main body of the notification. example: https://example.com/offers image_url: type: string format: uri description: >- The URL of a large image to be displayed within the notification content. auto_dismiss_notification: type: boolean description: Whether the notification should auto-dismiss. WebButton: type: object description: Action button configuration for Web push notifications. properties: title: type: string description: The text displayed on the button. example: View Offer icon_url: type: string format: uri description: The URL of an icon to be displayed next to the button text. url: type: string format: uri description: >- The destination URL that the user is redirected to when they click this button. WebAdvanced: type: object description: > Platform-level advanced settings for push delivery - TTL, priority, badge count, and similar controls. properties: icon_image_type: type: string enum: - DEFAULT - ICON_URL description: The type of icon to use for the notification. icon_url: type: string format: uri description: The URL for a custom notification icon. CarouselContent: type: object description: | Configuration for image carousel in Simple Image Carousel template. **Required for:** Simple Image Carousel template properties: slider_transition: type: string enum: - MANUAL - AUTOMATIC description: > The transition type for the carousel slides. In earlier versions of this API, the accepted values were `manual` and `automatic` (lowercase). They are now `MANUAL` and `AUTOMATIC` (uppercase). Update any existing integrations that pass lowercase values. slide_data: type: array description: Array of slide configurations. items: type: object properties: image_url: type: string format: uri description: The image URL for this slide. image_click_action: type: string enum: - DEEPLINKING - RICH_LANDING - NAVIGATE_TO_A_SCREEN description: The click action for this slide's image. image_click_action_value: type: string description: | The click action value for this slide's image. **Required** when image_click_action is provided. key_value_pairs: type: array items: $ref: '#/components/schemas/KeyValuePair' KeyValuePair: type: object description: A custom key-value pair attached to the push payload. properties: key: type: string description: The key name. value: type: string description: The value. IOSCarouselContent: type: object description: | Configuration for image carousel in Simple Image Carousel template. **Required for:** Simple Image Carousel template properties: slider_transition: type: string enum: - MANUAL - AUTOMATIC description: > The transition type for the carousel slides. In earlier versions of this API, the accepted values were `manual` and `automatic` (lowercase). They are now `MANUAL` and `AUTOMATIC` (uppercase). Update any existing integrations that pass lowercase values. slide_data: type: array description: Array of slide configurations. items: type: object properties: image_url: type: string format: uri description: The image URL for this slide. image_click_action: type: string enum: - DEEPLINKING - RICH_LANDING - NAVIGATE_TO_A_SCREEN description: The click action for this slide's image. image_click_action_value: type: string description: The click action value for this slide's image. key_value_pairs: type: array items: $ref: '#/components/schemas/KeyValuePair' responses: V5ValidationError: description: Request failed schema or component validation. content: application/json: schema: $ref: '#/components/schemas/V5ErrorEnvelope' example: response_id: abc-101 error: code: VALIDATION_FAILED message: One or more fields failed validation. request_id: req-push-001 details: - target: campaign_delivery_type message: campaign_delivery_type value is required. V5Unauthorized: description: Authentication failure. content: application/json: schema: $ref: '#/components/schemas/V5ErrorEnvelope' example: response_id: abc-101 error: code: UNAUTHORIZED message: Invalid or missing credentials. details: [] V5InternalError: description: Unhandled server-side failure. content: application/json: schema: $ref: '#/components/schemas/V5ErrorEnvelope' example: response_id: abc-101 error: code: INTERNAL_ERROR message: Internal server error. details: [] securitySchemes: BasicAuth: type: http scheme: basic description: > Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'. - **Username**: Use your MoEngage workspace ID (also known as the App ID). You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**. - **Password**: On your MoEngage workspace, navigate to **Settings** → **Account** → **API keys** and click **Create new key**. The tab lists every API surface (Data, Segmentation, Push, Email, Campaigns, Templates, and more) and exposes per-resource actions. For Campaigns, ensure the **View**, **Create & Manage**, and **Create, Manage & Publish** checkboxes are selected. For more information on authentication and getting your credentials, refer to [Getting your credentials](/api/introduction#getting-your-credentials). Send the value in the `Authorization` header as `Basic` followed by Base64-encoding of `appkey:apisecret` (workspace ID and API key). ````