Problem
How do I list all outMail services under a specified client using the Partner API?
Listing all outMail services using the RESTful Partner API?
Solution
The following example of code shows you how to list all outMail services under one of the partners clients.
Notes
It is assumed that you already have the following.
- Client ID - You need the client id (which could also be the partner id if your listing services under your own account). Client ID can be found by using the /clients end point. See the examples on clients-list and clients-search.
Prerequisites
To use the Partner API you must meet the following criteria
- Have a working development environment.
- Have an active Partner account. If you need a partner account you can sign up here.
- Enabled your account to use the API and set the access controls.
- Have valid API Credentials.
- Optional - Setup your development environment to initially use the Sandbox Testing Portal.
For Partner API reference documentation please see https://portal.my-engine.com/apidocs/index.html
Example Code
The examples below uses the sandbox. For a production environment remember to change the following:
- API Url
- Partner ID
- Partner API Key
<?php
/**
* outmail-list.php
*
* This example with do an API GET for a list of outmail services for
* a specified client.
*
*/
$apiPartnerId = "<PartnerID>";
$apiSecretKey = "___PartnerKey___";
$apiUrl = "https://sandbox.my-engine.com/api-v1/outmails";
$crlf = "<br />";
// Set the parameters
$queryParameters = array();
// If you want to list _ALL_ all the outMails under a partner comment the line below out
$queryParameters["search"] = "('client_id':'9987606')";
$queryParameters["fields"] = "!(id,client_id,username,password,outmail_server_id,account_status_id,enabled,live_service_endpoint_url,live_service_id)";
// Init Curl
$curl = curl_init();
// API Authentication:
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "$apiPartnerId:$apiSecretKey");
// Set Curl Options
$parameters = http_build_query($queryParameters, '', '&');
curl_setopt($curl, CURLOPT_URL, $apiUrl . "?" . $parameters);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
// API GET
$jsonResult = curl_exec($curl);
// Check for a valid HTTP 200 success and process the returned result
// or handler the failure.
if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) == 200) {
$result = json_decode($jsonResult, true);
if (json_last_error() == JSON_ERROR_NONE) {
// We have valid Json data, so lets display the results.
foreach ($result['data'] as $outmail) {
echo "outMail ID = " . $outmail["id"] . $crlf;
echo "Client ID = " . $outmail["client_id"] . $crlf;
echo "outMail Status = " . $outmail["enabled"] . $crlf;
echo "outMail Billing Status = " . $outmail["account_status_id"] . $crlf;
echo "outMail Server = " . $outmail["outmail_server_id"] . $crlf;
echo "outMail Username = " . $outmail["username"] . $crlf;
echo "outMail Password = " . $outmail["password"] . $crlf;
echo "Live Service URL = " . $outmail["live_service_endpoint_url"] . " (You will need this URL and ID for Delete & Un/Suspend actions)" . $crlf;
echo "Live Service ID = " . $outmail["live_service_id"] . $crlf . $crlf;
}
}
} else {
echo "Response Code = " . curl_getinfo($curl, CURLINFO_RESPONSE_CODE) . $crlf;
$result = json_decode($jsonResult, true);
if (json_last_error() == JSON_ERROR_NONE) {
echo "error = " . $result["error"]["name"] . $crlf;
echo "url = " . $result["error"]["url"] . $crlf;
echo "message = " . $result["error"]["message"] . $crlf;
} else {
echo $jsonResult;
}
}
curl_close($curl);
/**
* outmail-list.cs
*
* This example with do an API GET for a list of outmail services for
* a specified client.
*
*/
using Newtonsoft.Json;
using System;
using System.Collections.Specialized;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
namespace outmail_list
{
class Program
{
private const string apiPartnerId = "<PartnerID>";
private const string apiSecretKey = "_PartnerKey_";
private const string apiUrl = "https://sandbox.my-engine.com/api-v1/outmails";
static async Task Main(string[] args)
{
// Build our parameters
NameValueCollection queryParameters = System.Web.HttpUtility.ParseQueryString(string.Empty);
queryParameters.Add("search", "('client_id':'9987606')");
queryParameters.Add("fields", "!(id,client_id,username,password,outmail_server_id,account_status_id,enabled,live_service_endpoint_url,live_service_id)");
// Create HTTP resource
HttpClient outMail = new HttpClient();
// Add an Accept header for JSON format.
outMail.DefaultRequestHeaders.Add("ContentType", "application/json");
// Set the Authorisation
var authToken = System.Text.Encoding.UTF8.GetBytes(apiPartnerId + ":" + apiSecretKey);
outMail.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", System.Convert.ToBase64String(authToken));
// Do the GET request.
HttpResponseMessage response = await outMail.GetAsync(apiUrl + "?" + queryParameters.ToString());
if (response.IsSuccessStatusCode)
{
var content = response.Content.ReadAsStringAsync();
dynamic details = JsonConvert.DeserializeObject(content.Result);
if (details.ContainsKey("data"))
{
foreach (var item in details["data"])
{
// View the entire record
// Console.WriteLine("data = {0}", item);
// Display the data we want.
Console.WriteLine("outMail ID = {0}", item["id"]);
Console.WriteLine("Client ID = {0}", item["client_id"]);
Console.WriteLine("outMail Status = {0}", item["enabled"]);
Console.WriteLine("outMail Billing Status = {0}", item["account_status_id"]);
Console.WriteLine("outMail Server = {0}", item["outmail_server_id"]);
Console.WriteLine("outMail Username = {0}", item["username"]);
Console.WriteLine("outMail Password = {0}", item["password"]);
Console.WriteLine("Live Service URL = {0} (You will need this URL and ID for Delete & Un/Suspend actions)", item["live_service_endpoint_url"]);
Console.WriteLine("Live Service ID = {0} \n", item["live_service_id"]);
}
}
else
{
Console.WriteLine("response = {0}", response);
Console.WriteLine("json response = {0}", details);
}
}
else
{
// Get the Json Error response and convert it
var jsonResponseStr = response.Content.ReadAsStringAsync().Result;
dynamic jsonResponse = JsonConvert.DeserializeObject(jsonResponseStr);
Console.WriteLine("name = {0}", jsonResponse["error"]["name"]);
Console.WriteLine("url = {0}", jsonResponse["error"]["url"]);
Console.WriteLine("message = {0}", jsonResponse["error"]["message"]);
Console.WriteLine("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
}
//Dispose once all HttpClient calls are complete.
outMail.Dispose();
}
}
}
'
' outmail-list.vb
'
' This example with do an API GET for a list of outmail services for
' a specified client.
'
'
Imports Newtonsoft.Json
Imports System
Imports System.Collections.Specialized
Imports System.Net.Http
Imports System.Net.Http.Headers
Imports System.Threading.Tasks
Module Program
Private Const apiPartnerId As String = "<PartnerID>"
Private Const apiSecretKey As String = "_PartnerKey_"
Private Const apiUrl As String = "https://sandbox.my-engine.com/api-v1/outmails"
Public Sub Main(args As String())
outmailsList().Wait()
End Sub
Public Async Function outmailsList() As Task
' Build our parameters
Dim queryParameters As NameValueCollection = System.Web.HttpUtility.ParseQueryString(String.Empty)
queryParameters.Add("search", "('client_id':'9987606')")
queryParameters.Add("fields", "!(id,client_id,username,password,outmail_server_id,account_status_id,enabled,live_service_endpoint_url,live_service_id)")
' Create HTTP resource
Dim client As New HttpClient()
' Add an Accept header for JSON format.
client.DefaultRequestHeaders.Add("ContentType", "application/json")
' Set the Authorisation
Dim authToken = System.Text.Encoding.UTF8.GetBytes(apiPartnerId + ":" + apiSecretKey)
client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Basic", System.Convert.ToBase64String(authToken))
' Do the GET request.
Dim response As HttpResponseMessage = Await client.GetAsync(apiUrl + "?" + queryParameters.ToString())
If response.IsSuccessStatusCode Then
Dim content = response.Content.ReadAsStringAsync()
Dim details As Object = JsonConvert.DeserializeObject(content.Result)
If details.ContainsKey("data") Then
For Each item In details("data")
' View the entire record
' Console.WriteLine("data = {0}", item)
' Display the data we want.
Console.WriteLine("outMail ID = {0}", item("id"))
Console.WriteLine("Client ID = {0}", item("client_id"))
Console.WriteLine("outMail Status = {0}", item("enabled"))
Console.WriteLine("outMail Billing Status = {0}", item("account_status_id"))
Console.WriteLine("outMail Server = {0}", item("outmail_server_id"))
Console.WriteLine("outMail Username = {0}", item("username"))
Console.WriteLine("outMail Password = {0}", item("password"))
Console.WriteLine("Live Service URL = {0} (You will need this URL and ID for Delete & Un/Suspend actions)", item("live_service_endpoint_url"))
Console.WriteLine("Live Service ID = {0} {1}", item("live_service_id"), vbCrLf)
Next
Else
Console.WriteLine("response = {0}", response)
Console.WriteLine("json response = {0}", details)
End If
Else
' Get the Json Error response And convert it
Dim jsonResponseStr = response.Content.ReadAsStringAsync().Result
Dim jsonResponse As Object = JsonConvert.DeserializeObject(jsonResponseStr)
Console.WriteLine("name = {0}", jsonResponse("error")("name"))
Console.WriteLine("url = {0}", jsonResponse("error")("url"))
Console.WriteLine("message = {0}", jsonResponse("error")("message"))
Console.WriteLine("{0} ({1})", response.StatusCode, response.ReasonPhrase)
End If
'Dispose once all HttpClient calls are complete.
client.Dispose()
End Function
End Module
/**
* outmail-list.js
*
* This example with do an API GET for a list of outmail services for
* a specified client.
*
*/
var apiPartnerId = "<PartnerID>";
var apiSecretKey = "_PartnerKey_";
var apiUrl = "https://sandbox.my-engine.com/api-v1/outmails";
// Set the parameters
// If you want to list _ALL_ all the outMails under a partner comment the line below out
var queryParameters = {
"search": "('client_id':'9987606')",
"fields": "!(id,client_id,username,password,outmail_server_id,account_status_id,enabled,live_service_endpoint_url,live_service_id)"
};
var parameters = $.param(queryParameters, true);
// Setup the Ajax request
var settings = {
url: apiUrl + "?" + parameters,
headers: {
'Authorization': 'Basic ' + btoa(apiPartnerId + ":" + apiSecretKey),
'cache-control': 'no-cache'
},
crossDomain: true,
dataType: 'json',
async: true,
method: "GET"
};
// API GET
$.ajax(settings)
.done(function(response) {
$.each(response.data, function(index, value) {
console.log("outMail ID = " + value.id);
console.log("Client ID = " + value.client_id);
console.log("outMail Status = " + value.enabled);
console.log("outMail Billing Status = " + value.account_status_id);
console.log("outMail Server = " + value.outmail_server_id);
console.log("outMail Username = " + value.username);
console.log("outMail Password = " + value.password);
console.log("Live Service URL = " + value.live_service_endpoint_url + " (You will need this URL and ID for Delete & Un/Suspend actions)");
console.log("Live Service ID = " + value.live_service_id);
console.log(" ");
});
})
.fail(function(request, textStatus, errorThrown) {
try {
var errObj = $.parseJSON(request.responseText);
console.log("API Error - " + errObj.name);
console.log("API Msg - " + errObj.message);
console.log("API url - " + errObj.url);
} catch (e) {
console.log("Error - " + errorThrown);
console.log("Status - " + request.status);
console.log(request);
}
});