Create campaign

API Description

Create

post

Create a new campaign

Authorizations

rest_key

AuthorizationstringRequired

API Key Authentication

Authentication is required in order to interact with Batch's APIs.

Batch implements authentication using API Keys, that we call the "REST API Key". You can find it on your dashboard.

Please make sure that you keep this key secret. You should never use it in client apps to call APIs from there as it would easily be extractable.

How to authenticate

In order to authenticate your requests, add your REST API Key in the Authorization header and prefix it by Bearer. Example: Authorization: Bearer bcd38d9rfb38ra28.

Header parameters

X-Batch-ProjectstringRequired

The unique project key, identifying a project on the Batch platform

Example: project_0664hxvwffvbpn278gxdyhsadddqgna6

Body

application/json

namestringRequired

Display name of the campaign on the dashboard

statestring · enumRequired

State of the campaign to create. Draft campaigns are not sent until they are started (updated to RUNNING). Stopped campaigns are paused and can be resumed by updating them to RUNNING.

Possible values:

send_rateinteger · min: 1000 · max: 1000000Optional

Determines the maximum number of messages to be sent per minute.

labelsstring[]Optional

An array of labels to assign to the campaign for organizational and capping purposes. Limited at 5 labels per campaign.

Responses

201

Request successful, campaign created

application/json

Responseone of

400

The request is malformed

application/json

401

The Rest API Key is not valid for this project

application/json

429

Too Many Requests

application/json

500

Unexpected error

application/json

503

Batch's services are under maintenance. Please try again later

application/json

post

/campaigns/create

HTTPcURLJavaScriptPython

POST /2.8/campaigns/create HTTP/1.1
Host: api.batch.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-Batch-Project: text
Content-Type: application/json
Accept: */*
Content-Length: 416

{
  "name": "The campaign name",
  "state": "RUNNING",
  "send_rate": 100000,
  "when": {
    "local_time": false,
    "start_time": "now"
  },
  "targeting": {
    "languages": [
      "fr"
    ],
    "regions": [
      "FR"
    ],
    "query": {
      "firstname": {
        "$eq": "Jane"
      }
    }
  },
  "labels": [
    "promo",
    "holiday"
  ],
  "messages": [
    {
      "channel_type": "email",
      "subject": "The campaign subject",
      "sender_identity_id": "4012",
      "reply_to": {
        "email_address": "[e-mail]"
      },
      "html": "The campaign HTML content"
    }
  ]
}

email nowemail scheduledpush multi-platformspush multi-languages

{
  "id": "orchestration_0664hyh918hr1gnzka9py5t62nrc0e1q"
}

Request structure

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

/campaigns/create

Headers and authentication

See Overview → Using Project APIs.

Post data

Exemple of a request body:

  {
    "name": "The campaign name",
    "state": "RUNNING",
    "send_rate" : 100000,
    "labels": ["myLabel1", "myLabel2"],
    "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": "[e-mail]"
        },
        "html": "The campaign HTML content",
        "languages" : [
          {
            "language" : "en",
            "subject" : "The campaign subject",
            "sender_identity_id" : "4012",
            "reply_to": {
              "email_address": "[e-mail]"
            },
            "html": "The campaign HTML content in english"           
          },
          {
            "language" : "fr",
            "subject" : "le sujet de la campagne",
            "sender_identity_id" : "4034",
            "reply_to": {
              "email_address": "[e-mail]"
            },
            "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",
  "send_rate" : 100000,
  "labels": ["myLabel1", "myLabel2"],

For the time being, Batch supports the "RUNNING", "STOPPED" and "DRAFT" state for a campaign.

Send rate (optional)

Send_rate sets the maximum sending speed for the campaign. The value must be an integer between 1,000 and 1,000,000, representing the number of messages sent per minute. This parameter is optional : if not set, the campaign will be sent at the maximum system speed.

Labels (optional)

An array of up to 5 unique label strings. These labels must have already been created via Dashboard, otherwise an error will be thrown.

When block

Describing when to send the campaign - required.

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

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"
      }
    }
  }

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": "[e-mail]"
      },
      "html": "The campaign HTML content",
      "languages" : [
        {
          "language" : "en",
          "subject" : "The campaign subject",
          "sender_identity_id" : "4012",
          "reply_to": {
            "email_address": "[e-mail]"
          },
          "html": "The campaign HTML content in english"           
        },
        {
          "language" : "fr",
          "subject" : "Le sujet de la campagne",
          "sender_identity_id" : "4034",
          "reply_to": {
            "email_address": "[e-mail]"
          },
          "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

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

iOS specific attributes

The iOS object can specify some attributes:

• deeplink

• custom payload

Android specific attributes

The Android object comes with android properties:

• deeplink

• custom payload

• media (icon)

• Collapse key

Web specific attributes

The Web object can specify some attributes:

• deeplink

• media (icon)

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.

All required parameters at the top level of a message is also required in any given translation.

Email & Push messages can both be translated.

Responses

Success

If the POST to the API endpoint is successful 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 [e-mail] 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.

Note than A/B testing cannot be performed via the API.