BrandMail API - searchMessages

Syntax

array searchMessages(
    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 Messages 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 Message details. See the remarks section below for the list of values this method returns.

Examples

The following example searches for messages with the Subject Your January 2013 Newsletter is here... or An Important Message from your Bank. The searchMessages() parameters also specify that a maximum of two results should be returned and the results should be sorted by the last_modified_time Field in descending order.

$search_criteria = array(

    array('subject', 'exactly', 'Your January 2013 Newsletter is here...'),

    'OR',

    array('subject', 'exactly', 'An Important Message from your Bank')

);

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

$messages = $api->invokeMethod('searchMessages', $search_criteria, 2, 0, 'last_modified_time', 'DESC');

{

    "id": 3,

    "method": "searchMessages",

    "params": [

        "YOURAPIKEY",

        [

            [

                "subject",

                "exactly",

                "Your January 2013 Newsletter is here..."

            ],

            "OR",

            [

                "subject",

                "exactly",

                "An Important Message from your Bank"

            ]

        ],

        2,

        0,

        "last_modified_time",

        "DESC"

    ]

}

{

    "id": 3,

    "result": [

        {

            "id": "111222",

            "name": "Newsletter 1234: January 2013",

            "from_name": "Example Co.",

            "from_address": "contact_us@example.com",

            "folder_id": "20214",

            "subject": "Your January 2013 Newsletter is here...",

            "type": "email",

            "email_type": "html",

            "size": "64",

            "creator_user_id": "30559",

            "creation_time": "1359698853",

            "last_modified_time": "1359698853",

            "show_unsubscribe_link": true,

            "show_update_profile_link": false,

            "update_profile_list_id": "0",

            "update_profile_webform_id": "0",

            "unsubscribe_list_id": "0",

            "unsubscribe_webform_id": "0",

            "creator_name": "John Smith",

            "authorised_sender": "Example Co.",

            "postal_address": "66 North Street\r\nSouth Side\r\nMiddleton\r\nQLD 4001\r\nAustralia"

        }

    ],

    "error": null

}

Remarks

The following table shows the values that are returned.

Key	Type	Searchable	Description
`id`	int	Yes	ID of the Message.
`name`	string	Yes	The name of the Message.
`type`	string	Yes	The type of Message to be added. Can be either `sms` or `email`.
`email_type`	string	Yes	The Email type for `email` Messages. Valid values are `html`, `plain-html`, `plain` or `raw_html`.
`subject`	string	Yes	The Email subject for `email` Messages.
`size`	int	Yes	The size of the Message in bytes.
`creator_user_id`	int	Yes	The ID of the User who created the Message.
`creator_name`	string	Yes	The name of the User who created the Message.
`creation_time`	int	Yes	Timestamp indicating when the Message was created.
`last_modified_time`	int	Yes	Timestamp indicating when the Message was last modified.
`from_address`	string	Yes	For `email` Messages, an Email address or Email wildcard (variable). For `sms` Messages, a mobile phone number or a phone number wildcard.
`from_name`	string	Yes	The name of the sender for `email` Messages.
`postal_address`	string	Yes	The postal address of the sender for `email` Messages.
`authorised_sender`	string	Yes	The authorised sender of the Email for `email` Messages.
`show_update_profile_link`	bool	Yes	Whether or not to show an update profile link for `email` Messages.
`show_unsubscribe_link`	bool	Yes	Whether or not to show an unsubscribe link for `email` Messages.
`unsubscribe_list_id`	int	Yes	The ID of the List accessed by unsubscribe links for `email` Messages.
`unsubscribe_webform_id`	int	Yes	The ID of the web form accessed by unsubscribe links for `email` Messages.
`update_profile_list_id`	int	Yes	The ID of the List accessed by update profile links for `email` Messages.
`update_profile_webform_id`	int	Yes	The ID of the web form accessed by update profile links for `email` Messages.
`folder_id`	int	Yes	The ID of the Folder that contains the Message.

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_criteria` is not valid

searchMessages