REST Email Marketing API Documentation

Example 1

In this example we show the code to send an email to multiple people. We'll start by preparing the recipients — first by creating some demographics to hold information, and then by importing the recipients. Next, we'll create the mailing, assign the audience, and queue the mailing to be distributed.

Once a demographic has been created it doesn't need to be re-created or maintained, so this example isn't that useful. The developer should know whether the demographic exists or not. However, testing for the demographic and creating it if it doesn't exist is shown for completeness.

There is some limited error checking in this code, but for a production system more should be done.

In our simple example mailing, we will dynamically merge the two demographic columns we defined to build an email specific to the recipient. The mail merge tag DbColumn is defined in this documentation.

 
private class DemographicsDataOutput
{
	public string ColumnName;

	public string DataType;

	public bool DisplayInSearchResults;

	public bool ExportWithReports;
}

private class RecipientAddManyResult
{
	public string emailAddress;

	public int recipientId;

	public string importMessage;
}

private static void RestExample1()
{
	try
	{
		string url = "http://www.example.com/api/rest/Demographics?accountName=acme&login=ApiUser";

		System.Net.HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
		request.Headers.Add("Password", "cujd72hf673jhs8g734hf");
		string results;
		using (System.Net.WebResponse response = request.GetResponse())
			using (Stream responseStream = response.GetResponseStream())
				using (StreamReader reader = new StreamReader(responseStream, Encoding.UTF8))
					results = reader.ReadToEnd();

		System.Web.Script.Serialization.JavaScriptSerializer jss = new JavaScriptSerializer();
		System.Collections.Generic.List<DemographicsDataOutput> ddoArray = jss.Deserialize<List<DemographicsDataOutput>>(results);

		bool foundName = false;
		bool foundEmail = false;

		foreach (DemographicsDataOutput row in ddoArray)
		{
			if (row.ColumnName == "SalespersonName")
				foundName = true;
			else if (row.ColumnName == "SalespersonEmail")
				foundEmail = true;
		}

		string data;

		if (foundName == false)
		{
			url = "http://www.example.com/api/rest/Demographics";
			request = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(url);

				data = "{ 'accountName':'acme','login':'ApiUser','password':'cujd72hf673jhs8g734hf','columnName':'SalespersonName', 'dataType':'String50', 'displayInSearchResults':False, 'exportWithReports':True}";

			request.Method = "POST";
			request.ContentType = "application/json";
			request.ContentLength = data.Length;
			using (Stream webStream = request.GetRequestStream())
				using (StreamWriter requestWriter = new StreamWriter(webStream, Encoding.ASCII))
					requestWriter.Write(data);

			using (System.Net.WebResponse webResponse = request.GetResponse())
				using (Stream webStream = webResponse.GetResponseStream())
					using (StreamReader responseReader = new StreamReader(webStream))
						results = responseReader.ReadToEnd();

			if (results == "Success")
				System.Console.WriteLine("Created demographic SalespersonName");
			else
				System.Console.WriteLine(results);
		}
		else
			System.Console.WriteLine("Demographic SalespersonName already exists.");

		if (foundEmail == false)
		{
			url = "http://www.example.com/api/rest/Demographics";
			request = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(url);

			data = "{ 'accountName':'acme','login':'ApiUser','password':'cujd72hf673jhs8g734hf','columnName':'SalespersonEmail', 'dataType':'String100', 'displayInSearchResults':False, 'exportWithReports':True}";
			request.Method = "POST";
			request.ContentType = "application/json";
			request.ContentLength = data.Length;
			using (Stream webStream = request.GetRequestStream())
				using (StreamWriter requestWriter = new StreamWriter(webStream, Encoding.ASCII))
					requestWriter.Write(data);

			using (System.Net.WebResponse webResponse = request.GetResponse())
				using (Stream webStream = webResponse.GetResponseStream())
					using (StreamReader responseReader = new StreamReader(webStream))
						results = responseReader.ReadToEnd();

			if (results == "Success")
				System.Console.WriteLine("Created demographic SalespersonEmail");
			else
				System.Console.WriteLine(results);
		}
		else
			System.Console.WriteLine("Demographic SalespersonEmail already exists.");

		url = "http://www.example.com/api/rest/Recipients/AddMany";
		request = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(url);
		request.Method = "POST";
		request.ContentType = "application/json";
		data = "{ 'accountName':'acme','login':'ApiUser','password':'cujd72hf673jhs8g734hf', 'importType':'AddAndUpdate', 'culture':'en-US', 'demographics':[['EmailAddress', 'Name', 'SalespersonName', 'SalespersonEmail'],";
		data += "['bob@aol.com','Bob Smith', 'Joe Jones', 'joe@example.com'],";
		data += "['fred.smith@aol.com','Fred Smith', 'Ralph Karns', 'r.karns@example.com']]}";

		request.ContentLength = data.Length;
		using (Stream webStream = request.GetRequestStream())
			using (StreamWriter requestWriter = new StreamWriter(webStream, Encoding.ASCII))
				requestWriter.Write(data);

		using (System.Net.WebResponse webResponse = request.GetResponse())
			using (Stream webStream = webResponse.GetResponseStream())
				using (StreamReader responseReader = new StreamReader(webStream))
					results = responseReader.ReadToEnd();

		if (results[0] == '[')
		{
			System.Collections.Generic.List<RecipientAddManyResult> amr = jss.Deserialize<List<RecipientAddManyResult>>(results);
			foreach (RecipientAddManyResult row in amr)
				System.Console.WriteLine(row.emailAddress + " " + row.importMessage);
		}
		else
		{
			System.Console.WriteLine("Error on AddMany!: " + results);
			return;
		}

		//try to delete the mailing, so this example can be run mulitple times. Once the mailing has been sent it cannot be deleted.

		url = "http://www.example.com/api/rest/Mailings/Remove?accountName=acme&login=ApiUser&mailingTitle=CES%202019b";
		request = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(url);
		request.Headers.Add("Password", "cujd72hf673jhs8g734hf");
		request.Method = "Delete";
		request.ContentLength = 0;
		using (System.Net.WebResponse response = request.GetResponse())
			using (System.IO.Stream responseStream = response.GetResponseStream())
				using (System.IO.StreamReader reader = new StreamReader(responseStream, Encoding.UTF8))
					results = reader.ReadToEnd();

		if (results.Length > 6 && results == "Success")
			System.Console.WriteLine("Mailing deleted successfully");
		else
			System.Console.WriteLine("Error on mailing delete!: " + results);

		url = "http://www.example.com/api/rest/Mailings/Create";
		request = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(url);
		request.Method = "POST";
		data = "{'accountName':'acme','login':'ApiUser','password':'cujd72hf673jhs8g734hf', 'mailingTitle':'CES 2019b',";
		data += "'htmlBody':'[-NameEmail-]:<br/><br/>Nice to meet your at the CES show. Please look for contact from your regional salesperson, [-DbColumn SalespersonName-]. If you want to reach out immediately, use email address: [-DbColumn SalespersonEmail-].<br/><br/>Cheers<br/>Joe Smith',";
		data += "'charsetId':1252, 'subject':'Our meeting at CES','bodyLanguageId':1033, 'trackAllLinks':true,";
		data += "'unsubscribeTopic':'Apology'}";
		request.Method = "POST";
		request.ContentType = "application/json";
		request.ContentLength = data.Length;
		using (Stream webStream = request.GetRequestStream())
			using (StreamWriter requestWriter = new StreamWriter(webStream, Encoding.ASCII))
				requestWriter.Write(data);

		using (System.Net.WebResponse webResponse = request.GetResponse())
			using (Stream webStream = webResponse.GetResponseStream())
				using (StreamReader responseReader = new StreamReader(webStream))
					results = responseReader.ReadToEnd();

		if (results.Length > 6 && results.StartsWith("Success"))
			System.Console.WriteLine("Mailing created successfully.");
		else
		{
			System.Console.WriteLine("Error on mailing create!: " + results);
			return;
		}

		url = "http://www.example.com/api/rest/Mailings/Audience";
		request = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(url);
		data = "{ 'accountName':'acme','login':'ApiUser','password':'cujd72hf673jhs8g734hf', 'mailingTitle':'CES 2019b', 'replaceExisting':true,'recipients':['bob@aol.com', 'fred.smith@aol.com']}";
		request.Method = "POST";
		request.ContentType = "application/json";
		request.ContentLength = data.Length;
		using (Stream webStream = request.GetRequestStream())
			using (StreamWriter requestWriter = new StreamWriter(webStream, Encoding.ASCII))
				requestWriter.Write(data);

		using (System.Net.WebResponse webResponse = request.GetResponse())
			using (Stream webStream = webResponse.GetResponseStream())
				using (StreamReader responseReader = new StreamReader(webStream))
					results = responseReader.ReadToEnd();

		if (results[0] == '{')
			System.Console.WriteLine("Mailing audience assigned.");
		else
		{
			System.Console.WriteLine("Error on mailing audience!: " + results);
			return;
		}

		url = "http://www.example.com/api/rest/Mailings/Queue?accountName=acme&login=ApiUser&mailingTitle=CES%202019b";
		request = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(url);
		request.Headers.Add("Password", "cujd72hf673jhs8g734hf");
		request.Method = "PUT";
		request.ContentLength = 0;
		using (System.Net.WebResponse response = request.GetResponse())
			using (System.IO.Stream responseStream = response.GetResponseStream())
				using (System.IO.StreamReader reader = new StreamReader(responseStream, Encoding.UTF8))
					results = reader.ReadToEnd();

		if (results[0] == '{')
		{
			System.Console.WriteLine("Mailing queued successfully. Here are the stats:");
			System.Console.WriteLine(results);
		}
		else
			System.Console.WriteLine("Error on mailing queue!: " + results);
	}
	catch (System.Exception e)
	{
		System.Diagnostics.Debug.Fail(e.Message);
	}
}

