POST - Create campaign

Campaign API is designed for broad audience interactions, allowing you to send messages to large groups of users. You can target either your entire user base or specific segments using Batch's segmentation features.

This API supports the creation, updating, and deletion of campaigns, giving you full control over your messaging strategies.

API Description

This API schema is available in the OpenAPI 3.1 format: View it online.

Request structure

Campaign API exposes a POST endpoint that allows to create a campaign:

https://api.batch.com/2.4/campaigns/create

Headers and authentication

See Overview → Using Project APIs.

Post data

Exemple of a request body:

  {
    "name": "The campaign name",
    "state": "RUNNING",
    "when": {
      "local_time": false,
      "start_time": "now"
    },
    "targeting": {
      "languages": [
        "fr"
      ],
      "regions": [
        "FR"
      ],
      "query": {
        "firstname": {
          "$eq": "Jane"
        }
      }
    },
    "messages": [
      {
        "channel_type": "email",
        "subject": "The campaign subject",
        "sender_identity_id": "4012",
        "reply_to": {
          "email_address": "jane.doe@demobatch.com"
        },
        "html": "The campaign HTML content",
        "languages" : [
          {
            "language" : "en",
            "subject" : "The campaign subject",
            "sender_identity_id" : "4012",
            "reply_to": {
              "email_address": "jane.doe@demobatch.com"
            },
            "html": "The campaign HTML content in english"           
          },
          {
            "language" : "fr",
            "subject" : "le sujet de la campagne",
            "sender_identity_id" : "4034",
            "reply_to": {
              "email_address": "jean.dupont@demobatch.fr"
            },
            "html": "HTML en français"            
          }
        ]
      }
    ]
  }

The body must include a valid JSON payload containing the following blocks:

General information about the campaign.
"When" part (Required) which indicates when to send the campaign.
"Targeting" which indicates who will be the recipients of the campaign (default is the entire user base).
"Messages" part (Required) describing the message to send. Payload will be different if you want to send an email or a push message.

Campaign general information

Describing name and state of the campaign.

  "name": "The campaign name",
  "state": "RUNNING"

For the time being, Batch only supports the "RUNNING" state for a campaign.

Id	Description
`name`	String - Required Display name of the campaign on the dashboard. E.g.`{"name":"My Engagement Campaign"}`
`state`	string - Required State of the created campaign. It can only be RUNNING for now. It means that the created campaign will be running (green dot in the Dashboard) immediately after being created. E.g.`{"state":"RUNNING"}`

When block

Describing when to send the campaign - required.

  "when": {
    "local_time": false,
    "start_time": "now"
  }

Id	Description
`local_time`	Boolean - Required - Default : FALSE Can be FALSE or TRUE. Default is FALSE. TRUE means we'll respect user timezone when sending messages and implies the campaign will take 24 hours to complete. E.g.`{"local_time":"true"}`
`start_time`	String - Required Campaign start date in UTC in a RFC 3339 date-time format (for example `2023-10-24T10:22:00Z` ) or `now` to start the campaign as soon as the call is made. E.g.`{"start_time":"2023-10-24T10:22:00Z"}`

Targeting block

Describing who will be reached by the campaign. This block is not required, if you omit it, Batch will consider sending the campaign to the entire user base.

  "targeting": {
    "languages": [
      "fr"
    ],
    "regions": [
      "FR"
    ],
    "query": {
      "firstname": {
        "$eq": "Jane"
      }
    }
  }

Id	Description
`languages`	Array[String] - Optional An array containing all device languages to be targeted. See supported language codes here . E.g.`{"languages":["it","fr"]}`
`regions`	Array[String] - Optional An array containing all the geographical regions codes to be targeted. See supported language codes here . E.g.`{"regions":["FR","US"]}`
`query`	Object - Optional Targeting query leveraging Profile fields. It is a mongo inspired query object containing filters & operators, based on native attributes (app version, OS version, etc) and users data (attributes, tags & events defined by you in the SDK). It is possible to use the Dashboard UI to prepare the query, then copy it and paste it in the payload.

Messages block - for email

Describing the messages to send when sending an email campaign - required.

  "messages": [
    {
      "channel_type": "email",
      "subject": "The campaign subject",
      "sender_identity_id": "4012",
      "reply_to": {
        "email_address": "jane.doe@demobatch.com"
      },
      "html": "The campaign HTML content",
      "languages" : [
        {
          "language" : "en",
          "subject" : "The campaign subject",
          "sender_identity_id" : "4012",
          "reply_to": {
            "email_address": "jane.doe@demobatch.com"
          },
          "html": "The campaign HTML content in english"           
        },
        {
          "language" : "fr",
          "subject" : "Le sujet de la campagne",
          "sender_identity_id" : "4034",
          "reply_to": {
            "email_address": "jean.dupont@demobatch.fr"
          },
          "html": "HTML en français"            
        }
      ]
    }
  ]

messages is an array that can only contain one element.

Channel type

value should be email

Sender Identity

Sender identity describes which sender email will be used. This sender needs to be created before the API Call. If not existing, it will not generate a new ID and the API Call will fail. Sender identity ID can be found on the dashboard (Email channel settings).

