REST Email Marketing API Documentation

Recipients — Search

Search for recipients based on demographics or topic subscriptions. Combine multiple piece of criteria to filter the results to get just those recipients you want. All demographics are returned.

HTTP VERB

Post

URL

/API/Rest/Recipients/Search

ARGUMENTS

topicName (Optional) Only return recipients marked as subscribed to this topic
searchDemographics (Optional) An array of demographic fields to use for searching
searchCriterias (Optional) An array of criteria for the searching of the demographic fields
searchValues (Optional) An array of values to match against the search fields

Allowed values for the comparison operator:
EqualTo
NotEqualTo
GreaterThan
LessThan
Between
IsTrue
IsFalse
Contains
StartsWith
EndsWith
IsNull
IsNotNull

Required permission

ViewMember

ERRORS

No Permission
The search criteria fields must have an equal number of entries in each array
Invalid topic name
Cannot find demographic
Unknown search criteria
Invalid demographic operator for column
Cannot convert column '' to money type
Cannot convert column '' to decimal type
Cannot convert column '' to boolean type
Cannot convert column '' to datetime type
Cannot convert column '' to char type
Cannot convert column '' to int type
Row not found
Too many API calls
Database error
Unknown error

RETURNS

Recipients in the large data format with the addition of an array providing the column names that are part of the data set, since these are user-defined.


{"downloadGuid":"2b0df9a2-bf30-4905-b6ba-4f8a782209a4","totalRows":4,
"columns":["Email Address", "Name", "Age", "LastName", "Title", "Language", "Salutation", "Company", "Territory_Region", "Mailing_Country", "FirstName"],
"userData":[["joe.example@example.com","Joe Example","33","Example","President","English","Mr.","Example.com","USA West","United States","Joe"],
["sam.example@example.com","Sam Example","45","Example","vp","English","Mr.","Acme","USA East","United States","Sam"],
["Linda@example.com","Linda Example","43","Example","VP Marketing","English","Ms.","IBM","USA East","United States","Linda"]]}

EXAMPLE

Query for recipients with an email address that starts with 'Joe'.

 
string message = "{'accountName':'acme','login':'ApiUser', 'password':'sdve4t3gfd', 'searchDemographics':['EmailAddress'],'searchCriterias':['StartsWith'],'searchValues':['Joe']}";
string url = "http://example.com/api/rest/Recipients/Search";
								
try
{
	System.Net.HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
	request.Method = "POST";
	request.ContentType = "application/json";
	request.ContentLength = message.Length;
	using (Stream webStream = request.GetRequestStream())
		using (StreamWriter requestWriter = new StreamWriter(webStream, System.Text.Encoding.ASCII))
			requestWriter.Write(message);
								
	System.Net.WebResponse webResponse = request.GetResponse();
	using (Stream webStream = webResponse.GetResponseStream())
		using (StreamReader responseReader = new StreamReader(webStream))
			Console.Out.WriteLine(responseReader.ReadToEnd());
}
catch (Exception e)
{
	System.Diagnostics.Debug.Fail(e.Message);
}
							
# encoding: utf-8
require 'rest-client'
require 'json'
							
url = 'http://www.acme.com/api/rest/Recipients/Search'
args = {'accountName'=>'acme', 'login'=>'ApiUser', 'password'=>'sdf3w4tw', 'searchDemographics':['EmailAddress'],'searchCriterias':['StartsWith'],'searchValues':['Joe']}
response = RestClient.post(url, args.to_json, :content_type => "application/json;charset=utf-8")
puts response	
						
import requests
url = "http://www.example.com/api/rest/Recipients/Search";
args = {'accountName':'acme','login':'ApiUser','password':'f334f3fg3','searchDemographics':['EmailAddress'],'searchCriterias':['StartsWith'],'searchValues':['Joe']}
headers = {'Content-Type': 'application/json'}
resp = requests.post(url, json=args, headers=headers)
if resp.status_code == 200:
	print resp.text

curl -X POST -H "Content-Type: application/json" -d "{'accountName':'acme','login':'ApiUser','password':'f334f3fg3', 'searchDemographics':['EmailAddress'],'searchCriterias':['StartsWith'],'searchValues':['Joe']}" http://www.example.com/API/Rest/Recipients/Search

Share this: