Create Campaign Draft (V5)

curl --request POST \
  --url https://api-{dc}.moengage.com/v5/campaigns \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "request_id": "{{request_id}}",
  "channel": "PUSH",
  "campaign_delivery_type": "ONE_TIME",
  "created_by": "{{user_email}}",
  "basic_details": {
    "name": "{{campaign_name}}",
    "platforms": [
      "ANDROID"
    ]
  },
  "campaign_content": {
    "content": {
      "push": {
        "android": {
          "template_type": "BASIC",
          "basic_details": {
            "notification_channel": "{{notification_channel}}",
            "title": "{{title}}",
            "message": "{{message}}",
            "default_click_action": "DEEPLINKING",
            "default_click_action_value": "{{deep_link_url}}"
          }
        }
      }
    }
  },
  "scheduling_details": {
    "delivery_type": "ASAP"
  }
}
'

{
  "response_id": "abc-101",
  "type": "campaign",
  "data": {
    "id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "status": "DRAFT",
    "campaign_delivery_type": "ONE_TIME"
  }
}

POST

campaigns

curl --request POST \
  --url https://api-{dc}.moengage.com/v5/campaigns \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "request_id": "{{request_id}}",
  "channel": "PUSH",
  "campaign_delivery_type": "ONE_TIME",
  "created_by": "{{user_email}}",
  "basic_details": {
    "name": "{{campaign_name}}",
    "platforms": [
      "ANDROID"
    ]
  },
  "campaign_content": {
    "content": {
      "push": {
        "android": {
          "template_type": "BASIC",
          "basic_details": {
            "notification_channel": "{{notification_channel}}",
            "title": "{{title}}",
            "message": "{{message}}",
            "default_click_action": "DEEPLINKING",
            "default_click_action_value": "{{deep_link_url}}"
          }
        }
      }
    }
  },
  "scheduling_details": {
    "delivery_type": "ASAP"
  }
}
'

{
  "response_id": "abc-101",
  "type": "campaign",
  "data": {
    "id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "status": "DRAFT",
    "campaign_delivery_type": "ONE_TIME"
  }
}

Component reference pages:

For the full schema of basic_details and campaign_content per channel, platform, and template type :
- Android (BASIC / STYLIZED_BASIC / SIMPLE_IMAGE_CAROUSEL / IMAGE_BANNER_WITH_TEXT / TIMER / TIMER_WITH_PROGRESS_BAR / Custom)
- iOS (BASIC / STYLIZED_BASIC / SIMPLE_IMAGE_CAROUSEL / Custom)
- Web BASIC
- Email (html_content and custom_template_id), see Campaign content reference.
For the order in which MoEngage resolves a placeholder across content blocks, trigger-request attributes, and user profile attributes, see Content for API-triggered shells.
For the full schema of trigger_condition, segmentation_details, scheduling_details, delivery_controls, conversion_goal_details, control_group_details, utm_params, campaign_audience_limit, advanced, and geofences, see Audience and delivery reference.

Rate Limits

Rate Limit Name	Rate Limit
Create campaign per minute	The total number of create campaign operations per minute per client allowed is 5.
Create campaign per hour	The total number of create campaign operations per hour per client allowed is 25.
Create campaign per day	The total number of create campaign operations per day per client allowed is 100.

Campaign Creation Limits

You can create 5 campaigns per minute, 25 campaigns per hour, and 100 campaigns per day.

Notes

Higher limit (Total Calls): The system permits a higher volume of total API calls (for example, 120 calls) to accommodate potential failures or retries.
Minimum limit (Campaign Creation Limits): The system maintains a stricter quota for actual successful creations (100 campaigns per day).

Example: If a client submits 120 requests and 20 fail, they successfully generate exactly 100 campaigns. Because the system applies the most restrictive threshold, the 100 successful operations trigger the quota limit, and the system issues a rate limit breach warning regardless of the total API calls made.

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.

Authorizations

Authorization

string

header

required

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 for details on creating and managing API keys.

Headers

MOE-APPKEY

string

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.

X-MOE-Request-Id

string

Client-supplied trace ID. The server echoes it in the X-MOE-Request-Id response header and in response_id. If you omit it, the server generates one.

Idempotency-Key

string<uuid>

required

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.

Body

application/json

Campaign payload. Required top-level fields are channel, campaign_delivery_type, and created_by. Optional sections (basic_details, campaign_content, audience, scheduling, and so on) can be omitted or supplied in full. Note: Use the tabs below to select your campaign type. The schema adapts based on the selected channel.

Push Campaign
Email Campaign

Request body for creating a Push campaign draft via POST /v5/campaigns.

Only channel, campaign_delivery_type, and created_by are required. Optional components (basic_details, campaign_content, segmentation_details, and so on) can be included in the same request, or added later via PATCH /v5/campaigns/{campaign_id}.

For full examples per delivery type, refer to campaign_delivery_type below. For the component-level schemas with conditional rules per template type, platform, and delivery type, refer to:

Campaign content reference — basic_details and campaign_content.
Audience and delivery reference — trigger_condition, segmentation_details, scheduling_details, delivery_controls, conversion_goal_details, control_group_details, utm_params, campaign_audience_limit, advanced, and geofences.

channel

enum<string>

required

The campaign channel. One of PUSH or EMAIL.

Available options:

PUSH

campaign_delivery_type

enum<string>

required

The delivery type of the campaign.

Note: BROADCAST_LIVE_ACTIVITY is not supported through the draft-based creation flow.

For full request payloads per delivery type, see the code examples on this page.

Available options:

ONE_TIME,

PERIODIC,

EVENT_TRIGGERED,

BUSINESS_EVENT_TRIGGERED,

DEVICE_TRIGGERED,

LOCATION_TRIGGERED

created_by

string<email>

required

The email ID of the user creating this campaign.

Example:

"[email protected]"

request_id

string

A unique identifier for this campaign creation request.

Important: After successful campaign creation, do not reuse this request_id for the next 1 hour. If campaign creation fails, you can immediately retry with the same request_id.

Example:

"{{request_id}}"

basic_details

object

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.

Show child attributes

trigger_condition

object

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.

Show child attributes

campaign_content

object

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, iOS push content, or Web push content.

Show child attributes

segmentation_details

object

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.

Show child attributes

scheduling_details

object

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.

Show child attributes

delivery_controls

object

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.

Show child attributes

advanced

object

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.

Show child attributes

conversion_goal_details

object

Configuration for tracking campaign conversion goals.

For runnable single-goal and multi-goal examples, refer to Conversion goal tracking.

Show child attributes

control_group_details

object

Configuration for control groups.

For runnable campaign-control-group and global-control-group examples, refer to Control groups.

Show child attributes

utm_params

object

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.

Show child attributes

campaign_audience_limit

object

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.

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:

{
  "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.

Show child attributes

Response

Draft created

response_id

string

type

string

Example:

"campaign"

data

object

Payload returned when a draft is successfully created.

Show child attributes

API Documentation

Endpoints

Create Campaign Draft (V5)

Rate Limits

Campaign Creation Limits

Authorizations

Headers

Body

Response