POST - Create campaign

The Campaigns API is made for 1-to-many interactions. It allows you to send message to a large audience of users. You can use it to target all your userbase or a specific segment of users relying on Batch segmentation.

The Campaign API will allow Create, Update, and Delete a campaign.

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.2/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 contain a valid JSON payload and will contain these 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.

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

Describing the messages to send - 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 only handles only the first message in this array.

Channel type

Only email channel is supported.

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. Only email is allowed for now. 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	String - Email Reply To address
	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.

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.