> ## 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 Status (V5)
> Applies a state transition to a published campaign. Supported for **Email** and **Push** campaigns.
This endpoint only handles post-publish lifecycle transitions (STOP, PAUSE, RESUME) for campaigns that are already live. Campaign publishing is not yet supported in V5.
The response does not include the resulting campaign status. To confirm the new state after a transition, call `GET /v5/campaigns/{campaign_id}`.
#### Rate Limits
| Rate Limit Name | Rate Limit |
| :- | :- |
| change campaign status per second | The total number of change campaign status requests per second per client is 10. |
| change campaign status per minute | The total number of change campaign status requests per minute per client allowed is 100. |
| change campaign status per hour | The total number of change campaign status 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}/status
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:** The `MOE-APPKEY` request header is optional.
Basic Auth already carries your Workspace ID as the username, so requests
authenticate correctly without it.
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}/status:
patch:
tags:
- Update Campaigns
summary: Update Campaign Status (V5)
description: >
Applies a state transition to a published campaign. Supported for
**Email** and **Push** campaigns.
operationId: change_campaign_status_v5
parameters:
- $ref: '#/components/parameters/MOE-APPKEY'
- $ref: '#/components/parameters/X-MOE-Request-Id'
- name: campaign_id
in: path
required: true
description: Raw 24-char ObjectId of the published campaign to transition.
schema:
type: string
- $ref: '#/components/parameters/Idempotency-Key-Required'
requestBody:
description: Send campaign status change request with action.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignStatusV5Request'
examples:
stop_campaign:
summary: Stop a campaign
value:
request_id: '{{request_id}}'
action: STOP
pause_campaign:
summary: Pause a campaign
value:
request_id: '{{request_id}}'
action: PAUSE
resume_campaign:
summary: Resume a campaign
value:
request_id: '{{request_id}}'
action: RESUME
responses:
'200':
description: Transition accepted.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/V5SuccessEnvelope'
- type: object
properties:
data:
$ref: '#/components/schemas/CampaignStatusTransitionData'
example:
response_id: abc-601
type: campaign
data:
id: 64a1b2c3d4e5f6a7b8c9d0e1
action: STOP
'400':
$ref: '#/components/responses/V5ValidationError'
'401':
$ref: '#/components/responses/V5Unauthorized'
'422':
description: >
The action is not valid for the campaign's current state or delivery
type. Common causes:
- Attempting `STOP` on a Periodic campaign.
- Attempting `PAUSE` or `RESUME` on a One-time campaign.
- Attempting `RESUME` on a campaign that is not in `PAUSED` state.
- Attempting `PAUSE` on a campaign that is not in `ACTIVE`,
`SCHEDULED`, or `SENDING` state.
content:
application/json:
schema:
$ref: '#/components/schemas/V5ErrorEnvelope'
example:
response_id: abc-422
error:
code: UNPROCESSABLE_ENTITY
message: Action STOP is not valid for a PERIODIC campaign.
details: []
'500':
$ref: '#/components/responses/V5InternalError'
components:
parameters:
MOE-APPKEY:
name: MOE-APPKEY
in: header
required: false
description: >
Your MoEngage Workspace ID (App ID). Optional — Basic Auth already
carries the Workspace ID as the username, so this header is not
required. Find it in the dashboard at **Settings** > **Account** > **API
keys**.
schema:
type: string
example: '{{workspace_id}}'
X-MOE-Request-Id:
name: X-MOE-Request-Id
in: header
required: false
description: >
Client-supplied trace ID for tracing. 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
schemas:
CampaignStatusV5Request:
type: object
description: >-
Changes the status of a single published campaign. One campaign ID per
request.
required:
- action
properties:
request_id:
type: string
description: >
A client-supplied identifier for this status change request, echoed
back as `response_id` so you can correlate the request and response.
This is not a deduplication key — to make a request idempotent, use
the `Idempotency-Key` header. Replaying the same `Idempotency-Key`
returns the original response.
action:
type: string
enum:
- STOP
- PAUSE
- RESUME
description: >
Lifecycle action for an already published or scheduled campaign.
Each action applies only to specific delivery types and requires the
campaign to be in a valid source state:
| Action | Supported delivery types | Valid source states |
| :--- | :--- | :--- |
| `STOP` | `ONE_TIME` | `ACTIVE`, `SCHEDULED`, `PAUSED`, `SENDING` |
| `PAUSE` | `PERIODIC`, `EVENT_TRIGGERED` | `ACTIVE`, `SCHEDULED`,
`SENDING` |
| `RESUME` | `PERIODIC`, `EVENT_TRIGGERED` | `PAUSED` |
`STOP` cannot be used on Periodic campaigns. `PAUSE` and `RESUME` cannot be used on One-time campaigns.
V5SuccessEnvelope:
type: object
properties:
response_id:
type: string
type:
type: string
example: campaign
data:
type: object
CampaignStatusTransitionData:
type: object
required:
- id
- action
description: Returned after a successful status transition on a published campaign.
properties:
id:
type: string
description: Raw 24-character campaign ObjectId.
example: 64a1b2c3d4e5f6a7b8c9d0e1
action:
type: string
description: The action that was applied (matches the requested action).
enum:
- STOP
- PAUSE
- RESUME
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.
responses:
V5ValidationError:
description: Request failed schema or component validation.
content:
application/json:
schema:
$ref: '#/components/schemas/V5ErrorEnvelope'
examples:
validation_failed:
summary: Generic field validation failure
value:
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.
double_opt_in_not_enabled_for_account:
summary: Double opt-in not enabled for account
value:
response_id: abc-101
error:
code: BAD_REQUEST
message: Double opt-in is not enabled for this account
target: basic_details
details:
- target: basic_details.send_only_double_opt_in_users
message: Double opt-in is not enabled for this account
double_opt_in_single_opt_in_method:
summary: Account opt-in method is Single Opt-in
value:
response_id: abc-101
error:
code: BAD_REQUEST
message: >-
send_only_double_opt_in_users cannot be set to true when
account opt-in method is Single Opt-in
target: basic_details
details:
- target: basic_details.send_only_double_opt_in_users
message: >-
send_only_double_opt_in_users cannot be set to true when
account opt-in method is Single Opt-in
double_opt_in_used_on_transactional_campaign:
summary: Used on TRANSACTIONAL campaign
value:
response_id: abc-101
error:
code: BAD_REQUEST
message: >-
send_only_double_opt_in_users is not supported for
transactional campaigns
target: basic_details
details:
- target: basic_details.send_only_double_opt_in_users
message: >-
send_only_double_opt_in_users is not supported for
transactional campaigns
double_opt_in_wrong_type:
summary: Wrong type (non-boolean)
value:
response_id: abc-101
error:
code: BAD_REQUEST
message: >-
send_only_double_opt_in_users - Invalid value passed.
Expected type: boolean
target: basic_details
details:
- target: basic_details.send_only_double_opt_in_users
message: >-
send_only_double_opt_in_users - Invalid value passed.
Expected type: boolean
deduplication_attribute_feature_not_enabled_for_account:
summary: deduplication_attribute - feature not enabled for account
value:
response_id: abc-101
error:
code: BAD_REQUEST
message: Brand dedup is not enabled for this account
target: basic_details
details:
- target: basic_details.deduplication_attribute
message: Brand dedup is not enabled for this account
deduplication_attribute_invalid_attribute_name:
summary: deduplication_attribute - invalid attribute name
value:
response_id: abc-101
error:
code: BAD_REQUEST
message: >-
deduplication_attribute '' is not a valid user
attribute for this account
target: basic_details
details:
- target: basic_details.deduplication_attribute
message: >-
deduplication_attribute '' is not a valid user
attribute for this account
deduplication_attribute_wrong_type_non_string:
summary: deduplication_attribute - wrong type (non-string)
value:
response_id: abc-101
error:
code: BAD_REQUEST
message: >-
deduplication_attribute - Invalid value passed. Expected
type: string, but got: int.
target: basic_details
details:
- target: basic_details.deduplication_attribute
message: >-
deduplication_attribute - Invalid value passed. Expected
type: string, but got: int.
deduplication_attribute_not_supported_for_api_triggered:
summary: >-
deduplication_attribute not supported for API_TRIGGERED
campaigns
value:
response_id: abc-101
error:
code: BAD_REQUEST
message: >-
deduplication_attribute is not supported for API_TRIGGERED
campaigns
target: basic_details
details:
- target: basic_details.deduplication_attribute
message: >-
deduplication_attribute is not supported for
API_TRIGGERED campaigns
gmail_annotations_on_transactional:
summary: gmail_annotations used on TRANSACTIONAL campaign
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: campaign_content.content.email.gmail_annotations
message: >-
gmail_annotations is not supported for TRANSACTIONAL
content type. It is only supported for PROMOTIONAL
campaigns.
gmail_annotations_missing_sender_logo:
summary: sender_logo missing when gmail_annotations is present
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.sender_logo
message: >-
sender_logo is required when gmail_annotations is
specified
gmail_annotations_invalid_sender_logo:
summary: sender_logo is not a valid HTTPS URL
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.sender_logo
message: sender_logo must be a valid https URL
gmail_annotations_deal_card_missing_field:
summary: Required deal_card field missing
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.deal_card.availability_starts
message: >-
availability_starts is required when deal_card is
specified
gmail_annotations_deal_card_invalid_end_time:
summary: availability_ends less than 1 hour after availability_starts
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.deal_card
message: >-
End date and time must be a minimum of one hour later
than the start date and time
gmail_annotations_product_carousel_minimum_products:
summary: Product carousel has fewer than 2 products
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.product_carousel
message: Product carousel requires a minimum of 2 products
gmail_annotations_product_set_product_count_exceeds_maximum:
summary: product_count exceeds maximum of 9
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.product_carousel.product_set_data
message: product_count must be between 2 and 9
gmail_annotations_product_carousel_invalid_original_price:
summary: Manual product has invalid original_price
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.product_carousel.manual_data.products[0].original_price
message: original_price must be a valid number
gmail_annotations_product_carousel_invalid_discount_value:
summary: Manual product has invalid discount_value
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.product_carousel.manual_data.products[0].discount_value
message: discount_value must be a valid number
gmail_annotations_product_carousel_invalid_promo_url:
summary: Manual product has invalid promo_url
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.product_carousel.manual_data.products[0].promo_url
message: promo_url must be a valid https URL
gmail_annotations_product_carousel_empty_product_image:
summary: Manual product has empty product_image
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.product_carousel.manual_data.products[0].product_image
message: product_image (Image URL) cannot be empty
gmail_annotations_product_carousel_invalid_product_image_url:
summary: Manual product has invalid product_image URL
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.product_carousel.manual_data.products[0].product_image
message: product_image must be a valid https URL
gmail_annotations_product_set_not_found:
summary: Product set ID does not exist in the workspace
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.product_carousel.product_set_data
message: product_set not found for the given workspace
gmail_annotations_product_sets_feature_not_enabled:
summary: Product Sets feature is not enabled for the workspace
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: >-
campaign_content.content.email.gmail_annotations.product_carousel
message: Product Sets is not enabled for this workspace
link_branding_domain_no_domain_configured:
summary: link_branding_domain - no link branding domains configured
value:
response_id: abc-101
error:
code: BAD_REQUEST
message: >-
link_branding_domain cannot be processed because no link
branding domains have been configured for this workspace.
Please set up a domain in your MoEngage dashboard settings
first.
target: campaign_content.content.email
details:
- target: campaign_content.content.email.link_branding_domain
message: >-
link_branding_domain cannot be processed because no link
branding domains have been configured for this
workspace.
link_branding_domain_no_match:
summary: link_branding_domain - does not match a configured domain
value:
response_id: abc-101
error:
code: BAD_REQUEST
message: >-
The provided link_branding_domain does not match any of the
configured domains for this workspace. Please verify the
domain name and try again.
target: campaign_content.content.email
details:
- target: campaign_content.content.email.link_branding_domain
message: >-
The provided link_branding_domain does not match any of
the configured domains for this workspace.
deep_link_domain_no_domain_configured:
summary: deep_link_domain - no deep linking domains configured
value:
response_id: abc-101
error:
code: BAD_REQUEST
message: >-
deep_link_domain cannot be processed because no deep linking
domains have been configured for this workspace. Please set
up a domain in your MoEngage dashboard settings first.
target: campaign_content.content.email
details:
- target: campaign_content.content.email.deep_link_domain
message: >-
deep_link_domain cannot be processed because no deep
linking domains have been configured for this workspace.
deep_link_domain_no_match:
summary: deep_link_domain - does not match a configured domain
value:
response_id: abc-101
error:
code: BAD_REQUEST
message: >-
The provided deep_link_domain does not match any of the
configured domains for this workspace. Please verify the
domain name and try again.
target: campaign_content.content.email
details:
- target: campaign_content.content.email.deep_link_domain
message: >-
The provided deep_link_domain does not match any of the
configured domains for this workspace.
from_address_personalization_not_enabled:
summary: >-
from_address - personalized value used without
EMAIL_FROM_ADDRESS_PERS enabled
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: campaign_content.content.email.from_address
message: >-
Personalized from_address is not supported for this
workspace. Remove the personalization token, or ask
support to enable EMAIL_FROM_ADDRESS_PERS.
from_address_invalid_email:
summary: from_address - not a valid email address
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: campaign_content.content.email.from_address
message: from_address is not a valid email address
reply_to_address_invalid_email:
summary: reply_to_address - not a valid email address
value:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
details:
- target: campaign_content.content.email.reply_to_address
message: reply_to_address is not a valid email address
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). Find it in the MoEngage dashboard at **Settings** > **Account** >
**API keys**.
- **Password**: Use an API key from **Settings** > **Account** > **API
keys**.
Refer to [API Key
Dashboard](/user-guide/settings/account/api-and-api-keys/api-key-dashboard)
for details on creating and managing API keys.
````