# encoding: utf-8
require 'rest-client'
require 'json'

url = "http://www.example.com/api/rest/Demographics/?accountName=acme&login=ApiUser"
response = RestClient.get url, {:Password => "dfhed673hf73eghf87u"}
if response.code != 200
    puts "Get demographics failed"
    puts response
    return
else
    data = JSON.parse(response.body)
end	

foundName = false
foundEmail = false

for row in data
    if row['ColumnName'] == "SalespersonName"
        foundName = true
    end
    if row['ColumnName'] == "SalespersonEmail"
        foundEmail = true
    end
end

if foundName == false
    url = 'http://www.example.com/api/rest/Demographics'
    data = {"accountName":"acme","login":"ApiUser","password":"dfhed673hf73eghf87u",'columnName':'SalespersonName', 'dataType':'String50', 'displayInSearchResults':false, 'exportWithReports':true}
    response = RestClient.post url, data.to_json, {"Content-Type": "application/json"}
    if response.code != 200
        puts "Add SalespersonName demographic failed"
        puts response.code
        return
    elsif response.body == "Success"
        puts "Created demographic SalespersonName"
    elsif
        puts response.body
        return
    end
else
    puts "Demographic SalespersonName already exists."
end

if foundEmail == false
    url = 'http://www.example.com/api/rest/Demographics'
    data = {"accountName":"acme","login":"ApiUser","password":"dfhed673hf73eghf87u",'columnName':'SalespersonEmail', 'dataType':'String100', 'displayInSearchResults':false, 'exportWithReports':true}
    response = RestClient.post url, data.to_json, {"Content-Type": "application/json"}
    if response.code != 200
        puts "Create demographic SalespersonEmail failed!"
        puts response.code
        return
    elsif response.body == "Success"
        puts "Created demographic SalespersonEmail"
    else
        puts response.body
        return
    end
