Setting Up Conditional Execution

Conditional Execution for Scheduled Campaigns

Step 1: Register a Listener

Your system needs to register a listener to receive notifications for scheduled Conditional Execution campaigns using EventTypeID=5. Use the RegisterEventListener API call. This step only needs to be done once for all future scheduled conditional campaigns.

Step 2: Optimove Notifies the Listener that the Campaign is Ready to be Sent

Once the campaign uses Conditional Execution, Optimove processes the campaign and notifies the listener of your system specified for EventTypeID=5. At this point, Optimove will wait until the Clearance Required By time has arrived before actually scheduling the campaign for execution.

Important Note:

When using Conditional Execution, the Target Group of the campaign will be sent to your internal system in advance, giving your system time to review the customers and decide whether they should receive the campaign. The approval should arrive by the Clearance Required By time, which by default is 30 minutes before campaign execution (configurable upon request).

The Clearance Required By time is communicated to the listener at the time of the EventTypeID=5 notification.

The structure of the request:

{
  "EventTypeID": 5,
  "TimeStamp": "YYYY-MM-DD HH:MM:SS",
  "CampaignID": x,
  "CampaignDuration": y,
  "ClearanceRequiredBy": "YYYY-MM-DD HH:MM:SS"
}

Note: ClearanceRequiredBy is calculated by Optimove based on the campaign's selected execution channel(s).

Step 3: Internal Systems Review Which Customers Receive the Campaign

Once your listener receives a notification that the campaign is ready, your system calls GetProcessedCampaignCustomers to retrieve the list of customers included in this campaign.

Step 4: Notify Optimove Which Customers Should Receive the Campaign

Once the customers have been reviewed, your system notifies Optimove that customers should receive the campaign. This is accomplished using the UpdateCustomerPromotionStatus API call.

Step 5: Optimove Sends the Campaign to Eligible Customers

Once the campaign's specified Clearance Required By time arrives, Optimove will schedule the campaign for execution only to the approved customers.

Customers that were not approved will not receive the campaign.

Conditional Execution V2 for Scheduled Campaigns

Conditional Execution V2 introduces more granular control over campaign approvals — instead of approving a whole campaign before its first execution, approval happens at the Send Group level, much closer to the actual send time. This makes V2 a better fit for multi-template campaigns and campaigns that use Send Time Optimization (STO).

⚠️

V1 or V2 — not both

A site can run on either V1 or V2, but not both. If you choose to implement V2, do not use the V1 API calls described above.

V2 is only supported for Campaign Execution 2.0 clients.

Key Concepts

Send Group — a set of customers scheduled to receive the same template at the same send time. Approval happens at this level rather than at the whole campaign level.

Send Time Optimization (STO) — when each customer receives the campaign at their own optimal time within a defined window. Approvals are made per batch, based on the exact send time assigned to each customer.

Multi-template campaigns — customers are approved per template, with each template having its own send time and approval deadline.

Approval Process

Step 1: Register a Webhook for the Heads-up Notification (Event Type 18)

Register a webhook to receive a heads-up notification (Event Type 18) before each Send Group's send time. The notification tells your system that the customers in that Send Group are ready for review and approval. This step only needs to be done once for all future V2 scheduled conditional campaigns.

📘

Registration endpoint coming soon

The registration endpoint for Event Type 18 is being finalized — check the Optimove API reference or ask your Customer Success Manager for the current path.

