ClickAutomation v1.2

Powerful automation rules which are triggered when a subscriber clicks a link in a message.

What can I do with clickAutomation?

A clickAutomation rule describes the event in which a Marketing Automation action is triggered by an email click:

  • The action will be automatically triggered when a subscriber clicks a specific link_id or any link in the message_id provided.
  • You can fetch a link_id from a given message via the emailMessageLink endpoint.
  • Actions include subscriptions, contact, notifications and much more.
  • You can specify when the action will execute. This can be as soon as possible, before/after a fixed period or at a specific time.

Actions may be queued when triggered by the event. Queued actions will complete when a rule is paused, but are aborted when a rule is deleted.

GET /clickAutomation or /clickAutomation/:id

AttributeTypeFilterSortDescription
id
intYesYesUnique ID of the Marketing Automation rule.
actiononweekend
boolYesNoWhether the rule will trigger at weekends.
actiontarget
stringNoNoDatum used by actiontype, e.g. list ID if actiontype is "addtolist".
actionhour
string/nullNoYesA specific time for the action to occur, format "HH:00:00".
actiontimediff
intNoYesOffset, in seconds, between a matching event and an consequent action.
actiontype
enumNoNoThe kind of action to be taken upon a successful match: "addtolist", "email_autoresponder", "notify", "sms_autoresponder".
link_id
int/nullNoNoIf non-null, the unique ID of the link used in the match comparison.
message_id
int/nullNoNoIf non-null, the unique ID of the message for which all containing links will be used in the match comparison.
name
stringYesYesRule name.
paused
boolYesNoWhether the rule is paused.
summary
string/nullNoNoEnglish-language description of the rule.
user_id
intYesNoUnique ID of the user who created this rule.
cdate
decimalNoYesCreation timestamp.
mdate
decimalNoNo

Last modification timestamp.

Rules will be paused if an associated list (or its containing folder) is deleted.

HEAD /clickAutomation or /clickAutomation/:id

AttributeTypePresenceDescription
id
intOptionalUnique ID of the Marketing Automation rule.
actiononweekend
boolOptionalWhether the rule will trigger at weekends.
name
stringOptionalRule name.
paused
boolOptionalWhether the rule is paused.
user_id
intOptionalUnique ID of the user who created this rule.

POST /clickAutomation

AttributeTypePresenceDescription
actiononweekend
boolOptional*Whether the rule will trigger at weekends.
actiontarget
stringRequiredDatum used by actiontype, e.g. list ID if actiontype is "addtolist".
actionhour
string/nullOptional**A specific time for the action to occur, format "HH:00:00".
actiontimediff
intOptional**Offset, in seconds, between a matching event and an consequent action.
actiontype
enumRequiredThe kind of action to be taken upon a successful match: "addtolist", "email_autoresponder", "notify", "sms_autoresponder".
link_id
int/nullRequired***If non-null, the unique ID of the link used in the match comparison.
message_id
int/nullRequired***If non-null, the unique ID of the message for which all containing links will be used in the match comparison.
name
stringRequiredRule name.
paused
boolOptionalWhether the rule is paused.
summary
string/nullRequiredEnglish-language description of the rule.

* Required if one of actionhour or actiontimediff are set (with actiontimediff not being set to 0). If these are not set, actiononweekend will automatically default to true and cannot be explicitly set to false.

** If actiontimediff is set to 0 and actionhour is not set, when the rule is triggered, the action will be taken as soon as possible (only for certain actiontypes).

*** Only one of link_id or message_id can be set.

If actiontype is set to "addtolist", actiontimediff must be non-zero. Otherwise, the actiontimediff must be 0 or greater. If actionhour is set, actiontimediff must be 0 or divisible by 1440.

The actionhour should be set to a local time for the company's timezone.

actiononweekend can only be set to "false" if one or both of actionhour or actiontimediff are set. If neither are set, actiononweekend will implicitly be set to "true". In this scenario, it will not be permitted to set actiononweekend to "false" as the rule will be configured to run 'as soon as possible'.

Users will only be permitted to set the message_id or actiontarget (if actiontype is "email_autoresponder" or "sms_autoresponder") to a message they have access to. Users will only be permitted to set link_id to a link ID for a message they have access to.

If an email message is associated to a clickAutomation rule via a POST/PUT, either as an actiontarget for an "email_autoresponder" actiontype, or as a message_id, or by association to a link_id, that message will become non-editable.

PUT /clickAutomation or /clickAutomation/:id

AttributeTypePresenceDescription
id
intRequiredUnique ID of the Marketing Automation rule.
actiononweekend
boolOptional*Whether the rule will trigger at weekends.
actiontarget
stringOptional***Datum used by actiontype, e.g. list ID if actiontype is "addtolist".
actionhour
string/nullOptional**A specific time for the action to occur, format "HH:00:00".
actiontimediff
intOptional**Offset, in seconds, between a matching event and an consequent action.
actiontype
enumOptional***The kind of action to be taken upon a successful match: "addtolist", "email_autoresponder", "notify", "sms_autoresponder".
link_id
int/nullOptionalIf non-null, the unique ID of the link used in the match comparison.
message_id
int/nullOptionalIf non-null, the unique ID of the message for which all containing links will be used in the match comparison.
name
stringOptionalRule name.
paused
boolOptionalWhether the rule is paused.
summary
string/nullOptionalEnglish-language description of the rule.

* Required if one of actionhour or actiontimediff are set (with actiontimediff not being set to 0). If these are not set, actiononweekend will automatically default to true and cannot be explicitly set to false.

** If actiontimediff is set to 0 and actionhour is not set, when the rule is triggered, the action will be taken as soon as possible (only for certain actiontypes).

*** Not all actiontypes and corresponding actiontargets can be modified once set. See tip.

If the actiontype is "email_autoresponder" or "sms_autoresponder", actiontype and actiontarget cannot be modified via a PUT request.

If enabled for the company, folder restrictions will apply to this endpoint. Users will only be able to create list-related rules for lists in folders that they have access to.

If an email message is associated to a clickAutomation rule via a POST/PUT, either as an actiontarget for an "email_autoresponder" actiontype, or as a message_id, or by association to a link_id, that message will become non-editable.

DELETE /clickAutomation or /clickAutomation/:id

AttributeTypePresenceDescription
id
intRequiredUnique ID of the Marketing Automation rule.

Deletion of rules is restricted by user. Only rules created by the user can be deleted by that user, unless they are the admin user who can delete any rules.

Error codes

CodeSubcodeMessageDescription
409
12
Automation Rule $id cannot be unpaused: Dependent $resource resource $resource_id no longer existsIf an automation rule dependent resource (usually actiontarget, but for smsAutomation it could be list_id, email_list_id or message_id) is deleted, and the associated rule is paused, this error will be given if the user then tries to unpause the rule without changing the dependent resource.

Please see error handling for more information on error codes.

Examples

JSON response

{
    "id":              12345,
    "actiononweekend": true,
    "actiontarget":    154807,
    "actionhour":      null,
    "actiontimediff":  2040,
    "actiontype":      "sms_autoresponder",
    "link_id":         43214,
    "message_id":      null,
    "name":            "Summer Competition Confirmation Trigger",
    "paused":          false,
    "summary":         "When a subscriber clicks a link in the campaign 'Summer Competition' then send the subscriber the SMS campaign 'Other Competitions' approximately 1.5 days later.",
    "user_id":         23456,
    "cdate":           1234966741,
    "mdate":           1234966741
}