Campaign Meta and Reachability API

You can use this API to get the details of the campaign as well as the reachability of the scheduled campaigns.

API Endpoint

Method: POST

https://api-0X.moengage.com/core-services/v1/campaigns/meta

Each customer is hosted on a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping page.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username: password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization: Basic Base64_ENCODED_APPKEY_APIKEY=="}

You can obtain the username and password details from the MoEngage Dashboard.

Navigate to Settings -> Account -> APIs.
Copy the following details:
- Username: Under Workspace ID (earlier APP ID), click the copy icon to copy the username.
- Password: In the API keys section, click the copy icon in the Campaign report/Business events/Custom templates tile to copy the API key.
Use these details to authenticate the API requests.

Request Headers

Key

Required

Sample Values

Description

Content-Type

Required

{"Content-Type": "application/json"}

Set the Content-Type header to application/json.

Authorization

Required

{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}

This authentication parameter, used for access control, must be passed in the request. To generate the authentication header, refer to Authentication.

MOE-APPKEY

Required

{“MOE-APPKEY”: “Workspace ID”}

This is the workspace ID (earlier APP ID) of your MoEngage workspace. The MOE-APPKEY has to be passed in the request. You can find your MoEngage Workspace ID in the MoEngage Dashboard:

Settings -> Account -> APIs -> Workspace ID (earlier APP ID)

For more information, refer to Authentication.

Request Body

Key	Required	Values	Description
campaign_fields	Optional	JSON Object	This object contains the campaign info details. For more information, refer to Campaign Fields Details.
limit	Required	Number	This field denotes the number of campaigns to be displayed on a page. Note: The maximum limit is 15.
page	Required	Number	This field denotes the number of pages to display the campaigns based on the limit. For example, if there are 200 campaigns and you set the limit to 10, there will be 20 pages.
request_id	Required	String	This field denotes the request ID for which the META info of the campaign is fetched.
include_child_campaigns	Optional	Boolean	By default, this field will be false. This field must be true to fetch the details of child campaign.

Campaign Fields

The campaign_fields JSON object contains the following information:

Key	Required	Values	Description
id	Optional	String	This field denotes the unique identifier to identify the campaign.
channels	Optional	Array	This field denotes the type of channel. Currently, the supported value is: EMAIL PUSH SMS WHATSAPP FACEBOOK GOOGLE ADS CONNECTORS
created_by	Optional	Array	This field denotes the Email ID of the user who created the campaign. Supported value is email ID only.
created_date	Optional	JSON Object	This field denotes the date when the campaign was created. For more information, refer to Created Date.
delivery_type	Optional	Array	This field denotes when to deliver your campaign. The supported values are: ONE_TIME PERIODIC EVENT_TRIGGERED BUSINESS_TRIGGERED
name	Optional	String	This field denotes the name of the goal event attribute.
status	Optional	Array	This field denotes the status of the campaign.
tags	Optional	Array	This field provides context about the campaigns and describes the nature of the campaign or the campaign's central theme.

Created Date

The created_date JSON object contains the following information:

Key	Required	Values	Description
from_date	Required	String	This field is of String type and indicates the starting point of the date range in which the campaigns are created.
to_date	Required	String	This field is of String type and indicates the ending point of the date range in which the campaigns are created.

Response Codes

Status Code	Request State	Description
200	Success	This response is returned when the request is processed successfully.
400	Bad Request	This response is returned when the required parameters are missing from the request, the provided parameters are invalid, or the custom template ID and version don't exist in the dashboard.
401	Unauthorized	The request does not have valid authentication credentials.
500	Internal Server Error	This response is returned when the system runs into an unexpected error.

Sample cURL Request

curl --location 'https://api-0X.moengage.com/core-services/v1/campaigns/meta' \
      --header 'content-type: application/json' \
      --header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
      --header 'Authorization: Basic {{Authorization_Key}}' \
      --data-raw '{
      "request_id": "12345",
      "page": 1,
      "limit": 15,
      "campaign_fields": {
      "channels": [
      "EMAIL"
      ],
      "created_by": [
      "abc@gmail.com"
      ],
      "created_date": {
      "from_date": "22-11-2024",
      "to_date": "29-11-2024"
      },
      "delivery_type": [
      "ONE_TIME"
      ],
      "id": "123456789",
      "name": "campaign_name",
      "status": [
      "SCHEDULED"
      ],
      "tags": [
      "tag1"
      ]
      }
      }'

Sample Response

{
      "campaign_id": "{{Campaign_id}}'",
      "channel": "WHATSAPP",
      "platform": [],
      "created_by": "johndoe@abc.com",
      "campaign_delivery_type": "ONE_TIME",
      "campaign_name": "{{Campaign_name}}'",
      "campaign_team": "{{Campaign_team}}'",
      "campaign_tags": [],
      "campaign_status": "Retired",
      "campaign_start_time": "2024-11-18T05:50:00"
      }