else
    puts "Demographic SalespersonEmail already exists."
end

url = 'http://www.example.com/api/rest/Recipients/AddMany'
data = {"accountName":"acme","login":"ApiUser","password":"dfhed673hf73eghf87u","importType":"AddAndUpdate","culture":"en-US", "demographics":[["EmailAddress", "Name", "SalespersonName", "SalespersonEmail"],["bob@aol.com","Bob Smith", "Joe Jones", "joe@example.com"], ["fred.smith@aol.com","Fred Smith", "Ralph Karns", "r.karns@example.com"]]}
response = RestClient.post url, data.to_json, {"Content-Type": "application/json"}
if response.code != 200
    puts "AddMany failed"
    puts response.body
    return
elsif response.body[0] == "["
    results = JSON.parse(response.body)
    for row in results
        puts row['emailAddress'] + " " + row['importMessage']
    end
else
    puts "Error on AddMany!: " + response.body
end
    
#try to delete the mailing, to assist with testing. Once the mailing has been sent it cannot be deleted.
url = 'http://www.example.com/api/rest/Mailings/Remove?accountName=acme&login=ApiUser&mailingTitle=CES%202019e'
response = RestClient.delete(url, {:Password => "dfhed673hf73eghf87u"})
if response.code != 200
    puts "Mailing delete failed"
    puts response.code
    return
