Create Campaign Draft (V5)

Creates a Push or Email campaign draft. Content, audience, and delivery settings can be included at the time of creation, or added later via PATCH /v5/campaigns/{campaign_id}.

POST /v5/campaigns

cURL

push_one_time

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>' \
  --header 'MOE-APPKEY: <moe-appkey>' \
  --header 'X-MOE-Request-Id: <x-moe-request-id>' \
  --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"
  }
}
'

201

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

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

{
  "response_id": "abc-101",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing credentials.",
    "details": []
  }
}

{
  "response_id": "abc-101",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded for app key.",
    "details": []
  }
}

{
  "response_id": "abc-101",
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error.",
    "details": []
  }
}

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 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 second	The total number of create campaign operations per second per client allowed is 5.
Create campaign per minute	The total number of create campaign operations per minute per client allowed is 25.
Create campaign per hour	The total number of create campaign operations per hour 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). 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.

Send the value in the Authorization header as Basic followed by Base64-encoding of appkey:apisecret (workspace ID and API key).

Headers

MOE-APPKEY · string · required

Your MoEngage Workspace ID (App ID). Find it in the dashboard at Settings > Account > APIs > Workspace ID.

X-MOE-Request-Id · string · required

Correlates with response_id. Supply this header or request_id in the body; if both are set, they must match.

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:

"[e-mail]"

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

201

application/json

Draft created

response_id · string

type · string

Example:

"campaign"

data · object

Payload returned when a draft is successfully created.

Show child attributes