BrandMail API - addBatch

Syntax

int addBatch(
    string api_key,
    int message_id,
    array contact_populations,
  [ int send_time,
    bool is_test ] 
);

Parameters

api_key (string): The key required to access the API. See Getting Started for more information.
message_id (int): The ID of the Message to send.
contact_populations (array): An array containing one or more associative arrays of Contact Populations. See the remarks section below.
send_time (int - optional): If send time is scheduled, time that system should send Batch.
is_test (bool - optional): Boolean value indicating if this is a test send. Setting this to true adds "[test]" to the subject. The addition of the word "[test]" is the only difference from an actual send.

Return Value

Returns the Batch's Queue ID on success. Periodically poll getBatchIdByQueueId to retrieve the Batch ID once the Batch has been created.

Examples

Send the Message to a single Contact:

$list_id     = 1234567;

$message_id  = 1111222;

// Send a Message to a single Contact in a List

$batch_details = array(

    array(

        'list_id'      => $list_id,

        'type'         => 'contacts',

        'contact_list' => array(2),

        'time'         => 'now'

    )

);

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

$queue_id = $api->invokeMethod('addBatch', $message_id, $batch_details);

{

    "id": 1,

    "method": "addBatch",

    "params": [

        "YOURAPIKEY",

        1111222,

        [

            {

                "list_id": 1234567,

                "type": "contacts",

                "contact_list": [

                    2

                ],

                "time": "now"

            }

        ]

    ]

}

{

    "id": 1,

    "result": 1931200,

    "error": null

}

Schedule a send for 1 hour in the future to Contacts who haven't received this Message before:

$list_id     = 1234567;

$message_id  = 1111222;

// Schedule a send to occur in approximately an hour to anyone who hasn't been sent a particular message

$batch_details = array(

    array(

        'list_id' => $list_id,

        'type'    => 'unsent',

        'time'    => 'now'

    )

);

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

$queue_id = $api->invokeMethod('addBatch', $message_id, $batch_details, time() + 3600, true);

{

    "id": 1,

    "method": "addBatch",

    "params": [

        "YOURAPIKEY",

        1111222,

        [

            {

                "list_id": 1234567,

                "type": "unsent",

                "time": "now"

            }

        ],

        1359008471,

        true

    ]

}

{

    "id": 1,

    "result": 1931201,

    "error": null

}

Schedule a send for tomorrow to all Contacts in the List:

$list_id     = 1234567;

$message_id  = 1111222;

// Schedule a send for tomorrow to everyone in the List, but only apply details at time of send

$batch_details = array(

    array(

        'list_id' => $list_id,

        'type'    => 'list',

        'time'    => 'send'

    )

);

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

$queue_id = $api->invokeMethod('addBatch', $message_id, $batch_details, time() + (24*3600), true);

{

    "id": 1,

    "method": "addBatch",

    "params": [

        "YOURAPIKEY",

        1111222,

        [

            {

                "list_id": 1234567,

                "type": "list",

                "time": "send"

            }

        ],

        1359091271,

        true

    ]

}

{

    "id": 1,

    "result": 1931202,

    "error": null

}

Remarks

The following table shows the structure of each contact_populations array.

Key	Type	Description
`list_id`	string	The List ID of the Contacts who will be sent the Message.
`type`	string	Either `list` to send to all contacts in the List, `unsent` to only send to Contacts who have not been sent the Message, or `contacts` to specify which Contacts to send to.
`contact_list`	array	An array containing the IDs of the Contacts to send to if the type has been set to `contacts`.
`time`	string	Either `now` or `send`. Dictates when the send processor populates the List of Contacts who will receive the Message, either immediately or at time of send.

By default, the system removes all Contacts from the Batch that have a duplicate address. This behaviour can be modified using the allow_send_to_duplicates List value (see addList). Duplicate Contacts are identified and removed based on the ascending order of List ID.

If addBatch is used for sending to a single Contact then an existing queue or Batch may be used to perform the send.

If you set the send_time parameter in future, a Notification Email is sent to the List owners when the Batch is sent.

Error Codes

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

Code	Error	Description
`303`	unable to load List	The List IDs you supply do not exist or do not belong to your Account.
`307`	unable to load Message	The Message ID you supply does not exist or does not belong to your Account.
`310`	no Lists found	One or more of the `details` parameters are invalid.
`310`	no List ID or type specified	The `contact_populations` array has not been correctly constructed.
`310`	invalid batch population type	The `contact_populations` array has not been constructed.
`314`	no Contact List specified for batch population	The `type` parameter of the `contact_populations` array has a value other than `unsent`, `list` or `contacts`.
`332`	Account owner address is not confirmed	The Account owner's Email address was not confirmed prior to using the API.

addBatch