languages array

Email messages are available with multi-language ( see specific section).

Id	Description
`channel_type`	String - Required Type of channel. `email` or `push` E.g.`{"channel_type":"email"}`
`subject`	String - Required Email subject. It can contain personalization fields. E.g.`{"subject":"Weather forecast for tomorrow"}`
`sender_identity_id`	String - Required Identifier of the sender. Senders are configured in the Dashboard and this ID can be found in each sender page. E.g.`{"sender_identity_id":"124"}`
`reply_to`	Object - Optional Email Reply To address
`reply_to`	`email_address`	String - Required if `reply_to` is present `reply_to` allows you to specify the email that will be input when the person replies to the email sent. E.g.`{"email_address":"hello@batch.com"}`
`html`	String - Required Html allows you to pass the full html of the email. the html must be escaped. Be careful to respect email inbox providers guidances in terms of email size.
`languages`	Array[Object] - Optional Multi-language feature. See specific section.

Messages block - for push

Describing the messages to send when sending a push campaign - required.

  "messages": [
    {
      "channel_type": "push",
      "platform_type" : ["ios","android"],
      "title": "The campaign title",
      "body": "The campaign body",
      "time_to_live": 3600,
      "media": {
        "picture": "https://example.com/"
      },
      "priority": "normal",
      "push_type": "alert",
      "filter_push_tokens" : "collected",
      "ios": {
        "deeplink": "https://example.com/",
        "custom_payload": "{\"tag\":\"wake up push\", \"landing_screen\":\"greeting\"}"
      },
      "android": {
        "deeplink": "https://example.com/",
        "custom_payload": "{\"tag\":\"wake up push\", \"landing_screen\":\"greeting\"}",
        "media": {
          "icon": "https://example.com/"
        },
        "collapse_key": {
          "enabled": true,
          "key": "default"
        }
      },
      "web": {
        "deeplink": "https://example.com/",
        "media": {
          "icon": "https://example.com/"
        }
      }
    }
  ]

messages is an array that can only contain one element.

Channel type

value should be push

Filter push tokens

filter_push_tokens allows you to target collected tokens or imported tokens, or both.

all : the campaign will target imported and collected push tokens
collected : the campaign will target only collected push tokens, detected by Batch SDKs
imported : the campaign will target only imported push tokens, not yet detected by Batch SDKs

iOS / Android / Web platorms

A push campaign can send the same message to several platforms, using the platform_type Array. You can select one platform only or a combination of 2 or 3 platforms. You can add some platform specific values for a platform by setting them inside of the ios, android and web objects.

languages array

Push messages are available with multi-language ( see specific section).

Id	Description
`channel_type`	String - Required Type of channel. `email` or `push` E.g.`{"channel_type":"push"}`
`platform_type`	Array[String] - Required Selected platforms : `ios` , `android` or `web` E.g.`{"platform_type":["ios,android"]}`
`title`	String - Optional Push title. It can contain personalization fields. E.g.`{"subject":"Weather forecast for tomorrow"}`
`body`	String - Required Push body. It can contain personalization fields. E.g.`{"body":"sunny weather tomorrow"}`
`time_to_live`	Integer (seconds) - Optional - Default: 0 (no expiry) Time to live (TTL) represents the time a notification can be held for delivery in seconds before expiring. If a user was offline and comes back online after this duration, the notification will not be delivered. It does not remove notifications already delivered to devices. Setting a value of `0` disables the TTL, which leaves expiration up to the platform push service. E.g.`{"time_to_live":3600}`
`media`	Object - Optional Rich notification content (only image is supported). This value will be used for Android and iOS platforms.
`media`	`picture`	String - Optional URL to an image that will be displayed as the main notification image. The file must be a RGB PNG or JPG image with a minimum height of 300px and width of 200px. Your server must support the HTTP OPTION verb. Can use personalization. E.g.`{"picture":"https://example.com/picture.png"}`
`priority`	String - Optional - Default: high Defines the priority of your message on iOS (APNS) and Android (FCM). Can be `normal` or `high` . If you set `push_type` to `background` , this value MUST be `normal` . E.g.`{"priority":"high"}`
`push_type`	String - Optional - Default: alert Push type. Can be `alert` or `background` . E.g.`{"push_type":"alert"}`
`filter_push_tokens`	String - Optional - Default: collected Push tokens to be targeted, Can be `collected` (Tokens already deteted by Batch SDKs), `imported` (Manually imported tokens, not yet detected by Batch SDKs) or `all` . E.g.`{"filter_push_tokens":"collected"}`
`ios`	Object - Optional iOS specific attributes. See iOS specific attributes section.
`android`	Object - Optional Android specific attributes. See Android specific attributes section.
`web`	Object - Optional Web specific attributes. See Web specific attributes section.
`languages`	Array[Object] - Optional Multi-language feature. See specific section.

iOS specific attributes

The iOS object can specify some attributes:

deeplink
custom payload

