BrandMail API - addAutoresponder

Syntax

int addAutoresponder( string api_key, array autoresponder_details );

Parameters

api_key (string): The key required to access the API. See Getting Started for more information.
autoresponder_details (array): An associative array of Autoresponder details. See remarks below for a description of the values in the autoresponder_details array.

Return Value

Returns the ID of the newly added Autoresponder on success.

Examples

$api = new Api($url, 'YOURAPIKEY');

$autoresponder_details = array(

    'list_id' => 1234,

    'message_id' => 654321,

    'event_type' => 'subscribe'

);

$autoresponder = $api->invokeMethod('addAutoresponder', $autoresponder_details);

{

    "id": 1,

    "method": "addAutoresponder",

    "params": [

        "YOURAPIKEY",

        {

            "list_id": 1234,

            "message_id": 654321,

            "event_type": "subscribe",

        }

    ]

}

{

    "id": 1,

    "result": 16728,

    "error": null

}

Remarks

The following table shows the structure of the autoresponder_details array.

Key	Type	Mandatory	Default	Description
`list_id`	int	Yes		The ID of the List containing the Autoresponder.
`message_id`	int	Yes		The ID of the Message to send in response to the event.
`event_type`	string	Yes		The Contact event which triggers the Autoresponder. Valid values are `subscribe`, `unsubscribe`, `update_profile` and `confirm`. See event types below for more information.
`folder_id`	int	No		The List Folder ID containing the Autoresponder.
`timezone`	string	No	API User's timezone	Timezone in tz format (area/location), for example, Australia/Melbourne. See getTimezoneList.
`is_active`	bool	No	true	Value indicating if Autoresponder is active.
`time_criteria_type`	string	No	`immediate`	When to send the Message. Valid values are `immediate`, `delay` and `specific`. See time criteria below for more information.
`time_criteria_timestamp`	int	No		Timestamp indicating when to send the Message if `time_criteria_type` is `specific`.
`time_criteria_offset_period`	string	No		Offset period when `time_criteria_type` is `delay`. Valid values are `minute`, `hour`, `day`, `week`, `month` or `year`. See Specifying a Delay below for more information.
`time_criteria_offset_value`	int	No		The number of units of the period chosen in `time_criteria_offset_period` when `time_criteria_type` is `delay`.
`time_criteria_specific_hour`	int	No		The specific hour of the day to send the Message if `time_criteria_offset_period` is a day or longer.
`time_criteria_specific_minute`	int	No		The specific minute of the hour to send the Message if `time_criteria_offset_period` is a day or longer.

Event types

Autoresponders are triggered when a Contact performs an action in the List.

Valid values for event_type are:

subscribe - A new Contact subscribes to a List.
unsubscribe - An existing Contact unsubscribes from a List.
update_profile - A Contact updates her profile.
confirm - A new Contact confirms his subscription (Email address).

Time Criteria

The time criteria determines when the Message is sent after the Autoresponder is triggered.

Valid values for time_criteria_type are:

immediate - send Message when the event occurs (default).
delay - send Message after the delay specified by time_criteria_offset_period, time_criteria_offset_value, time_criteria_specific_hour and time_criteria_specific_minute.
specific - send Message at the specific time specified in time_criteria_timestamp.

Specifying a Delay

When time_criteria_type is set to delay, the time_criteria_offset_period and time_criteria_offset_value determine how long after the event occurs that the Message is sent (such as 5 hours or 2 days).

Valid values for time_criteria_offset_period are:

minute
hour
day
week
month
year

Set the time_criteria_offset_value to the required number of units of the period chosen in time_criteria_offset_period.

If the time_criteria_offset_period value is a day or longer, then time_criteria_specific_hour and time_criteria_specific_minute specify the time of day when the Message is sent.

Error Codes

This method may return the following error codes in addition to the standard error codes:

Code	Error	Description
`310`	Invalid `timezone`	`timezone` is specified as one that is not recognized.
`310`	Invalid `event_type`	`event_type` is specified as something other than `subscribe,`unsubscribe`,`update_profile`or`confirm`
`310`	Invalid `time_criteria_offset_period`	`time_criteria_type` is set to `delay` and `time_criteria_offset_period` is not set, or is set to something other than `minute`, `hour`, `day`, `week`, `month` or `year`
`310`	`time_criteria_offset_period` equal to or greater than a day requires a valid `time_criteria_specific_hour`	`time_criteria_type` is `delay` and `time_criteria_offset_period` is `day`, `week`, `month` or `year`, and `time_criteria_specific_hour` is not set
`310`	`time_criteria_offset_period` equal to or greater than a day requires a valid `time_criteria_specific_minute`	`time_criteria_type` is `delay` and `time_criteria_offset_period` is `day`, `week`, `month` or `year`, and `time_criteria_specific_minute` is not set
`310`	Invalid `time_criteria_type`	`time_criteria_type` is set to something other than `immediate`, `delay` or `specific`

addAutoresponder