searchBatches

Returns a list of Batches that match the search criteria.

searchBatches

Returns a list of Batches that match the search criteria.

Top ↑

Syntax

array searchBatches(
    string api_key,
  [ array search_criteria,
    int limit,
    int offset,
    string sort_by,
    string sort_order ] 
);

Parameters

api_key (string)

The key required to access the API. See Getting Started for more information.

search_criteria (array - optional)

An array of search criteria. See the remarks section below for the list of values which are searchable.
If you do not specify search criteria, all Batches are returned.

limit (int - optional)

Maximum number of items to return.

offset (int - optional)

Number of items to skip before beginning to return results. See Using Search Methods for information about using the offset parameter with the limit parameter to include pagination in your results.

sort_by (string - optional)

The name of the value to sort the results by.

sort_order (string - optional)

The order the results are returned in (either ascending or descending). The default is descending. Valid values are:

  • DESC - Sort from highest to lowest (default).
  • ASC - Sort from lowest to highest.

Return Value

Returns an array containing zero or more associative arrays of Batch details. See the remarks section below for the list of values this method returns.

Examples

Search for all Batches:

$api     = new Api($url, 'YOURAPIKEY');
$batches = $api->invokeMethod('searchBatches');
{
    "id": 1,
    "method": "searchBatches",
    "params": [
        "YOURAPIKEY"
    ]
}
{
    "id": 1,
    "result": [
        {
            "id": "1880001",
            "list_id": "325374",
            "creator_user_id": "50553",
            "creation_time": "1360298491",
            "message_id": "819007",
            "message_type": "email",
            "is_scheduled": "1",
            "is_populated": "0",
            "send_status": "cancelled",
            "send_time": "1360384891",
            "first_sent_time": "0",
            "last_sent_time": "1360298570",
            "send_contact_count": "0",
            "send_current_count": "0",
            "is_test": "0",
            "type": "manual",
            "creator_name": "Api Test Co. PTY LTD"
        },
        {
            "id": "1880003",
            "list_id": "325374",
            "creator_user_id": "50553",
            "creation_time": "1360299462",
            "message_id": "819008",
            "message_type": "email",
            "is_scheduled": "1",
            "is_populated": "0",
            "send_status": "pending",
            "send_time": "1360385862",
            "first_sent_time": "0",
            "last_sent_time": "1360299469",
            "send_contact_count": "0",
            "send_current_count": "0",
            "is_test": "0",
            "type": "manual",
            "creator_name": "Api Test Co. PTY LTD"
        }
    ],
    "error": null
}

Search for Batches scheduled in the future:

$search_criteria = array(
    array('send_time',          'greater_than', time()),
    array('is_test',            'exactly',      0),
    array('is_scheduled',       'exactly',      1),
);

$api     = new Api($url, 'YOURAPIKEY');
$batches = $api->invokeMethod('searchBatches', $search_criteria);
{
    "id": 1,
    "method": "searchBatches",
    "params": [
        "YOURAPIKEY",
        [
            [
                "send_time",
                "greater_than",
                1360301561
            ],
            [
                "is_test",
                "exactly",
                0
            ],
            [
                "is_scheduled",
                "exactly",
                1
            ]
        ]
    ]
}
{
    "id": 1,
    "result": [
        {
            "id": "1880001",
            "list_id": "325374",
            "creator_user_id": "50553",
            "creation_time": "1360298491",
            "message_id": "819007",
            "message_type": "email",
            "is_scheduled": "1",
            "is_populated": "0",
            "send_status": "cancelled",
            "send_time": "1360384891",
            "first_sent_time": "0",
            "last_sent_time": "1360298570",
            "send_contact_count": "0",
            "send_current_count": "0",
            "is_test": "0",
            "type": "manual",
            "creator_name": "Api Test Co. PTY LTD"
        },
        {
            "id": "1880006",
            "list_id": "325374",
            "creator_user_id": "50553",
            "creation_time": "1360301556",
            "message_id": "819007",
            "message_type": "email",
            "is_scheduled": "1",
            "is_populated": "0",
            "send_status": "pending",
            "send_time": "1360387956",
            "first_sent_time": "0",
            "last_sent_time": "1360301558",
            "send_contact_count": "0",
            "send_current_count": "0",
            "is_test": "0",
            "type": "manual",
            "creator_name": "Api Test Co. PTY LTD"
        }
    ],
    "error": null
}

Remarks

The following table shows the values that are returned.

Key Type Searchable Description
id int Yes The Batch ID
list_id int Yes The List ID
message_id int Yes The Message ID
message_type string Yes The Message type. Can be either email or sms
creator_user_id int Yes The ID of the User who created this Batch
creator_name string Yes The name of the User who created this Batch
creation_time int Yes The name of the User who created this Batch
type string Yes The Batch type. Valid values are manual, campaign, autoresponder or quicksend
is_test bool Yes Value indicating if this is a test send
is_scheduled bool Yes Value indicating if the Batch is scheduled
is_populated bool Yes Value indicating if the Batch has been populated and is ready to be sent
send_status string Yes The send status of the Batch. Valid values are initialising, pending, sending, completed, failed, cancelled or paused
send_contact_count int Yes Total number of contacts in this Batch
send_current_count int Yes The number of Contacts that have been sent the Message
send_time int Yes Timestamp of when the Batch is scheduled to be sent
first_sent_time int Yes Timestamp of when the first Message was sent
last_sent_time int Yes Timestamp of when the last Message was sent

Send status

The send_status Field indicates the current status of the Batch in the system's Message sending process. The possible send_status values are:

Active States:

  • initialising - Currently being built by the System's Queue Processor
  • pending - Waiting to be Sent
  • sending - Sending in Progress
  • completed - Completed Successfully

Inactive States:

  • failed Failed
  • cancelled Cancelled by the User
  • paused Temporarily Stopped by the User or System

Reasons Why A Batch Might Fail

  • The send list contains more than 10 invalid Email addresses.
  • The Message to be sent was deleted. Please note, this can also cause previously completed Batches to be marked as failed, as this state is applied retroactively to any previous Batches when Message is deleted.
  • The Batch recipient List was empty at the time of send.

Error Codes

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

Code Error Description
311 Invalid Search Parameter Format search_critera is not valid

See Also

Method References
Popular Pages