{
      "campaign_id": "{{Campaign_id}}",
      "channel": "SMS",
      "platform": [],
      "created_by": "john.doe@abc.com",
      "campaign_delivery_type": "ONE_TIME",
      "campaign_name": "{{Campaign_name}}",
      "campaign_team": "{{Campaign_team}}",
      "campaign_tags": [],
      "campaign_status": "Scheduled",
      "campaign_start_time": "2024-11-28T12:18:00",
      "reachability_details": {
      "count": 18182,
      "last_updated_time": "2024-11-27T09:05:42.661000"
      }
      }

info	Information The reachability_details info is only generated for scheduled one-time, business event-triggered, and event-triggered campaigns.

Response Body

Key	Values	Description
campaign_id	String	This field indicates the campaign ID.
channel	String	This field denotes the type of channel. For example, EMAIL.
Platform	Array	This field denotes the platform types supported for your campaign.
created_by	String	This field denotes the Email ID of the user who created the campaign. The supported value is email ID only.
campaign_delivery_type	String	This field denotes the delivery type associated with your campaign. For example, ONE TIME.
campaign_name	String	This field indicates the campaign name.
campaign_team	String	This field indicates the campaign team name.
campaign_tags	Array	This field indicates the tags associated with the campaign. For example; activation, all users, and engagement.
campaign_status	String	This field denotes the status of the campaign.
campaign_start_time	String	This field denotes the start time of the campaign.
total_child_campiagns	Integer	This field shows the number of child campaigns if the provided campaign ID is of the parent campaign ID and the child campaign ID is true. Ths is only applicable for periodic campaigns.
parent_campaign_id	String	This shows the campaign ID of the parent if the provided campaign ID is a child and the status is true. Only applicable for periodic campaigns.
reachability_details	JSON Object	This field denotes the reachability information associated with your campaign. It is only populated for scheduled campaigns. For more information, refer to reachability_details.

Reachability Details

The reachability_details JSON object contains the following information:

Key	Values	Description
count	Number	This field denotes the number of users your scheduled campaigns have reached.
last_updated_time	String	This field denotes the last updated time of your scheduled campaign.

Response Code Structure

{
      "campaign_id": "{{Campaign_id}}'",
       parent_campaign_id = StringField() // If the requested campaign_id belongs to child campaigns, the respective parent campaign details will be shown here. To fetch this information make sure you pass the request child_camapign_Id as True. 
       total_child_campaigns = IntField() // This will be available if the campaign_id belongs to the parent campaign. Only applicable for periodic campaigns.
      "channel": "SMS",
      "platform": [],
      "created_by": "john.doe@abc.com",
      "campaign_delivery_type": "ONE_TIME",
      "campaign_name": "{{Campaign_name}}",
      "campaign_team": "{{Campaign_team}}",
      "campaign_tags": [],
      "campaign_status": "Scheduled",
      "campaign_start_time": "2024-11-28T12:18:00",
      "reachability_details": {
      "count": 18182,
      "last_updated_time": "2024-11-27T09:05:42.661000"
      }
      }

{
      "error": {
      "code": "400 Bad Request",
      "message": "request_id key is mandatory field",
      "target": "request_id",
      "details": [
      {
      "target": "request_id",
      "message": "request_id key is mandatory field"
      }
      ],
      "request_id": "11"
      }
      }

{
      "error": {
      "code": "400 Bad Request",
      "message": "Campaigns Api sentry flag not enabled",
      "target": "campaigns_api",
      "details": [
      {
      "target": "campaigns_api",
      "message": "Campaigns Api sentry flag not enabled"
      }
      ],
      "request_id": ""
      }
      }

{
      "error": {
      "code": "400 Bad Request",
      "message": "Bad request",
      "details": [
      {
      "target": "limit",
      "message": "Invalid field value passed:limit - Field is required but value is None : None"
      }
      ],
      "request_id": "122"
      }
      }

{
      "error": {
      "code": "400 Bad Request",
      "message": "Bad request",
      "details": [
      {
      "target": "page",
      "message": "Invalid field value passed:page - Field is required but value is None : None"
      }
      ],
      "request_id": "122"
      }
      }

{
      "error": {
      "code": "401 Authentication error",
      "message": "Authentication required",
      "details": [
      {
      "code": "InvalidValue",
      "target": "APP_SECRET_KEY",
      "message": [
      {
      "code": "InvalidValue",
      "target": "APP_SECRET_KEY",
      "message": "Invalid APP_SECRET_KEY is provided."
      }
      ]
      }
      ],
      "request_id": ""
      }
      }

{
      "error": {
      "code": "500 Internal Server Error",
      "message": "Something went wrong. Please contact Moengage team",
      "target": "string",
      "details": [
      {
      "message": "Expecting value: line 1 column 1 (char 0)",
      "target": ""
      }
      ]
      }
      }

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

FAQs

arrow_drop_down Can I get the exact reachability of scheduled campaigns?

No, reachability is an estimated value that may vary over time due to factors such as app installations, uninstalls, or changes in email subscription status.

arrow_drop_down Can reachability be refreshed with every API call?

No, reachability is calculated once daily and cached for 24 hours. Multiple API calls within the same day will return the cached value.