Vision 6

addBatch

Creates a new Batch to send a Message to a set of Contacts.

addBatch

Creates a new Batch to send a Message to a set of Contacts.

Top ↑

Syntax

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

API Key Access Level required: Standard access

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:

PHP

$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);

JSON Request

{
    "id": 1,
    "method": "addBatch",
    "params": [
        "YOURAPIKEY",
        1111222,
        [
            {
                "list_id": 1234567,
                "type": "contacts",
                "contact_list": [
                    2
                ],
                "time": "now"
            }
        ]
    ]
}

JSON Response

{
    "id": 1,
    "result": 1931200,
    "error": null
}

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

PHP

$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);

JSON Request

{
    "id": 1,
    "method": "addBatch",
    "params": [
        "YOURAPIKEY",
        1111222,
        [
            {
                "list_id": 1234567,
                "type": "unsent",
                "time": "now"
            }
        ],
        1359008471,
        true
    ]
}

JSON Response

{
    "id": 1,
    "result": 1931201,
    "error": null
}

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

PHP

$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);

JSON Request

{
    "id": 1,
    "method": "addBatch",
    "params": [
        "YOURAPIKEY",
        1111222,
        [
            {
                "list_id": 1234567,
                "type": "list",
                "time": "send"
            }
        ],
        1359091271,
        true
    ]
}

JSON Response

{
    "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.

See Also