elsif response.body.length > 6 and response.body == "Success"
    puts  "Mailing deleted successfully"
else
    puts "Error on mailing delete!: " + response.body
end

url = 'http://www.example.com/api/rest/Mailings/Create'
data = {"accountName":"acme", "login":"ApiUser", "password":"dfhed673hf73eghf87u", "mailingTitle":"CES 2019e",
        'htmlBody':'[-NameEmail-]:<br/><br/>Nice to meet your at the CES show. Please look for contact from your regional salesperson, [-DbColumn SalespersonName-]. If you want to reach out immediately, use email address: [-DbColumn SalespersonEmail-].<br/><br/>Cheers<br/>Joe Smith',
        'charsetId':'1252', 'subject':'Our meeting at CES','bodyLanguageId':'1033', 'trackAllLinks':true,
        'unsubscribeTopic':'Apology'}
response = RestClient.post url, data.to_json, {"Content-Type": "application/json"}
if response.code != 200
    puts "Mailing create failed"
    puts response.code
    return
elsif response.body.length > 6 and response.body[0..6] == "Success"
    puts "Mailing created successfully."
else
    puts "Error on mailing create!: " + response.body
end

url = 'http://www.example.com/api/rest/Mailings/Audience'
data = {"accountName":"acme","login":"ApiUser","password":"dfhed673hf73eghf87u", "mailingTitle":"CES 2019e", "replaceExisting":true, "recipients":["bob@aol.com", "fred.smith@aol.com"]}
response = RestClient.post url, data.to_json, {"Content-Type": "application/json"}
if response.code != 200
    puts "Assigning the audience failed"
    puts response.code
    return
elsif response.body[0] == "{"
    puts "Mailing audience assigned."
else
    puts "Error on mailing audience!: " + response.body
end
    
url = 'http://www.example.com/api/rest/Mailings/Queue?accountName=acme&login=ApiUser&mailingTitle=CES%202019e&queueTime=2019-07-07'
response = RestClient.put url, "", {:Password =>> "dfhed673hf73eghf87u"}
if response.code != 200
    puts "Mailing queue failed"
    puts response.code
    return
elsif response.body[0] == "{"
    puts "Mailing queued successfully. Here are the stats:"
    puts response.body
else
    puts "Error on mailing queue!: " + response.body
    return
end


import requests
import json

url = "http://www.example.com/api/rest/Demographics/?accountName=acme&login=ApiUser"
headers = {'Password':'hd7367fhjf9sh'}
resp = requests.get(url, headers=headers)
if resp.status_code != 200:
    print "Retrieve of demographics failed!"
    print resp.status_code
else:
    data = json.loads(resp.text)

foundName = False
foundEmail = False

for row in data:
    if row['ColumnName'] == "SalespersonName":
        foundName = True
    if row['ColumnName'] == "SalespersonEmail":
        foundEmail = True

if foundName == False:
    url = 'http://www.example.com/api/rest/Demographics'
    data = {"accountName":"acme","login":"ApiUser","password":"hd7367fhjf9sh",'columnName':'SalespersonName', 'dataType':'String50', 'displayInSearchResults':False, 'exportWithReports':True}
    resp = requests.post(url, json=data, headers={"Content-Type": "application/json"})
    if resp.status_code != 200:
        print "Create of demographic SalespersonName failed!"
        print resp.status_code
    elif resp.text == "Success":
        print ("Created demographic SalespersonName")
    else:
        print resp.text
else:
    print ("Demographic SalespersonName already exists.")