Id	Description
`ios`	Object - Optional iOS specific values
	`deeplink`	String - Optional Push deeplink. Cannot be longer than 1024 characters. It can contain personalization fields. E.g.`{"deeplink":"https://example.com/"}`
	`custom_payload`	String - Optional Payload that should sent in the push notification's data. String representation of a JSON object. Can be used to override standard keys, such as `aps`. Using the `com.batch` key is forbidden. It can contain personalization fields. E.g.`{"custom_payload":"{\"tag\":\"wake up push\", \"landing_screen\":\"greeting\"}"}`

Android specific attributes

The Android object comes with android properties:

deeplink
custom payload
media (icon)
Collapse key

Id	Description
`Android`	Object - Optional Android specific values
	`deeplink`	String - Optional Push deeplink. Cannot be longer than 1024 characters. It can contain personalization fields. E.g.`{"deeplink":"https://example.com/"}`
	`custom_payload`	String - Optional Payload that should sent in the push notification's data. String representation of a JSON object. Can be used to override standard keys, such as `aps`. Using the `com.batch` key is forbidden. It can contain personalization fields. E.g.`{"custom_payload":"{\"tag\":\"wake up push\", \"landing_screen\":\"greeting\"}"}`
	`media`	Object - Optional Rich notification content. The only allowed key is `icon` which should be an URL to a square PNG or JPEG with a minimum size 196x196. See the API reference for more info.
	`collapse_key`	Object - Optional Defines how notifications are managed when an offline device goes online (enabled by default) . If enabled, the device will only show the most recent notification. If disabled, it will show all the notifications received when the device was offline. You should disable the collapse key if all your notifications matter (E.g. messages, etc) . You can use up to 3 different collapse keys if you want users to get only one notification of each kind when coming online (E.g. marketing messages, alert, etc) . E.g.`{"enabled":true,"key":"default"}`

Web specific attributes

The Web object can specify some attributes:

deeplink
media (icon)

Id	Description
`web`	Object - Optional Webpush specific values
	`deeplink`	String - Optional Push deeplink. Cannot be longer than 1024 characters. It can contain personalization fields. E.g.`{"deeplink":"https://example.com/"}`
	`media`	Object - Optional Rich notification content. The only allowed key is `icon` which should be an URL to a square PNG or JPEG with a minimum size 196x196. See the API reference for more info.

Multi-language

languages allows you to define many translations. Each item of an array will give you translation of many attributes (content & some parameters) for the designed language.

Email

As soon as a translation is given then all required parameters at the level above are also required here.

Id	Description
`languages`	Array[Object] - Array of translations. Default language content is located at the level above. As soon as a translation is given then all required parameters at the level above are also required here.
	`language`	String - Translation language. E.g.`{"language":"en"}`
	`subject`	String - translated subject E.g.`{"subject":"Weather forecast for tomorrow"}`
	`sender_identity_id`	String - Sender ID for this language E.g.`{"sender_identity_id":"127"}`
	`reply_to`	Object - Email Reply To used for this language
	`html`	String - Translated HTML

Push

As soon as a translation is given then all required parameters at the level above are also required here.

Id	Description
`languages`	Array[Object] - Array of translations. Default language content is located at the level above. As soon as a translation is given then all required parameters at the level above are also required here.
	`language`	String - Translation language. E.g.`{"language":"en"}`
	`title`	String - translated Title E.g.`{"subject":"Title in english"}`
	`body`	String - Required Push body. It can contain personalization fields. E.g.`{"body":"sunny weather tomorrow"}`
	`media`	Object - Optional Rich notification content (only image is supported). This value will be used for Android and iOS platforms.
	`ios`	Object - Optional iOS specific attributes. See iOS specific attributes section.
	`android`	Object - Optional Android specific attributes. See Android specific attributes section.
	`web`	Object - Optional Web specific attributes. See Web specific attributes section.

Responses

Success

If the POST to the API endpoint is successfull you will receive an HTTP 201 confirmation.

Failure

If the POST data does not meet the API requirements you will receive an actionable error message. Contact us at support@batch.com if you need further support.

AUTHENTICATION_INVALID (Http status code: 401, Error code: 10)
API_MISUSE (Http status code: 403, Error code: 12)
ROUTE_NOT_FOUND (Http status code: 404, Error code: 20)
MISSING_PARAMETER (Http status code: 400, Error code: 30)
MALFORMED_PARAMETER (Http status code: 400, Error code: 31)
MALFORMED_JSON_BODY (Http status code: 400, Error code: 32)
SERVER_ERROR (Http status code: 500, Error code: 1)
MAINTENANCE_ERROR (Http status code: 503, Error code: 2)
TOO_MANY_REQUESTS (Http status code: 429, Error code: 60)
If you get a "too many requests" response, please wait for at least 5 seconds before trying again. Further requests might still return this error.

Next stepUpdating a campaign

Documentation > APIs > Campaign API

POST - Create campaign

API Description

Request structure

Headers and authentication

Post data

Campaign general information

When block

Targeting block

Messages block - for email

Channel type

Sender Identity

languages array

Messages block - for push

Channel type

Filter push tokens

iOS / Android / Web platorms

languages array

iOS specific attributes

Android specific attributes

Web specific attributes

Multi-language

Email

Push

Responses

Success

Failure