Create a Scheduled Campaign Draft

The Campaign API lets you programmatically create and manage campaigns in Optimove. This article covers how to create a scheduled campaign draft and retrieve it via API—giving you a flexible, code-driven approach to campaign building before you're ready to launch.

Base URL

https://api5.optimove.net/campaign-api

Overview

A scheduled campaign is sent at a planned date, optionally repeating on a recurrence (daily, weekly, or monthly). A campaign in the draft state is a work-in-progress and never executes until you activate it.

This guide covers:

• The required request shape for a minimum-viable scheduled draft
• How to add a recurrence so the campaign repeats
• How the API responds, including warnings and validation errors

Endpoint

POST /campaigns

Creates a new scheduled campaign in draft state.

Required Headers

Prerequisites

Before calling the endpoint, make sure you have the following set up in your Optimove tenant:

Quick Start

The smallest valid request body for a scheduled draft campaign is:

{
  "state": "draft",
  "campaignType": "scheduled",
  "targetGroupId": 3,
  "exclusionType": 0,
  "startDate": "2026-06-01",
  "controlPercentage": 10,
  "isOptimized": false,
  "reevaluateGroup": false,
  "isRunAnyway": false,
  "actions": [
    {
      "actionId": 22394,
      "percentage": 90,
      "isConditionalExecution": false,
      "channels": [
        {
          "channelId": 15,
          "brandInnerId": "AC09",
          "templates": [
            {
              "templateId": "455297",
              "isDefault": true,
              "executionTime": {
                "time": "10:00",
                "timeZone": "UTC"
              }
            }
          ]
        }
      ]
    }
  ],
  "tags": []
}

And the equivalent curl call:

curl -X POST https://<your-host>/campaigns \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d @scheduled-draft.json

Request Fields

The request body is a single JSON object that describes the campaign. Fields below apply to the scheduled campaign type.

Top-Level

Recurrence Patterns

Omit recurrence (or send null) for a one-off campaign. To make the campaign repeat, attach a recurrence object.

Common Recurrence Fields

Daily — Example

{
  "recurrence": {
    "type": "Daily",
    "interval": 1,
    "endType": "AfterOccurrences",
    "numberOfOccurrences": 10
  }
}

Weekly — Example

For weekly recurrence, at least one day must be selected in selectedDays. If startDate does not fall on a selected day, the API adjusts it forward to the first selected day on or after the requested date and returns a warning.

{
  "recurrence": {
    "type": "Weekly",
    "interval": 2,
    "endType": "AfterOccurrences",
    "numberOfOccurrences": 20,
    "selectedDays": [
      { "day": "Tuesday",  "isSelected": true },
      { "day": "Thursday", "isSelected": true }
    ]
  }
}

Monthly — by Day of the Month

{
  "recurrence": {
    "type": "Monthly",
    "interval": 1,
    "endType": "AfterOccurrences",
    "numberOfOccurrences": 6,
    "monthlyPattern": "DayOfMonth",
    "dayOfMonth": 10
  }
}

dayOfMonth must match the day component of startDate.

Monthly — by Day of the Week

{
  "recurrence": {
    "type": "Monthly",
    "interval": 1,
    "endType": "EndByDate",
    "endDate": "2026-12-31",
    "monthlyPattern": "DayOfWeek",
    "dayOfWeekInMonth": {
      "weekOfMonth": "Last",
      "dayOfWeek": "Friday"
    }
  }
}

weekOfMonth accepts "First", "Second", "Third", "Fourth", or "Last". The dayOfWeek must match the weekday of startDate. If startDate is on the 29th or later, weekOfMonth must be "Last".

Actions & Channels

actions is an array of 0–4 action objects. Each action represents a campaign variant: it targets a portion of the audience (via percentage) and is delivered through one or more channels.

Action Object

Channel Object

Template Object

Successful Response

A successful call returns 201 Created with the full created campaign and an optional warnings list.

{
  "isSuccess": true,
  "data": {
    "campaign": {
      "id": "68f63f3d15d41b0012c6f486",
      "displayId": "D12345",
      "state": "draft",
      "campaignType": "scheduled",
      "startDate": "2026-06-01"
      // ...all fields you sent, plus server-applied defaults
    },
    "warnings": null
  }
}

Identifiers in the Response

• id—The draft's identifier (24-character hex string). Use this in subsequent Update, Get, Delete, and Activate calls
• displayId—A display-friendly identifier intended for UI use. Do not use it for API lookups

Warnings

Warnings are non-fatal: the campaign was created, but something was adjusted or skipped. Common warnings include client-supplied service-managed fields being dropped, or a default value being applied for an absent setting.

Errors

The endpoint maps failures to standard HTTP status codes.

Validation Error Shape

{
  "isSuccess": false,
  "data": {
    "errors": {
      "controlPercentage": ["Action percentages and control percentage must sum to 100."],
      "recurrence.endDate": ["EndDate cannot be before StartDate."]
    }
  },
  "errorCode": "BUSINESS_RULE_VIOLATION"
}

Draft Lifecycle

A draft is not executed until it is activated. After creating it, you can:

• Update it with PUT /campaigns/{id}—drafts are always fully editable
• Get it with GET /campaigns/scheduled/{id}
• Delete it with DELETE /campaigns/scheduled/{id}—soft-deletes the draft

Need help? Contact your Optimove integration manager or open a support ticket and reference this guide.