POST - Create campaign

The Campaigns 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

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

https://api.batch.com/2.3/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"
      }
    ]
  }

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

General information about the campaign.
"When" part (mandatory) which indicates when to send the campaign.
"Targeting" which indicates who will be the recipients of the campaign (défault is the entire user base).
"Messages" part (mandatory) 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 - 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] - An array containing all device languages to be targeted. See supported language codes here. E.g.`{"languages":["it","fr"]}`
`regions`	Array[String] - An array containing all the geographical regions codes to be targeted. See supported language codes here. E.g.`{"regions":["FR","US"]}`
`query`	Object - 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"
    }
  ]

The Batch Campaign API currently handles only the first message in this array.

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).

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 - Email Reply To address
`reply_to`	`email_address`	String - `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.

Messages block - for push

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

  "messages": [
    {
      "channel_type": "push",
      "title": "The campaign title",
      "body": "The campaign body",
      "time_to_live": 3600,
      "media": {
        "picture": "https://example.com/"
      },
      "priority": "normal",
      "push_type": "alert",
      "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"
        }
      }
    }
  ]

The Batch Campaign API currently handles only the first message in this array.

Channel type

value should be push

iOS / Android platorms

A push campaign sends the same message to iOS and Android. You can add some platform specific values for a platform by setting them inside of the ios and android objects.

Id	Description
`channel_type`	String - Required Type of channel. `email` or `push` E.g.`{"channel_type":"push"}`
`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 - 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"}`
`ios`	Object - Optional iOS specific attributes. See iOS specific attributes section.
`android`	Object - Optional Android specific attributes. See Android specific attributes 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"}`

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 > API > 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

Messages block - for push

Channel type

iOS / Android platorms

iOS specific attributes

Android specific attributes

Responses

Success

Failure