if foundEmail == False:
    url = 'http://www.example.com/api/rest/Demographics'
    data = {"accountName":"acme","login":"ApiUser","password":"hd7367fhjf9sh",'columnName':'SalespersonEmail', 'dataType':'String100', 'displayInSearchResults':False, 'exportWithReports':True}
    resp = requests.post(url, json=data, headers={"Content-Type": "application/json"})
    if resp.status_code != 200:
        print "Create demographic SalespersonEmail failed!"
        print resp.status_code
    elif resp.text == "Success":
        print ("Created demographic SalespersonEmail")
    else:
        print resp.text
else:
    print ("Demographic SalespersonEmail already exists.")

url = 'http://www.example.com/api/rest/Recipients/AddMany'
data = {"accountName":"acme","login":"ApiUser","password":"hd7367fhjf9sh", 'importType':'AddAndUpdate', 'culture':'en-US', 'demographics':[['EmailAddress', 'Name', 'SalespersonName', 'SalespersonEmail'],
                                                                                                                            ['bob@aol.com','Bob Smith', 'Joe Jones', 'joe@example.com'],
                                                                                                                            ['fred.smith@aol.com','Fred Smith', 'Ralph Karns', 'r.karns@example.com']]}
resp = requests.post(url, json=data, headers={"Content-Type": "application/json"})
if resp.status_code != 200:
    print "AddMany failed"
    print resp.status_code
elif resp.text[0] == "[":
    results = json.loads(resp.text)
    for row in results:
        print ( row['emailAddress'] + " " + row['importMessage'])
else:
    print ("Error on AddMany!: " + resp.text)
    
#try to delete the mailing, to assist with testing. Once the mailing has been sent it cannot be deleted.
url = 'http://www.example.com/api/rest/Mailings/Remove?accountName=acme&login=ApiUser&mailingTitle=CES%202019'
resp = requests.delete(url, headers=headers)
if resp.status_code != 200:
    print "Mailing delete failed"
    print resp.status_code
elif len(resp.text) > 6 and resp.text == "Success":
    print ( "Mailing deleted successfully")
else:
    print ("Error on mailing delete!: " + resp.text)

url = 'http://www.example.com/api/rest/Mailings/Create'
data = {"accountName":"acme", "login":"ApiUser", "password":"hd7367fhjf9sh", "mailingTitle":"CES 2019",
        'htmlBody':'[-NameEmail-]:

Nice to meet your at the CES show. Please look for contact from your regional salesperson, [-DbColumn SalespersonName-]. If you want to reach out immediately, use email address: [-DbColumn SalespersonEmail-].

Cheers
Joe Smith',
        'charsetId':'1252', 'subject':'Our meeting at CES','bodyLanguageId':'1033', 'trackAllLinks':True,
        'unsubscribeTopic':'Apology'}
resp = requests.post(url, json=data, headers={"Content-Type": "application/json"})
if resp.status_code != 200:
    print "Mailing create failed"
    print resp.status_code
elif len(resp.text) > 6 and resp.text[0:7] == "Success":
    print ( "Mailing created successfully.")
else:
    print ("Error on mailing create!: " + resp.text)

url = 'http://www.example.com/api/rest/Mailings/Audience'
data = {"accountName":"acme","login":"ApiUser","password":"hd7367fhjf9sh", "mailingTitle":"CES 2019", "replaceExisting":True, "recipients":["bob@aol.com", "fred.smith@aol.com"]}
resp = requests.post(url, json=data, headers={"Content-Type": "application/json"})
if resp.status_code != 200:
    print "Assigning the audience failed"
    print resp.status_code
elif resp.text[0] == "{":
    print ( "Mailing audience assigned.")
else:
    print ("Error on mailing audience!: " + resp.text)
    
url = 'http://www.example.com/api/rest/Mailings/Queue?accountName=acme&login=ApiUser&mailingTitle=CES%202019'
resp = requests.put(url, headers=headers)
if resp.status_code != 200:
    print "Mailing queue failed"
    print resp.status_code
elif resp.text[0] == "{":
    print ( "Mailing queued successfully. Here are the stats:")
    print (resp.text)
else:
    print ("Error on mailing queue!: " + resp.text)

Share this: