BrandMail API - addBatchByContactSearch

Syntax

int addBatchByContactSearch(
    string api_key,
    int message_id,
    array lists,
    array search_criteria,
  [ int send_time,
    bool is_scheduled ] 
);

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.

lists (array)

A List of one or more List IDs for the method to search.

search_criteria (array)

An array of search criteria that selects Contacts to be included in the Batch. You can search on any of the Fields in the List. See searchContacts for more information on the list of values which are searchable.

send_time (int - optional)

Timestamp indicating when to send the message.

is_scheduled (bool - optional)

Value indicating if the Batch is scheduled to be sent on a future date. Valid values are:

true - Batch is scheduled to be sent in the future.
false - Batch is not scheduled to be sent in the future (default).

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

This example searches in Lists 111222, 333444, and 555666 for Contacts who have been modified but not sent a Message within the last 24 hours. It creates a Batch of the Contacts found and specifies that that system should send them Message 1234567. If you look at the JSON Results tab, you can see that the method was successful and returned the Queue ID 1931202.

$message_id  = 1234567;

$lists       = array(111222, 333444, 555666);

// Search: All contacts that haven't been sent anything in the

// last 24 hours but have been modified in the last 24 hours

$search_criteria = array(

    array('last_message_time',  'less_than',    time() - (24*3600)),

    array('last_modified_time', 'greater_than', time() - (24*3600)),

);

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

$queue_id = $api->invokeMethod('addBatchByContactSearch', $message_id, $lists, $search_criteria);

{

    "id": 1,

    "method": "addBatchByContactSearch",

    "params": [

        "YOURAPIKEY",

        1234567,

        [

            111222,

            333444,

            555666

        ],

        [

            [

                "last_message_time",

                "less_than",

                1359611538

            ],

            [

                "last_modified_time",

                "greater_than",

                1359611538

            ]

        ]

    ]

}

{

    "id": 1,

    "result": 1931202,

    "error": null

}

Remarks

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 the Message is scheduled to be sent in the 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	One or more of the List IDs do not exist or do not belong to your Account.
`307`	Could not load message	The Message ID does not exist or does not belong to your Account.
`310`	No Lists Found	The `details` parameter is not a multidimensional array of search criteria.
`332`	Account Owner Address is not Confirmed	The Account owner's email address has not been confirmed.

addBatchByContactSearch