Creates a Batch of Contacts that match search criteria.


Creates a Batch of Contacts that match search criteria.

Top ↑


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


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.


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": [
    "id": 1,
    "result": 1931202,
    "error": null


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.

See Also