Note: In default asynchronous mode, a successful result does not signify that the message has been delivered to gateway, only that all validations have passed (eg. campaign exists, target set, params in correct format).
Review the campaign model properties page to see the available parameters.
## OpenAPI ````json POST /execute/campaign { "openapi": "3.1.0", "info": { "title": "external-api", "version": "1" }, "servers": [ { "url": "https://api.eu.xtremepush.com/api/external" } ], "paths": { "/execute/campaign": { "post": { "summary": "Execute", "description": "Used to trigger an API-triggered campaign.\n\nNote: In default asynchronous mode, a successful result does not signify that the message has been delivered to gateway, only that all validations have passed (eg. campaign exists, target set, params in correct format).
\n\nReview the campaign model properties page to see the available parameters.
", "operationId": "campaign-execute", "deprecated": "false", "security": [], "requestBody": { "required": "true", "content": { "application/json": { "schema": { "type": "object", "required": [ "apptoken", "id" ], "properties": { "apptoken": { "type": "string", "description": "Your app token" }, "id": { "type": "integer", "format": "int32", "description": "ID of the Campaign within Xtremepush" }, "target_by": { "type": "string", "description": "Specify the type of identifier used in target or target_with_params. Allowed values: `id` (Xtremepush device id - default), `user_id` (client-defined unique user/contact id), `email`, `mobile_number`, `profile_id` (Xtremepush profile ID), `token` (push token), or specific mobile OS identifiers: `device_adid`, `device_idfv`, `device_idfa`." }, "target": { "type": "array", "description": "List of targeted IDs, type defined by `target_by`. Eg. `[\"user1\", \"user2\"]`", "items": { "type": "string" } }, "target_with_params": { "type": "string", "format": "json", "description": "An alternative to `target` parameter if you want to pass the values of any personalisation params you have in your campaign template message. Eg. `{\"user1\": {\"fname\":\"Alex\",\"balance\":\"100 EUR\"}, \"user2\": {\"fname\":\"John\", \"balance\": \"80 EUR\"}}`" }, "target_existing_only": { "type": "string", "description": "Optional. Set to 0 to create a new user profile if the profile didn't exist before." }, "params": { "type": "string", "format": "json", "description": "Personalisation params used when targeting a single user or all messages are to be modified with the same params. Eg. `{\"first_name\":\"Sam\",\"balance\":\"500\"}`. Where params are defined they will be applied to all the targeted profiles; any overrides or additional params defined in target_with_params will be merged in or override the default set in params." }, "time": { "type": "string", "description": "Optional to specify when to execute the campaign. It will be executed immediately if this param is omitted. You can use both date string and unix timestamp as a value." }, "async": { "type": "string", "description": "Optional. If set to 0 your request will be processed completely before API response is returned. In this way you enable an extra level of error reporting being able to receive errors like: \"Recipient not found\", \"Message is suppressed due to insufficient personalization params\". The limitation of non-async mode is that you're only allowed to target a single profile/device. In case you need an extra level of reporting for batch sends you should use a separate query to fetch batch send status." } } }, "examples": { "Execute with personalisation params": { "value": { "apptoken": "YOUR_APPTOKEN", "id": "CAMPAIGN_ID", "target_by": "user_id", "target_with_params": { "user1": { "first_name": "Alex", "balance": "100 EUR" }, "user2": { "first_name": "John", "balance": "80 EUR" } } }, "summary": "Executing a campaign, targeting a single user by external ID and setting a number of variables in the campaign text" }, "Execute at a specific time": { "value": { "apptoken": "YOUR_APPTOKEN", "id": "CAMPAIGN_ID", "target_by": "user_id", "target": [ "12345" ], "time": "2024-12-01 10:00:00" }, "summary": "Executing a campaign at a specific time and including external_message_id in the request, which is a customer-defined reference for the transaction" }, "Create or update profile on execute": { "value": { "apptoken": "YOUR_APPTOKEN", "id": "CAMPAIGN_ID", "target_by": "user_id", "target": [ "NEW_USER_ID" ], "target_existing_only": "0" }, "summary": "Setting the optional param target_existing_only to 0 allows creating a new user profile and update system attributes if they are passed within target_with_params in the request" }, "Execute with payload": { "value": { "apptoken": "YOUR_APPTOKEN", "id": "CAMPAIGN_ID", "target_by": "user_id", "target": [ "12345" ], "params": { "first_name": "Sam", "balance": "500" } }, "summary": "Executing a campaign with a payload deeplink to be used when the notification is opened" }, "Execute with retry and require interaction": { "value": { "apptoken": "YOURAPPTOKEN", "id": "CAMPAIGNID", "target_by": "user_id", "target": [ "12345" ], "messages": { "3": { "push_require_interaction": "true" } }, "retry_for": "2", "retry_for_period": "weeks" }, "summary": "Executing a campaign that enables the web push require interaction option, and has a retry period of 2 weeks" } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": "true", "default": "true" }, "code": { "type": "integer", "example": "200", "default": "0" }, "message": { "type": "string", "example": "Campaign is successfully executed" } } }, "examples": { "Result": { "value": { "success": "true", "code": "200", "message": "Campaign is successfully executed" } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": "false", "default": "true" }, "code": { "type": "integer", "example": "400", "default": "0" }, "errors": { "type": "object", "properties": { "execute": { "type": "array", "items": { "type": "string", "example": "Web Push: one or multiple messages were suppressed due to insufficient personalization params" } } } } } }, "examples": { "Result": { "value": { "success": "false", "code": "400", "errors": { "execute": [ "Web Push: one or multiple messages were suppressed due to insufficient personalization params" ] } } } } } } } }, "tags": [ "Campaign Methods" ] } } } } ````