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

Create

post

Create a new campaign

Authorizations

Header parameters

X-Batch-Projectstringrequired

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

Example: project_0664hxvwffvbpn278gxdyhsadddqgna6

Body

namestringrequired

Display name of the campaign on the dashboard

statestring · enumrequired

Only RUNNING state supported for now

Available options:

whenobjectrequired

Campaign programation details (when/how to send)

targetingobjectoptional

Who should be reached by the campaign

messagesone of[]required

Messages to send, only one kind of message is allowed at a time.

Responses

application/json

one ofoptional

application/json

application/json

application/json

application/json

application/json

post

HTTPcURLJavaScriptPython

POST /2.4/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: 368

{
  "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": "[email protected]"
      },
      "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:

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

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