Welcome to the documentation for the JSON endpoint of the Emercury API. This is a special endpoint for those who prefer to access the API by sending requests in a JSON format, and also receiving responses in a JSON format.
The JSON endpoint is rooted in the base Emercury XML API, and simply allows you to communicate with our API in JSON instead of XML. Otherwise, you can still use all of the same methods, and use all the same parameters, and expect the same responses.
In order to utilize the JSON endpoint, you will need two things. First you will need to know which Emercury API method you want to reach. And then understand how to communicate with the JSON endpoint.
Learn how the JSON endpoint receives and responds to your requests
There are essentially two parts to communicating with the JSON endpoint. The first is the endpoint itself:
https://api.emercury.net/api-json.php?request=
The second part is a JSON object which you append on like so
https://api.emercury.net/api-json.php?request={yourRequestObject}
Let us take a look at just such an example object with a real-world use case. To keep it simple, we'll construct a request object for the GetAudiences method. This is a method which requires no additional parameters.
{
"request": {
"method": "GetAudiences",
"mail": "[email protected]",
"API_key": "1234567ABCDGH"
}
}
Inside of this object you will notice that we have a “request” key, which we then set to an object that has the following 3 key-value pairs:
The Emercury API method
Your Emercury account email
Your Emercury API key
If we take a look at this same object in a flattened form, it will look like this:
{"request": {"method": "GetAudiences","mail": "[email protected]","API_key": "1234567ABCDGH"}}
And if we attach it to the endpoint, the final request string will look like this:
https://api.emercury.net/api-json.php?request={"request": {"method": "get_audiences","mail": "[email protected]","API_key": "1234567ABCDGH"}}
Note: If this string contains your actual credentials, you can even go ahead and insert it into your browser address bar, hit run and get the list of audiences, right there in your browser. This is because the JSON endpoint is a GET endpoint.
How the JSON endpoint responds to your requests
Let’s continue with the request string we constructed above:
https://api.emercury.net/api-json.php?request={"request": {"method": "get_audiences","mail": "[email protected]","API_key": "1234567ABCDGH"}}
If you send this request, you will get back a list of all the audiences in your Emercury account. This response will come back to you in a JSON format like so:
{
"audiences": [
{
"id": "21831",
"name": "Customers",
"size": "2199",
"subscribers_count": "1056",
"unsubscribed": "279",
"status": "0",
"is_segment": "no"
},
{
"id": "24618",
"name": "Sales Team",
"size": "16",
"subscribers_count": "7",
"unsubscribed": "2",
"status": "0",
"is_segment": "no"
},
{
"id": "29603",
"name": "Unconfirmed Registrations",
"size": "195",
"subscribers_count": "146",
"unsubscribed": "7",
"status": "0",
"is_segment": "no"
}
]
}
How to send a request for a method that requires a single parameter
For this example we'll use a different method. This time we'll utilize GetSubscribers method as it requires a parameter in order to answer your request. The parameter in this case will be the *id of the audience in question.
*Again, remember that the main documentation lists all methods, and what parameters they require.
In this case, the object method will be very similar to the previous one, except that you need one additional key-value pair that looks like this:
"parameters": {yourParametersObject}
In this example we’ll only pass the parameter for “audience_id”, as this is what the GetSubscribers method requires. So with that, our final request object will end up like so:
{
"request": {
"method": "GetSubscribers",
"mail": "[email protected]",
"API_key": "1234567ABCDGH"
"parameters":{
"audience_id":"123"
}
}
}
The flattened version of the request object will look like this:
{"request": {"method": "GetSubscribers", "mail": "[email protected]", "API_key": "1234567ABCDGH", "parameters": {"audience_id": "123}"}}}
And if you attach it to your request string, you will get something like this:
https://api.emercury.net/api-json.php?request={"request": {"method": "GetSubscribers", "mail": "[email protected]", "API_key": "1234567ABCDGH", "parameters": {"audience_id": "123}"}}}
Again, this is a GET request, so you can even paste this into a browser, and it will work. And then, the JSON response you get back from Emercury will look like this:
{
"subscribers": [
{
"email": "[email protected]",
"optin_date": "0000-00-00",
"optin_ip": "",
"optin_website": "",
"first_name": "John",
"last_name": "Doe",
"city": "",
"state": "",
"added": "2021-12-13 18:09:46",
"audience_name": "Customers",
"user_field_3": "",
"user_field_4": "",
"user_field_6": "",
"user_field_10": "",
"user_field_11": "",
"user_field_12": "",
"user_field_13": "",
"user_field_14": "",
"user_field_15": "",
"user_field_16": "",
"user_field_17": "",
"user_field_18": "",
"user_field_19": "",
"user_field_20": "",
"user_field_21": "",
"user_field_22": "",
"user_field_23": "",
"user_field_24": "",
"user_field_25": "",
"user_field_26": "",
"user_field_27": "",
"user_field_28": "",
"user_field_29": "",
"user_field_30": ""
},
{
"email": "[email protected]",
"optin_date": "0000-00-00",
"optin_ip": "",
"optin_website": "",
"first_name": "Jane",
"last_name": "Doe",
"city": "",
"state": "",
"added": "2021-12-13 18:09:46",
"audience_name": "Customers",
"user_field_3": "",
"user_field_4": "",
"user_field_6": "",
"user_field_10": "",
"user_field_11": "",
"user_field_12": "",
"user_field_13": "",
"user_field_14": "",
"user_field_15": "",
"user_field_16": "",
"user_field_17": "",
"user_field_18": "",
"user_field_19": "",
"user_field_20": "",
"user_field_21": "",
"user_field_22": "",
"user_field_23": "",
"user_field_24": "",
"user_field_25": "",
"user_field_26": "",
"user_field_27": "",
"user_field_28": "",
"user_field_29": "",
"user_field_30": ""
}
]
}
How to send a request for a method that requires multiple parameters:
This time we will take the method called addSchedule. This is a method that requires 3 parameters. If we add those in, we will have a parameters object that looks like this:
{
"campaign_id": 238351,
"schedule_date": "03/14/2023",
"schedule_time":"1:15PM"
}
And with that, our final request object should end up like so:
{
"request": {
"method": "addSchedule",
"mail": "[email protected]",
"API_key": "1234567ABCDGH",
"parameters":{
"campaign_id": 238351,
"schedule_date": "03/14/2023",
"schedule_time":"1:15PM"
}
}
}
Available methods and required parameters
In order to choose the right Method you will want to reference the main Emercury API documentation at this location.
Every available method is listed at the top of the page. If you click on a method, you can see which parameters are required or optional. The examples on the page are in XML, but converting to JSON is straightforward.
Let’s take a look at the GetSubscribers method on the API documentation page. If you do so, you will notice that the example XML request looks like this:
<request> <method>GetSubscribers</method> <user mail="[email protected]" API_key="12345ABCDEF67890GHIJK "></user> <parameters> <audience_id>12345</audience_id> </parameters> </request> |
Just notice the bolded parameters part, and you will see it contains a single parameter called audience_id. With this, you will know how to construct your request object for the JSON endpoint.
And if we use what we learned previously, you should end up with this request object:
{
"request": {
"method": "GetSubscribers",
"mail": "[email protected]",
"API_key": "1234567ABCDGH"
"parameters":{
"audience_id":"123"
}
}
}
If you attach it to your request string, you will get something like this:
https://api.emercury.net/api-json.php?request={"request": {"method": "GetSubscribers", "mail": "[email protected]", "API_key": "1234567ABCDGH", "parameters": {"audience_id": "123}"}}}
The same goes for a method with multiple parameters
If we look at the documentation for the addSchedule method again, we will notice that it provides this example of a request in XML.
<request> <user mail="[email protected]" API_key="12345ABCDEF67890GHIJK" /> <method>addSchedule</method> <parameters> <campaign_id>11111</campaign_id> <schedule_date> 03/14/2012 </schedule_date> <schedule_time> 1:15PM </schedule_time> </parameters> </request> |
Bonus tip: If it is easier for you to read JSON, you can use this tool which converts XML to JSON and just paste any of the XML examples there to get the JSON equivalent.
And now that we know that there are 3 parameters, we can utilize them in our parameters object like so:
{
"campaign_id": 238351,
"schedule_date": "03/14/2023",
"schedule_time":"1:15PM"
}
And if we add this parameters object to the request object, we should get this:
{
"request": {
"method": "addSchedule",
"mail": "[email protected]",
"API_key": "1234567ABCDGH",
"parameters":{
"campaign_id": 238351,
"schedule_date": "03/14/2023",
"schedule_time":"1:15PM"
}
}
}
Code examples and patterns
If you want to have an easier time working with the different Emercury methods, one useful pattern is to simply build abstractions or code patterns for each of the three types of Emercury methods.
This includes the Emercury methods that require no parameters, those which require a single parameter, and those that require multiple parameters. To give you an idea we'll present examples for each, written in Node.js; However you could apply these ideas or patterns in the language and technology of your choice.
A pattern for methods with no parameters
Your function can look something like this:
async function methodOnlyRoutes(method) {
const requestString = ` {
"request": {
"method": "${method}",
"mail": "${process.env.EMERCURY_USER_EMAIL}",
"API_key": "${process.env.EMERCURY_API_KEY}"
}
}`
const url = 'https://api.emercury.net/api-json.php?request=' + requestString
await emercuryFetch(url)
}
Note that this function is crafted to accept an Emercury method and simply append it to the request string. Also notice how it pulls your credentials from the .env file which is a good practice for secrets and credentials.
This approach is an easy way to work with Emercury methods that require no parameters, such as for example the method “GetAudiences”.
Also note that we’re calling a method called “emercuryFetch” for an additional level of abstraction. This is in case you need to deal with things like middlewares. This fetching method can look something like this:
async function emercuryFetch(url) {
console.log(url)
try {
const request = await fetch(url, {method: 'GET'})
const response = await request.json()
console.log(response)
} catch (e) {
console.log(e)
}
}
The example includes console.logs for easy testing purposes. You would of course remove these in production and insert your middleware logic, or your preferred method of dealing with the response and errors.
A pattern for methods with a single parameter
async function singleParamRoutes(method, param, paramValue) {
const requestString = ` {
"request": {
"method": "${method}",
"mail": "${process.env.EMERCURY_USER_EMAIL}",
"API_key": "${process.env.EMERCURY_API_KEY}",
"parameters": {"${param}": "${paramValue}"}
}
}`
const url = 'https://api.emercury.net/api-json.php?request=' + requestString
await emercuryFetch(url)
}
Note: This is a generic example for simplicity. We’re sourcing the param value as an argument, however you would create this in whichever way it makes sense for your use case or client.
A pattern for methods with multiple parameters
One pattern you can utilize is take a parameters object, run a stringify method on it, and then append that to the request string. Just remember that a parameter object might look like this:
{
"campaign_id": 238351,
"schedule_date": "03/14/2023",
"schedule_time":"1:15PM"
}
With that said, if we were to create a function that takes such a parameters object and an Emercury method of choice, it might look like this:
async function multiParamRoutes(method, parametersObj) {
const parameters = JSON.stringify(parametersObj)
const requestString = ` {
"request": {
"method": "${method}",
"mail": "${process.env.EMERCURY_USER_EMAIL}",
"API_key": "${process.env.EMERCURY_API_KEY}",
"parameters": ${parameters}
}
}`
const url = 'https://api.emercury.net/api-json.php?request=' + requestString
await emercuryFetch(url)
}
Note how instead of passing the singular parameter and its value as in the previous pattern, we pass the parameters object as an argument.
Note: Again, the function we constructed here is just an illustrative example for simplicity. In a real world scenario some of this might be going through middlewares.