By default, the notification arrives 1 hour before the approval deadline (this heads-up window is configurable by Optimove's operations support team — site-admin control is on the roadmap). The approval deadline is always 15 minutes before the Send Group's scheduled send time.

So for a Send Group scheduled to send at 10:00 with the default 1-hour heads-up window:

• Notification sent at 08:45
• Approval deadline at 09:45
• Send time at 10:00

If Optimove fails to deliver the notification, it will retry up to 3 times.

Notification Payload:

{
  "timestamp": "YYYY-MM-DD HH:MM:SS",
  "send_group": {
    "id": 123,
    "approval_deadline": "YYYY-MM-DD HH:MM:SS",
    "order": 1,
    "number_of_customers": 2500
  },
  "occurrence": {
    "id": 222,
    "series_id": 111,
    "campaign_duration": 1,
    "total_send_groups_with_conditional": 3,
    "number_of_unique_customers": 2500,
    "notes": "campaign notes",
    "tags": ["tag1", "tag2"],
    "action": {
      "id": 576,
      "channel": {
        "id": 345,
        "name": "string",
        "brand_id": "string",
        "template": {
          "id": "string",
          "name": "string"
        }
      }
    }
  }
}

📘

If channel eligibility is configured, customers who don't meet the eligibility criteria are excluded from the Send Group before the heads-up notification is sent.

Step 2: Retrieve Customers in the Send Group

After receiving the notification, call Get Customers in Send Group to retrieve the customers scheduled to receive the campaign in this Send Group, along with any attributes you want to use for review (e.g. first name, loyalty tier).

• Route: GET /v2/conditional-execution/scheduled/send-groups/{send_group_id}/customers?attributes=attribute1,attribute2
• Headers: X-API-KEY
• Success response: 200 OK

Response Payload:

[
  {
    "customer_id": "C12345",
    "promo_codes": ["PROMO2026", "PROMO2"],
    "attributes": {
      "firstName": "John",
      "loyaltyTier": "Gold"
    }
  }
]

Step 3: Approve or Reject Customers

Once you've reviewed the list, submit an approval status for each customer using Update Customer Status in Send Group. Only customers with is_approved: true submitted before the deadline will receive the campaign.

• Route: POST /v2/conditional-execution/scheduled/send-groups/{send_group_id}/approvals
• Headers: X-API-KEY
• Success response: 202 Accepted

Request Payload:

[
  {
    "customer_id": "C12345",
    "is_approved": true
  },
  {
    "customer_id": "C12346",
    "is_approved": false
  }
]

📘

Approved customers who aren't part of the Send Group are ignored.

Step 4: Optimove Sends the Campaign to Approved Customers

At the Send Group's scheduled send time, Optimove sends the campaign only to customers approved before the deadline. Customers approved after the deadline, rejected, or not included in the response are excluded.

Conditional Execution for Triggered Campaigns

Step 1: Register a Webhook

Register one or more webhooks to receive notifications for triggered Conditional Execution campaigns. All webhooks will receive all notifications, and Optimove will respect the first response received for each customer and campaign action within the defined timeout. This step only needs to be done once for all future triggered conditional campaigns. Refer to the CreateWebhook API call documentation for details. Additional webhook management APIs include GetWebhooks, GetWebhookById, and DeleteWebhook.

Webhook Registration API Call:

{
  "url": "string"
}

Response payload (201 Created):

{
  "url": "https://example.com/webhook",
  "id": "webhook1"
}

Step 2: Optional - Define Tenant Settings

Define the response timeout (default is 5000 milliseconds) and, optionally, a shared HMAC secret string for authorization with Optimove using the UpdateWebhookSettings API call.

Signature Verification

If you choose to configure a secret for your webhook:

Before sending the webhook to your endpoint, Optimove signs the request using the HMAC algorithm and the secret you provided. Validate the signature in the optimove-signature-content header.

Example:

const secret = 'abcdefg';
const hash = crypto.createHmac('sha256', secret)
  .update('I love cupcakes')
  .digest('hex');
console.log(hash);

Tenant Settings API Call Request:

{
  "timeout": 5000,
  "secret": "string"
}

Response payload (200 OK):

{
  "timeout": 5000,
  "secret": "string"
}

Step 3: Request Activation of Triggered Conditional Execution

Contact your Customer Success Manager (CSM) or Customer Success Engineer (CSE) to enable triggered Conditional Execution for your site. Once enabled, you can activate it per campaign action in the Campaign Builder.

Note: The above steps are required only once.

Step 4: Optimove Notifies the Webhook(s) that the User is Eligible for a Campaign

When a user completes the required trigger events and is eligible for a triggered campaign, Optimove sends a notification with full campaign and user details.

Notification Payload:

{
  "timestamp": 1234567890123,
  "conditional_execution_approval_deadline": 1234567890999,
  "request_uid": "string",
  "is_hashed": false,
  "user": {
    "user_id": "string",
    "is_visitor": false,
    "personalization": {
      "attribute_key1": "attribute_value1",
      "attribute_key2": "attribute_value2"
    }
  },
  "occurrence": {
    "date": "YYYY-MM-DD",
    "series_id": "string",
    "occurrence_id": "string",
    "target_group": {
      "id": 123,
      "name": "string"
    },
    "notes": "string",
    "tags": ["string"],
    "communication_type": "triggered",
    "action": {
      "id": 1,
      "name": "string",
      "is_control": false,
      "promotions": [
        {
          "name": "string",
          "code": "string"
        }
      ],
      "channels": [
        {
          "id": 1,
          "name": "string",
          "brand_id": "string",
          "template": {
            "id": 1,
            "name": "string"
          }
        }
      ]
    }
  },
  "trigger_context": {
    "id": 1,
    "name": "string",
    "events": [
      {
        "key": "string",
        "timestamp": 1234567890,
        "parameters": {
          "param_key1": "param_value1",
          "param_key2": "param_value2"
        }
      }
    ]
  }
}

Step 5: Internal Systems Review if the User Should Receive the Campaign

Perform the necessary internal checks or validations.

Step 6: Notify Optimove if the User Should Receive the Campaign

Send approval using the SendWebhookApproval API.

Approval Payload:

{
  "timestamp": 1234567890123,
  "request_uid": "string",
  "approved": true,
  "additional_data": {}
}

Step 7: Optimove Sends the Campaign to the User

If the user is approved before the timeout, Optimove sends the campaign. If delayed execution is configured, the delay begins at approval time.

Note: Triggered Conditional Execution is not supported for web page pop-up campaigns.