searchMessages

Returns the Messages that match the search criteria.

searchMessages

Returns the Messages that match the search criteria.

Top ↑

Syntax

object 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 object containing zero or more objects 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

See Also