API reference: Marketing automation documents the function signatures, parameters, return values, and error behavior of the Elaine HTTP API.
Function availability depends on the Elaine release and enabled features. Authenticate HTTP requests with an Elaine-issued Bearer JWT.
Function overview
| string|integer | api_getCampaignStatus ( int $campaign_id ) |
| Returns the current status of a campaign $campaign_id. |
| boolean|integer | api_isCampaignRunning ( int $campaign_id ) |
| Checks whether a campaign $campaign_id is currently running. |
| boolean|integer | api_setCampaignStatus ( int $campaign_id , string $status ) |
| Sets the status of a campaign $campaign_id. |
| boolean|integer | api_startCampaignExecution ( int $campaign_id ) |
| Starts a campaign $campaign_id and returns whether the start was successful. |
| boolean|integer | api_stopCampaignExecution ( int $campaign_id ) |
| Stops a campaign $campaign_id and returns whether the stop was successful. |
| integer | api_userCreateOrUpdateStartCampaign ( array $data , int $campaign_id , int $entry_id = null , bool $restart = false , bool $force_subscription = false , string $rollback_type = 'api' , int $rollback_id , int $datasource_id ) |
| This function newly creates a recipient or updates an existing recipient. |
| boolean|integer | api_userStartCampaign ( int $p_id , int $campaign_id , int $entry_id = null , bool $restart = false , bool $force_subscription = false , string $rollback_type = 'api' , int $rollback_id , int $datasource_id ) |
| This function subscribes a recipient profile $p_id to a marketing campaign $campaign_id in the state/entry $entry_id. |
Functions
api_getCampaignStatus
string|integer api_getCampaignStatus ( int $campaign_id )
SINCE 5.12.0 Returns the current status of a campaign $campaign_id. Possible values are:'active': The campaign can be started. Triggered new subscriptions are possible at any time. Statistics running. Events are triggered.'inactive': Campaign cannot start. Triggered new subscriptions are not possible. Statistics running. Events are triggered.'closed': Campaign cannot start. Triggered new subscriptions are not possible. Statistics not running. Events are not triggered.'staging': Campaign can be started. Triggered new subscriptions are not possible. Statistics not running. Events are triggered.
Parameters
| int | $campaign_id | Campaign ID |
Return Value
| string|integer | Status string or error code |
api_isCampaignRunning
boolean|integer api_isCampaignRunning ( int $campaign_id )
SINCE 5.12.0 Checks whether a campaign $campaign_idis currently running.Parameters
| int | $campaign_id | Campaign ID |
Return Value
| boolean|integer | Boolean or error code |
api_setCampaignStatus
boolean|integer api_setCampaignStatus ( int $campaign_id , string $status )
SINCE 5.12.0 Sets the status of a campaign $campaign_id. Possible values for $status are described under api_getCampaignStatus().Parameters
| int | $campaign_id | Campaign ID |
| string | $status | Statusa for campaign |
Return Value
| boolean|integer | Success or error code |
api_startCampaignExecution
boolean|integer api_startCampaignExecution ( int $campaign_id )
SINCE 5.12.0 Starts a campaign $campaign_idand returns whether the start was successful.Parameters
| int | $campaign_id | Campaign ID |
Return Value
| boolean|integer | Success or error code |
api_stopCampaignExecution
boolean|integer api_stopCampaignExecution ( int $campaign_id )
SINCE 5.12.0 Stops a campaign $campaign_idand returns whether the stop was successful.Parameters
| int | $campaign_id | Campaign ID |
Return Value
| boolean|integer | Success or error code |
api_userCreateOrUpdateStartCampaign
integer api_userCreateOrUpdateStartCampaign ( array $data , int $campaign_id , int $entry_id = null , bool $restart = false , bool $force_subscription = false , string $rollback_type = 'api' , int $rollback_id , int $datasource_id )
This function newly creates a recipient or updates an existing recipient. After this process, the behaviour is identical to the function api_userStartCampaign(). The recipient data has to be transferred in an array as the first parameter.
Parameters
| array | $data | data to insert for user, or update for user |
| int | $campaign_id | the identifier of the campaign automation |
| int | $entry_id = null | [optional] entry state id to subscribe in |
| bool | $restart = false | [optional] recipient could restart in the current campaign (if already subscribed, set a new state id) |
| bool | $force_subscription = false | [optional] set true to ignore status of campaign automation and do always subscribe |
| string | $rollback_type = 'api' | [optional] meta data for subscription: type, permitted values are: 'api' (default), 'mail', 'system', 'swyn', 'import', 'user', 'bounce', 'spam', 'form', 'custom', 'campaign' |
| int | $rollback_id | [optional] meta data for subscription: id |
| int | $datasource_id | [optional] datasource identifier |
Return Value
| integer | Profile ID, Success or error code |
api_userStartCampaign
boolean|integer api_userStartCampaign ( int $p_id , int $campaign_id , int $entry_id = null , bool $restart = false , bool $force_subscription = false , string $rollback_type = 'api' , int $rollback_id , int $datasource_id )
This function subscribes a recipient profile $p_id to a marketing campaign $campaign_id in the state/entry $entry_id. Via the parameter $restart you can configure whether the profile should run through the campaign again, even if it has already been a member. If you would like to unsubscribe the profile, independent from the state of the campaign, you can force the unsubscription via $force_subscription. The origin of the profile can be specified via $rollback_type, $rollback_id and data source $datasource_id.
Parameters
| int | $p_id | the identifier of the recipient |
| int | $campaign_id | the identifier of the campaign automation |
| int | $entry_id = null | [optional] entry state id to subscribe in |
| bool | $restart = false | [optional] recipient could restart in the current campaign (if already subscribed, set a new state id) |
| bool | $force_subscription = false | [optional] set true to ignore status of campaign automation and do always subscribe |
| string | $rollback_type = 'api' | [optional] meta data for subscribe: type |
| int | $rollback_id | [optional] meta data for subscribe: id |
| int | $datasource_id | [optional] datasource identifier |
Return Value
| boolean|integer | Success or error code |
Generic event processing
api_processEvent
Processes a configured generic event for use by marketing automations, transactional messages, or both. The recipient data must contain an identifier such as p_id or c_email. Optional metadata can control message parameters and restrict processing to selected campaign IDs.
Parameters
| string | $eventName | Configured event name using letters, numbers, hyphens, or underscores. |
| array | $recipientData | Recipient identifier and supported persistent, event, or temporary data fields. |
| array | $metaData | Optional message, recipient-group, variant, correlation, and campaign-filtering metadata. |
Return value
Returns a negative integer error code on failure. Otherwise, it returns an array containing transactional-message results in tam and marketing-automation results in ma. An empty array means that no configured message or automation consumed the event.