NAV Navigation
UniOne Documentation
HTTP PHP Python Ruby C# Java Node.JS
 

Web API v1.15.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

All UniOne API methods require HTTPS connection. UniOne accepts HTTP POST requests in JSON format up to 5 megabytes long and returns HTTP response also in JSON. API endpoint (or base URL) depends on which datacenter the user is registered at.

Authentication

Every method call requires authentication by providing user API key or project API key in either of two places:

You can obtain user API key in account settings. Project API key can be obtained using Projects page or by project API methods.

Error Handling

UniOne API method call returns HTTP code 200 OK on success or HTTP code 4xx/5xx on error:

HTTP Code Meaning
200 OK – Request was successfully processed.
400 Bad Request – Your request is invalid. Please check request format and parameters.
401 Unauthorized – Your API key is wrong.
403 Forbidden – Not enough rights to process the request.
404 Not Found – The specified endpoint not found.
429 Too many requests – Please slow down request rate.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

HTTP error code gives generic information about error reason, but usually a JSON object is returned also with more details and API error code. Read more in API Errors section.

Email Methods

This group of methods is related with email sending.

email-send

POST https://us1.unione.io/en/transactional/api/v1/email/send.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"message": {
"recipients": [
{
"email": "user@example.com",
"substitutions": {
"CustomerId": 12452,
"to_name": "John Smith"
},
"metadata": {
"campaign_id": "email61324",
"customer_hash": "b253ac7"
}
}
],
"template_id": "string",
"skip_unsubscribe": 0,
"template_engine": "simple",
"global_substitutions": {
"property1": "string",
"property2": "string"
},
"global_metadata": {
"property1": "string",
"property2": "string"
},
"body": {
"html": "<b>Hello, {{to_name}}</b>",
"plaintext": "Hello, {{to_name}}",
"amp": "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>"
},
"subject": "string",
"from_email": "user@example.com",
"from_name": "John Smith",
"reply_to": "user@example.com",
"track_links": 0,
"track_read": 0,
"headers": {
"X-MyHeader": "some data",
"List-Unsubscribe": "<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>"
},
"attachments": [
{
"type": "text/plain",
"name": "readme.txt",
"content": "SGVsbG8sIHdvcmxkIQ=="
}
],
"inline_attachments": [
{
"type": "image/gif",
"name": "IMAGECID1",
"content": "R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw=="
}
],
"options": {
"unsubscribe_url": "https://example.org/unsubscribe/{{CustomerId}}",
"smtp_pool_id": "string"
}
}
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"message" => [
"recipients" => [
[
"email" => "user@example.com",
"substitutions" => [
"CustomerId" => 12452,
"to_name" => "John Smith"
],
"metadata" => [
"campaign_id" => "email61324",
"customer_hash" => "b253ac7"
]
]
],
"template_id" => "string",
"skip_unsubscribe" => 0,
"template_engine" => "simple",
"global_substitutions" => [
"property1" => "string",
"property2" => "string"
],
"global_metadata" => [
"property1" => "string",
"property2" => "string"
],
"body" => [
"html" => "<b>Hello, {{to_name}}</b>",
"plaintext" => "Hello, {{to_name}}",
"amp" => "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body[visibility:hidden]</style></head><body> Hello, AMP4EMAIL world.</body></html>"
],
"subject" => "string",
"from_email" => "user@example.com",
"from_name" => "John Smith",
"reply_to" => "user@example.com",
"track_links" => 0,
"track_read" => 0,
"headers" => [
"X-MyHeader" => "some data",
"List-Unsubscribe" => "<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>"
],
"attachments" => [
[
"type" => "text/plain",
"name" => "readme.txt",
"content" => "SGVsbG8sIHdvcmxkIQ=="
]
],
"inline_attachments" => [
[
"type" => "image/gif",
"name" => "IMAGECID1",
"content" => "R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw=="
]
],
"options" => [
"unsubscribe_url" => "https://example.org/unsubscribe/{{CustomerId}}",
"smtp_pool_id" => "string"
]
]
];

try {
$response = $client->request('POST','email/send.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"message": {
"recipients": [
{
"email": "user@example.com",
"substitutions": {
"CustomerId": 12452,
"to_name": "John Smith"
},
"metadata": {
"campaign_id": "email61324",
"customer_hash": "b253ac7"
}
}
],
"template_id": "string",
"skip_unsubscribe": 0,
"template_engine": "simple",
"global_substitutions": {
"property1": "string",
"property2": "string"
},
"global_metadata": {
"property1": "string",
"property2": "string"
},
"body": {
"html": "<b>Hello, {{to_name}}</b>",
"plaintext": "Hello, {{to_name}}",
"amp": "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>"
},
"subject": "string",
"from_email": "user@example.com",
"from_name": "John Smith",
"reply_to": "user@example.com",
"track_links": 0,
"track_read": 0,
"headers": {
"X-MyHeader": "some data",
"List-Unsubscribe": "<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>"
},
"attachments": [
{
"type": "text/plain",
"name": "readme.txt",
"content": "SGVsbG8sIHdvcmxkIQ=="
}
],
"inline_attachments": [
{
"type": "image/gif",
"name": "IMAGECID1",
"content": "R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw=="
}
],
"options": {
"unsubscribe_url": "https://example.org/unsubscribe/{{CustomerId}}",
"smtp_pool_id": "string"
}
}
}
r = requests.post(base_url+'/email/send.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/email/send.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/email/send.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/email/send.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"message\": {"
+" \"recipients\": ["
+" {"
+" \"email\": \"user@example.com\","
+" \"substitutions\": {"
+" \"CustomerId\": 12452,"
+" \"to_name\": \"John Smith\""
+" },"
+" \"metadata\": {"
+" \"campaign_id\": \"email61324\","
+" \"customer_hash\": \"b253ac7\""
+" }"
+" }"
+" ],"
+" \"template_id\": \"string\","
+" \"skip_unsubscribe\": 0,"
+" \"template_engine\": \"simple\","
+" \"global_substitutions\": {"
+" \"property1\": \"string\","
+" \"property2\": \"string\""
+" },"
+" \"global_metadata\": {"
+" \"property1\": \"string\","
+" \"property2\": \"string\""
+" },"
+" \"body\": {"
+" \"html\": \"<b>Hello, {{to_name}}</b>\","
+" \"plaintext\": \"Hello, {{to_name}}\","
+" \"amp\": \"<!doctype html><html amp4email><head> <meta charset=\\\"utf-8\\\"><script async src=\\\"https://cdn.ampproject.org/v0.js\\\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>\""
+" },"
+" \"subject\": \"string\","
+" \"from_email\": \"user@example.com\","
+" \"from_name\": \"John Smith\","
+" \"reply_to\": \"user@example.com\","
+" \"track_links\": 0,"
+" \"track_read\": 0,"
+" \"headers\": {"
+" \"X-MyHeader\": \"some data\","
+" \"List-Unsubscribe\": \"<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>\""
+" },"
+" \"attachments\": ["
+" {"
+" \"type\": \"text/plain\","
+" \"name\": \"readme.txt\","
+" \"content\": \"SGVsbG8sIHdvcmxkIQ==\""
+" }"
+" ],"
+" \"inline_attachments\": ["
+" {"
+" \"type\": \"image/gif\","
+" \"name\": \"IMAGECID1\","
+" \"content\": \"R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw==\""
+" }"
+" ],"
+" \"options\": {"
+" \"unsubscribe_url\": \"https://example.org/unsubscribe/{{CustomerId}}\","
+" \"smtp_pool_id\": \"string\""
+" }"
+" }"
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"message": {
"recipients": [
{
"email": "user@example.com",
"substitutions": {
"CustomerId": 12452,
"to_name": "John Smith"
},
"metadata": {
"campaign_id": "email61324",
"customer_hash": "b253ac7"
}
}
],
"template_id": "string",
"skip_unsubscribe": 0,
"template_engine": "simple",
"global_substitutions": {
"property1": "string",
"property2": "string"
},
"global_metadata": {
"property1": "string",
"property2": "string"
},
"body": {
"html": "<b>Hello, {{to_name}}</b>",
"plaintext": "Hello, {{to_name}}",
"amp": "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>"
},
"subject": "string",
"from_email": "user@example.com",
"from_name": "John Smith",
"reply_to": "user@example.com",
"track_links": 0,
"track_read": 0,
"headers": {
"X-MyHeader": "some data",
"List-Unsubscribe": "<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>"
},
"attachments": [
{
"type": "text/plain",
"name": "readme.txt",
"content": "SGVsbG8sIHdvcmxkIQ=="
}
],
"inline_attachments": [
{
"type": "image/gif",
"name": "IMAGECID1",
"content": "R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw=="
}
],
"options": {
"unsubscribe_url": "https://example.org/unsubscribe/{{CustomerId}}",
"smtp_pool_id": "string"
}
}
};
fetch('https://us1.unione.io/en/transactional/api/v1/email/send.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/email/send.json

Sends an email or a bunch of emails

While sending you can provide substitutions (merge tags), use a template, turn on read or click tracking, etc.

Restrictions:

If the list of recipients contains invalid, non-existent, duplicate, or unsubscribed emails, those emails will be returned in the output parameter failed_emails, and the email will be sent to all other valid emails addresses. If all the emails addresses fall into failed_emails, sending will not be carried out and API error 204 will be returned.

Parameters

Name Type Description
message Required
object
Object containing all message properties.
» recipients Required
array
Contains recipient emails, substitutions(merge tags) and metadata.
»» email Required
string(email)
Recipient email
»» substitutions Optional
object
Object to pass the substitutions(merge tags) for the recipient (e.g. recipient name, discount code, password change link, etc. See Template engines). The substitutions can be used in the following parameters:
  • body.html
  • body.plaintext
  • body.amp
  • subject
  • from_name
  • headers
  • options.unsubscribe_url
A substitution name can consist from latin characeters, numbers and “_” or “-” symbols, and should start with the letter. There’s a special substitution “to_name” which is used to put recipent’s name like “Name Surname” to include it to SMTP header “To” in the form “Name Surname <email@example.com>”. The “to_name” length is limited to 78 symbols.
»» metadata Optional
object
Object for passing the metadata, such as “key”: “value”. Max key quantity: 10. Max key length: 64 symbols. Max value length: 1024 symbols. The metadata is returned by webhook.
» template_id Optional
string(uuid)
Optional identifier of the template that had been created by template/set method. If “body” is passed, “template_id” will be ignored.
» skip_unsubscribe Optional
integer
Whether to skip or not appending default unsubscribe footer. 1=skip, 0=append, default is 0. You should ask support to approve
» template_engine Optional
string
The template engine for handling the substitutions(merge tags), “simple” or “velocity”. Default value is “simple”.
» global_substitutions Optional
object
Object for passing the substitutions(merge tags) common for all recipients - e.g., company name. If the substitution names are duplicated in object “substitutions”, the values of the variables will be taken from the object “substitutions”. The substitutions can be used in the following parameters:
  • body.html
  • body.plaintext
  • body.amp
  • subject
  • from_name
  • headers
  • options.unsubscribe_url
A substitution name can consist from latin characeters, numbers and “_” or “-” symbols, and should start with the letter.
» global_metadata Optional
object
Object for passing the metadata, such as “key”: “value”. Max key quantity: 10. Max key length: 64 symbols. Max value length: 1024 symbols. The metadata is returned by webhook.
» body Optional
object
Contains HTML/plaintext/AMP parts of the email.
»» html Required
string
Required HTML part of the email body
»» plaintext Optional
string
Optional plaintext part of the email body.
»» amp Optional
string
Optional AMP part of the email body.
» subject Optional
string
Email subject.
» from_email Optional
string
Sender’s email.
» from_name Optional
string
Sender’s name.
» reply_to Optional
string
Optional Reply-To email (in case it’s different to sender’s email)
» track_links Optional
integer
1=click tracking is on (default), 0=click tracking is off
» track_read Optional
integer
1=read tracking is on (default), 0=read tracking is off
» headers Optional
object
Contains email headers, maximum 50. Only headers with “X-” name prefix are accepted, all other are ignored. If our support have approved omitting standard unsubscription block for you, you can also pass List-Unsubscribe, List-Subscribe, List-Help, List-Owner and List-Archive headers.
» attachments Optional
array
Optional array of attachments
»» type Required
string
Attachment type, see MIME. If unsure, use “application/octet-stream”.
»» name Required
string
Attachment name in the format: “name.extension”
»» content Required
string(byte)
File contents in base64.
» inline_attachments Optional
array
Optional array of inline attachments, e.g. for including images in email instead of loading them from external URL.
»» type Required
string
Attachment type, see MIME. If unsure, use “application/octet-stream”.
»» name Required
string
Attachment content id. For example, “name”=“IMAGECID1” should be referenced in HTML like <img src=“cid:IMAGECID1”>
»» content Required
string(byte)
File contents in base64.
» options Optional
object
Additional message options.
»» unsubscribe_url Optional
string
Custom unsubscribe link. Read more here.
»» smtp_pool_id Optional
string(uuid)
SMTP pool identifier to send message with. If smtp_pool_id is not set, default one for your account/project will be used. You can pay for one or more dedicated IPs and use this option to choose sending using dedicated IP or common pool. Contact support to get SMTP identifiers of common pool and your dedicated SMTP.

200 Response

{
"status": "success",
"job_id": "1ZymBc-00041N-9X",
"emails": [
"user@example.com"
],
"failed_emails": {
"email1@gmail.com": "temporary_unavailable",
"bad@address": "invalid",
"email@example.com": "duplicate",
"root@example.org": "permanent_unavailable",
"olduser@example.net": "unsubscribed"
}
}

Response Schema

HTTP Code 200:

Email successfully accepted for sending.

Name Type Description
status Required
string
“success” string
job_id Required
string
Job identifier, might be useful for investigating errors.
emails Optional
array
Array of recipients emails successfully accepted for sending.
failed_emails Optional
array
Array of objects with recipients emails rejected for sending and their statuses, e.g.: [{“email1@gmail.com”: “temporary_unavailable”}]. Possible statuses:
  • unsubscribed - specified email is unsubscribed;
  • invalid - the email does not exist or has been entered incorrectly;
  • duplicate - the email already exists in the request, email duplicating is prevented;
  • temporary_unavailable - the email address is unavailable. This means that over the next three days sending to this address will return an error. Email may be temporarily unavailable due to one of the following reasons:
    1. a previous email has been rejected by the recipient’s server for spam;
    2. the recipient’s mailbox is full or is not used;
    3. recipient’s domain does not accept mail;
    4. sending server was rejected due to blacklisting;
  • permanent_unavailable - the email address is permanently unavailable, unsubscribed globally, or the recipient reported spam in the previous emails.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

email-subscribe

POST https://us1.unione.io/en/transactional/api/v1/email/subscribe.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"from_email": "user@example.com",
"from_name": "string",
"to_email": "user@example.com"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"from_email" => "user@example.com",
"from_name" => "string",
"to_email" => "user@example.com"
];

try {
$response = $client->request('POST','email/subscribe.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"from_email": "user@example.com",
"from_name": "string",
"to_email": "user@example.com"
}
r = requests.post(base_url+'/email/subscribe.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/email/subscribe.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/email/subscribe.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/email/subscribe.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"from_email\": \"user@example.com\","
+" \"from_name\": \"string\","
+" \"to_email\": \"user@example.com\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"from_email": "user@example.com",
"from_name": "string",
"to_email": "user@example.com"
};
fetch('https://us1.unione.io/en/transactional/api/v1/email/subscribe.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/email/subscribe.json

Sends an email with (re)subscribe link.

This method allows subscription renewal by a former subscriber who has previously unsubscribed, or who is blocked because of complaints. This method sends an email with a new subscription link to a former subscriber. Once the recipient clicks the link, their subscription status is restored. There is a default restriction that limits this method to being used once a day. If you need to resubscribe more often, please ask support about it.

Parameters

Name Type Description
from_email Required
string(email)
Sender’s email. (Field alias “email_address_from” is supported, too).
from_name Required
string
Sender’s name. (Field alias “name_from” is supported, too).
to_email Required
string(email)
Recipient’s email. (Field alias “email_address_to” is supported, too).

200 Response

{
"status": "success"
}

Response Schema

HTTP Code 200:

Email successfully accepted for sending.

Name Type Description
status Required
string
“success” string

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

Template Methods

You have the option of storing a template on the UniOne side and then using it by id, which is highly recommended for sending repetitive messages or high volume traffic. UniOne supports two different template engines.

template-set

POST https://us1.unione.io/en/transactional/api/v1/template/set.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"template": {
"id": "string",
"name": "string",
"editor_type": "html",
"template_engine": "simple",
"global_substitutions": {
"property1": "string",
"property2": "string"
},
"global_metadata": {
"property1": "string",
"property2": "string"
},
"body": {
"html": "<b>Hello, {{to_name}}</b>",
"plaintext": "Hello, {{to_name}}",
"amp": "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>"
},
"subject": "string",
"from_email": "user@example.com",
"from_name": "John Smith",
"reply_to": "user@example.com",
"track_links": 0,
"track_read": 0,
"headers": {
"X-MyHeader": "some data",
"List-Unsubscribe": "<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>"
},
"attachments": [
{
"type": "text/plain",
"name": "readme.txt",
"content": "SGVsbG8sIHdvcmxkIQ=="
}
],
"inline_attachments": [
{
"type": "image/gif",
"name": "IMAGECID1",
"content": "R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw=="
}
]
}
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"template" => [
"id" => "string",
"name" => "string",
"editor_type" => "html",
"template_engine" => "simple",
"global_substitutions" => [
"property1" => "string",
"property2" => "string"
],
"global_metadata" => [
"property1" => "string",
"property2" => "string"
],
"body" => [
"html" => "<b>Hello, {{to_name}}</b>",
"plaintext" => "Hello, {{to_name}}",
"amp" => "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body[visibility:hidden]</style></head><body> Hello, AMP4EMAIL world.</body></html>"
],
"subject" => "string",
"from_email" => "user@example.com",
"from_name" => "John Smith",
"reply_to" => "user@example.com",
"track_links" => 0,
"track_read" => 0,
"headers" => [
"X-MyHeader" => "some data",
"List-Unsubscribe" => "<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>"
],
"attachments" => [
[
"type" => "text/plain",
"name" => "readme.txt",
"content" => "SGVsbG8sIHdvcmxkIQ=="
]
],
"inline_attachments" => [
[
"type" => "image/gif",
"name" => "IMAGECID1",
"content" => "R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw=="
]
]
]
];

try {
$response = $client->request('POST','template/set.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"template": {
"id": "string",
"name": "string",
"editor_type": "html",
"template_engine": "simple",
"global_substitutions": {
"property1": "string",
"property2": "string"
},
"global_metadata": {
"property1": "string",
"property2": "string"
},
"body": {
"html": "<b>Hello, {{to_name}}</b>",
"plaintext": "Hello, {{to_name}}",
"amp": "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>"
},
"subject": "string",
"from_email": "user@example.com",
"from_name": "John Smith",
"reply_to": "user@example.com",
"track_links": 0,
"track_read": 0,
"headers": {
"X-MyHeader": "some data",
"List-Unsubscribe": "<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>"
},
"attachments": [
{
"type": "text/plain",
"name": "readme.txt",
"content": "SGVsbG8sIHdvcmxkIQ=="
}
],
"inline_attachments": [
{
"type": "image/gif",
"name": "IMAGECID1",
"content": "R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw=="
}
]
}
}
r = requests.post(base_url+'/template/set.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/template/set.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/template/set.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/template/set.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"template\": {"
+" \"id\": \"string\","
+" \"name\": \"string\","
+" \"editor_type\": \"html\","
+" \"template_engine\": \"simple\","
+" \"global_substitutions\": {"
+" \"property1\": \"string\","
+" \"property2\": \"string\""
+" },"
+" \"global_metadata\": {"
+" \"property1\": \"string\","
+" \"property2\": \"string\""
+" },"
+" \"body\": {"
+" \"html\": \"<b>Hello, {{to_name}}</b>\","
+" \"plaintext\": \"Hello, {{to_name}}\","
+" \"amp\": \"<!doctype html><html amp4email><head> <meta charset=\\\"utf-8\\\"><script async src=\\\"https://cdn.ampproject.org/v0.js\\\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>\""
+" },"
+" \"subject\": \"string\","
+" \"from_email\": \"user@example.com\","
+" \"from_name\": \"John Smith\","
+" \"reply_to\": \"user@example.com\","
+" \"track_links\": 0,"
+" \"track_read\": 0,"
+" \"headers\": {"
+" \"X-MyHeader\": \"some data\","
+" \"List-Unsubscribe\": \"<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>\""
+" },"
+" \"attachments\": ["
+" {"
+" \"type\": \"text/plain\","
+" \"name\": \"readme.txt\","
+" \"content\": \"SGVsbG8sIHdvcmxkIQ==\""
+" }"
+" ],"
+" \"inline_attachments\": ["
+" {"
+" \"type\": \"image/gif\","
+" \"name\": \"IMAGECID1\","
+" \"content\": \"R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw==\""
+" }"
+" ]"
+" }"
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"template": {
"id": "string",
"name": "string",
"editor_type": "html",
"template_engine": "simple",
"global_substitutions": {
"property1": "string",
"property2": "string"
},
"global_metadata": {
"property1": "string",
"property2": "string"
},
"body": {
"html": "<b>Hello, {{to_name}}</b>",
"plaintext": "Hello, {{to_name}}",
"amp": "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>"
},
"subject": "string",
"from_email": "user@example.com",
"from_name": "John Smith",
"reply_to": "user@example.com",
"track_links": 0,
"track_read": 0,
"headers": {
"X-MyHeader": "some data",
"List-Unsubscribe": "<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>"
},
"attachments": [
{
"type": "text/plain",
"name": "readme.txt",
"content": "SGVsbG8sIHdvcmxkIQ=="
}
],
"inline_attachments": [
{
"type": "image/gif",
"name": "IMAGECID1",
"content": "R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw=="
}
]
}
};
fetch('https://us1.unione.io/en/transactional/api/v1/template/set.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/template/set.json

Creates or updates an email template.

If you omit the “id” field then new template will be created. If you specify the “id” field, the system will try to find a template with the specified id and edit it.

Restrictions:

Parameters

Name Type Description
template Required
object
Object with all the template properties.
» id Optional
string(uuid)
Template unique identifier.
» name Optional
string
Template name.
» editor_type Optional
string
Editor type, “html” or “visual”. Default is “html”. You can create a template with “visual” editor type only in web interface.
» template_engine Optional
string
The template engine for handling the substitutions(merge tags), “simple” or “velocity”. Default value is “simple”.
» global_substitutions Optional
object
Object for passing the substitutions(merge tags) common for all recipients - e.g., company name. If the substitution names are duplicated in object “substitutions”, the values of the variables will be taken from the object “substitutions”. The substitutions can be used in the following parameters:
  • body.html
  • body.plaintext
  • body.amp
  • subject
  • from_name
  • headers
  • options.unsubscribe_url
A substitution name can consist from latin characeters, numbers and “_” or “-” symbols, and should start with the letter.
» global_metadata Optional
object
Object for passing the metadata, such as “key”: “value”. Max key quantity: 10. Max key length: 64 symbols. Max value length: 1024 symbols. The metadata is returned by webhook.
» body Optional
object
Contains HTML/plaintext/AMP parts of the email.
»» html Required
string
Required HTML part of the email body
»» plaintext Optional
string
Optional plaintext part of the email body.
»» amp Optional
string
Optional AMP part of the email body.
» subject Optional
string
Email subject.
» from_email Optional
string
Sender’s email.
» from_name Optional
string
Sender’s name.
» reply_to Optional
string
Optional Reply-To email (in case it’s different to sender’s email)
» track_links Optional
integer
1=click tracking is on (default), 0=click tracking is off
» track_read Optional
integer
1=read tracking is on (default), 0=read tracking is off
» headers Optional
object
Contains email headers, maximum 50. Only headers with “X-” name prefix are accepted, all other are ignored. If our support have approved omitting standard unsubscription block for you, you can also pass List-Unsubscribe, List-Subscribe, List-Help, List-Owner and List-Archive headers.
» attachments Optional
array
Optional array of attachments
»» type Required
string
Attachment type, see MIME. If unsure, use “application/octet-stream”.
»» name Required
string
Attachment name in the format: “name.extension”
»» content Required
string(byte)
File contents in base64.
» inline_attachments Optional
array
Optional array of inline attachments, e.g. for including images in email instead of loading them from external URL.
»» type Required
string
Attachment type, see MIME. If unsure, use “application/octet-stream”.
»» name Required
string
Attachment content id. For example, “name”=“IMAGECID1” should be referenced in HTML like <img src=“cid:IMAGECID1”>
»» content Required
string(byte)
File contents in base64.

200 Response

{
"status": "success",
"template": {
"id": "string",
"name": "string",
"editor_type": "html",
"template_engine": "simple",
"global_substitutions": {
"property1": "string",
"property2": "string"
},
"global_metadata": {
"property1": "string",
"property2": "string"
},
"body": {
"html": "<b>Hello, {{to_name}}</b>",
"plaintext": "Hello, {{to_name}}",
"amp": "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>"
},
"subject": "string",
"from_email": "user@example.com",
"from_name": "John Smith",
"reply_to": "user@example.com",
"track_links": 0,
"track_read": 0,
"headers": {
"X-MyHeader": "some data",
"List-Unsubscribe": "<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>"
},
"attachments": [
{
"type": "text/plain",
"name": "readme.txt",
"content": "SGVsbG8sIHdvcmxkIQ=="
}
],
"inline_attachments": [
{
"type": "image/gif",
"name": "IMAGECID1",
"content": "R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw=="
}
]
}
}

Response Schema

HTTP Code 200:

Template set successfully.

Name Type Description
status Required
string
“success” string
template Required
object
Object with all the template properties.
» id Optional
string(uuid)
Template unique identifier.
» name Optional
string
Template name.
» editor_type Optional
string
Editor type, “html” or “visual”. Default is “html”. You can create a template with “visual” editor type only in web interface.
» template_engine Optional
string
The template engine for handling the substitutions(merge tags), “simple” or “velocity”. Default value is “simple”.
» global_substitutions Optional
object
Object for passing the substitutions(merge tags) common for all recipients - e.g., company name. If the substitution names are duplicated in object “substitutions”, the values of the variables will be taken from the object “substitutions”. The substitutions can be used in the following parameters:
  • body.html
  • body.plaintext
  • body.amp
  • subject
  • from_name
  • headers
  • options.unsubscribe_url
A substitution name can consist from latin characeters, numbers and “_” or “-” symbols, and should start with the letter.
» global_metadata Optional
object
Object for passing the metadata, such as “key”: “value”. Max key quantity: 10. Max key length: 64 symbols. Max value length: 1024 symbols. The metadata is returned by webhook.
» body Optional
object
Contains HTML/plaintext/AMP parts of the email.
»» html Required
string
Required HTML part of the email body
»» plaintext Optional
string
Optional plaintext part of the email body.
»» amp Optional
string
Optional AMP part of the email body.
» subject Optional
string
Email subject.
» from_email Optional
string
Sender’s email.
» from_name Optional
string
Sender’s name.
» reply_to Optional
string
Optional Reply-To email (in case it’s different to sender’s email)
» track_links Optional
integer
1=click tracking is on (default), 0=click tracking is off
» track_read Optional
integer
1=read tracking is on (default), 0=read tracking is off
» headers Optional
object
Contains email headers, maximum 50. Only headers with “X-” name prefix are accepted, all other are ignored. If our support have approved omitting standard unsubscription block for you, you can also pass List-Unsubscribe, List-Subscribe, List-Help, List-Owner and List-Archive headers.
» attachments Optional
array
Optional array of attachments
»» type Required
string
Attachment type, see MIME. If unsure, use “application/octet-stream”.
»» name Required
string
Attachment name in the format: “name.extension”
»» content Required
string(byte)
File contents in base64.
» inline_attachments Optional
array
Optional array of inline attachments, e.g. for including images in email instead of loading them from external URL.
»» type Required
string
Attachment type, see MIME. If unsure, use “application/octet-stream”.
»» name Required
string
Attachment content id. For example, “name”=“IMAGECID1” should be referenced in HTML like <img src=“cid:IMAGECID1”>
»» content Required
string(byte)
File contents in base64.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

template-get

POST https://us1.unione.io/en/transactional/api/v1/template/get.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"id": "string"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"id" => "string"
];

try {
$response = $client->request('POST','template/get.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"id": "string"
}
r = requests.post(base_url+'/template/get.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/template/get.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/template/get.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/template/get.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"id\": \"string\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"id": "string"
};
fetch('https://us1.unione.io/en/transactional/api/v1/template/get.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/template/get.json

Gets template properties by it’s id.

Parameters

Name Type Description
id Required
string(uuid)
Template id.

200 Response

{
"status": "success",
"template": {
"id": "string",
"name": "string",
"editor_type": "html",
"template_engine": "simple",
"global_substitutions": {
"property1": "string",
"property2": "string"
},
"global_metadata": {
"property1": "string",
"property2": "string"
},
"body": {
"html": "<b>Hello, {{to_name}}</b>",
"plaintext": "Hello, {{to_name}}",
"amp": "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>"
},
"subject": "string",
"from_email": "user@example.com",
"from_name": "John Smith",
"reply_to": "user@example.com",
"track_links": 0,
"track_read": 0,
"headers": {
"X-MyHeader": "some data",
"List-Unsubscribe": "<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>"
},
"attachments": [
{
"type": "text/plain",
"name": "readme.txt",
"content": "SGVsbG8sIHdvcmxkIQ=="
}
],
"inline_attachments": [
{
"type": "image/gif",
"name": "IMAGECID1",
"content": "R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw=="
}
]
}
}

Response Schema

HTTP Code 200:

Template returned successfully.

Name Type Description
status Required
string
“success” string
template Required
object
Object with all the template properties.
» id Optional
string(uuid)
Template unique identifier.
» name Optional
string
Template name.
» editor_type Optional
string
Editor type, “html” or “visual”. Default is “html”. You can create a template with “visual” editor type only in web interface.
» template_engine Optional
string
The template engine for handling the substitutions(merge tags), “simple” or “velocity”. Default value is “simple”.
» global_substitutions Optional
object
Object for passing the substitutions(merge tags) common for all recipients - e.g., company name. If the substitution names are duplicated in object “substitutions”, the values of the variables will be taken from the object “substitutions”. The substitutions can be used in the following parameters:
  • body.html
  • body.plaintext
  • body.amp
  • subject
  • from_name
  • headers
  • options.unsubscribe_url
A substitution name can consist from latin characeters, numbers and “_” or “-” symbols, and should start with the letter.
» global_metadata Optional
object
Object for passing the metadata, such as “key”: “value”. Max key quantity: 10. Max key length: 64 symbols. Max value length: 1024 symbols. The metadata is returned by webhook.
» body Optional
object
Contains HTML/plaintext/AMP parts of the email.
»» html Required
string
Required HTML part of the email body
»» plaintext Optional
string
Optional plaintext part of the email body.
»» amp Optional
string
Optional AMP part of the email body.
» subject Optional
string
Email subject.
» from_email Optional
string
Sender’s email.
» from_name Optional
string
Sender’s name.
» reply_to Optional
string
Optional Reply-To email (in case it’s different to sender’s email)
» track_links Optional
integer
1=click tracking is on (default), 0=click tracking is off
» track_read Optional
integer
1=read tracking is on (default), 0=read tracking is off
» headers Optional
object
Contains email headers, maximum 50. Only headers with “X-” name prefix are accepted, all other are ignored. If our support have approved omitting standard unsubscription block for you, you can also pass List-Unsubscribe, List-Subscribe, List-Help, List-Owner and List-Archive headers.
» attachments Optional
array
Optional array of attachments
»» type Required
string
Attachment type, see MIME. If unsure, use “application/octet-stream”.
»» name Required
string
Attachment name in the format: “name.extension”
»» content Required
string(byte)
File contents in base64.
» inline_attachments Optional
array
Optional array of inline attachments, e.g. for including images in email instead of loading them from external URL.
»» type Required
string
Attachment type, see MIME. If unsure, use “application/octet-stream”.
»» name Required
string
Attachment content id. For example, “name”=“IMAGECID1” should be referenced in HTML like <img src=“cid:IMAGECID1”>
»» content Required
string(byte)
File contents in base64.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

template-list

POST https://us1.unione.io/en/transactional/api/v1/template/list.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"limit": 50,
"offset": 0
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"limit" => 50,
"offset" => 0
];

try {
$response = $client->request('POST','template/list.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"limit": 50,
"offset": 0
}
r = requests.post(base_url+'/template/list.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/template/list.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/template/list.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/template/list.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"limit\": 50,"
+" \"offset\": 0"
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"limit": 50,
"offset": 0
};
fetch('https://us1.unione.io/en/transactional/api/v1/template/list.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/template/list.json

Returns the list of all or some templates of the account.

You can iterate thru large list using “offset” and “limit” parameters. When less than “limit” templates are returned then the end of list is reached.

Parameters

Name Type Description
limit Optional
integer
Limits the number of templates returned, default is 50.
offset Optional
integer
Index of the first template in the list, starting with 0.

200 Response

{
"status": "success",
"templates": [
{
"id": "string",
"editor_type": "html",
"template_engine": "simple",
"global_substitutions": {
"property1": "string",
"property2": "string"
},
"global_metadata": {
"property1": "string",
"property2": "string"
},
"body": {
"html": "<b>Hello, {{to_name}}</b>",
"plaintext": "Hello, {{to_name}}",
"amp": "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body{visibility:hidden}</style></head><body> Hello, AMP4EMAIL world.</body></html>"
},
"subject": "string",
"from_email": "user@example.com",
"from_name": "John Smith",
"reply_to": "user@example.com",
"track_links": 0,
"track_read": 0,
"headers": {
"X-MyHeader": "some data",
"List-Unsubscribe": "<mailto: unsubscribe@example.com?subject=unsubscribe>, <http://www.example.com/unsubscribe/{{CustomerId}}>"
},
"attachments": [
{
"type": "text/plain",
"name": "readme.txt",
"content": "SGVsbG8sIHdvcmxkIQ=="
}
],
"inline_attachments": [
{
"type": "image/gif",
"name": "IMAGECID1",
"content": "R0lGODdhAwADAIABAP+rAP///ywAAAAAAwADAAACBIQRBwUAOw=="
}
],
"created": "string",
"user_id": 11344,
"project_id": "6123462132634",
"project_name": "Project 1A"
}
]
}

Response Schema

HTTP Code 200:

Template list returned successfully.

Name Type Description
status Required
string
“success” string
templates Required
array
Array of template objects.
» id Optional
string(uuid)
Template unique identifier.
» editor_type Optional
string
Editor type, “html” or “visual”. Default is “html”. You can create a template with “visual” editor type only in web interface.
» template_engine Optional
string
The template engine for handling the substitutions(merge tags), “simple” or “velocity”. Default value is “simple”.
» global_substitutions Optional
object
Object for passing the substitutions(merge tags) common for all recipients - e.g., company name. If the substitution names are duplicated in object “substitutions”, the values of the variables will be taken from the object “substitutions”. The substitutions can be used in the following parameters:
  • body.html
  • body.plaintext
  • body.amp
  • subject
  • from_name
  • headers
  • options.unsubscribe_url
A substitution name can consist from latin characeters, numbers and “_” or “-” symbols, and should start with the letter.
» global_metadata Optional
object
Object for passing the metadata, such as “key”: “value”. Max key quantity: 10. Max key length: 64 symbols. Max value length: 1024 symbols. The metadata is returned by webhook.
» body Optional
object
Contains HTML/plaintext/AMP parts of the email.
»» html Required
string
Required HTML part of the email body
»» plaintext Optional
string
Optional plaintext part of the email body.
»» amp Optional
string
Optional AMP part of the email body.
» subject Optional
string
Email subject.
» from_email Optional
string
Sender’s email.
» from_name Optional
string
Sender’s name.
» reply_to Optional
string
Optional Reply-To email (in case it’s different to sender’s email)
» track_links Optional
integer
1=click tracking is on (default), 0=click tracking is off
» track_read Optional
integer
1=read tracking is on (default), 0=read tracking is off
» headers Optional
object
Contains email headers, maximum 50. Only headers with “X-” name prefix are accepted, all other are ignored. If our support have approved omitting standard unsubscription block for you, you can also pass List-Unsubscribe, List-Subscribe, List-Help, List-Owner and List-Archive headers.
» attachments Optional
array
Optional array of attachments
»» type Required
string
Attachment type, see MIME. If unsure, use “application/octet-stream”.
»» name Required
string
Attachment name in the format: “name.extension”
»» content Required
string(byte)
File contents in base64.
» inline_attachments Optional
array
Optional array of inline attachments, e.g. for including images in email instead of loading them from external URL.
»» type Required
string
Attachment type, see MIME. If unsure, use “application/octet-stream”.
»» name Required
string
Attachment content id. For example, “name”=“IMAGECID1” should be referenced in HTML like <img src=“cid:IMAGECID1”>
»» content Required
string(byte)
File contents in base64.
» created Required
string(utc-date-time)
Template creation date and time in UTC timezone in format “YYYY-MM-DD hh:mm:ss”
» user_id Required
integer
Unique user identifier.
» project_id Optional
string
Unqiue project identifier, ASCII string up to 36 characters long.
» project_name Optional
string
Project name, unique for user account.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

template-delete

POST https://us1.unione.io/en/transactional/api/v1/template/delete.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"id": "string"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"id" => "string"
];

try {
$response = $client->request('POST','template/delete.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"id": "string"
}
r = requests.post(base_url+'/template/delete.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/template/delete.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/template/delete.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/template/delete.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"id\": \"string\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"id": "string"
};
fetch('https://us1.unione.io/en/transactional/api/v1/template/delete.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/template/delete.json

Deletes a template by id.

Parameters

Name Type Description
id Required
string(uuid)
Template id.

200 Response

{
"status": "success"
}

Response Schema

HTTP Code 200:

Template deleted successfully.

Name Type Description
status Required
string
“success” string

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

Webhook Methods

UniOne lets you recieve notifications about email status changes or spam blocks. You provide an URL and every time a watched event occurs we will notify you by submitting a request with JSON data to this URL.

You can configure the format of webhook calls (JSON or gzipped JSON), which events you want to be notified of, whether or not you let us groups several events in one request, do you want to receive extra details like SMTP answer or recipient’s user agent, etc.

Please note that your webhook handler should be able to process at least 5 parallel requests (but you can configure the maximum number of parallel connections up to 100, which is recommended).

If the URL of your webhook handler is not available (the response is not HTTP 200 OK within 3 seconds timeout), the system will repeat requests each 10 minutes during 24 hours, passing extra parameter retry_count. If there were at least 10 events during last 24 hours and all the webhook requests about these events have failed then we consider webhook handler broken and change it’s status to inactive automatically. A notification about that is sent to an email configured in control panel.

The format of webhook request and details of each event are described here.

webhook-set

POST https://us1.unione.io/en/transactional/api/v1/webhook/set.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"url": "https://yourhost.example.com/unione-webhook",
"status": "active",
"event_format": "json_post",
"delivery_info": 0,
"single_event": 0,
"max_parallel": 10,
"events": {
"spam_block": [
"*"
],
"email_status": [
"delivered",
"opened",
"clicked",
"unsubscribed",
"soft_bounced",
"hard_bounced",
"spam"
]
}
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"url" => "https://yourhost.example.com/unione-webhook",
"status" => "active",
"event_format" => "json_post",
"delivery_info" => 0,
"single_event" => 0,
"max_parallel" => 10,
"events" => [
"spam_block" => [
"*"
],
"email_status" => [
"delivered",
"opened",
"clicked",
"unsubscribed",
"soft_bounced",
"hard_bounced",
"spam"
]
]
];

try {
$response = $client->request('POST','webhook/set.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"url": "https://yourhost.example.com/unione-webhook",
"status": "active",
"event_format": "json_post",
"delivery_info": 0,
"single_event": 0,
"max_parallel": 10,
"events": {
"spam_block": [
"*"
],
"email_status": [
"delivered",
"opened",
"clicked",
"unsubscribed",
"soft_bounced",
"hard_bounced",
"spam"
]
}
}
r = requests.post(base_url+'/webhook/set.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/webhook/set.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/webhook/set.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/webhook/set.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"url\": \"https://yourhost.example.com/unione-webhook\","
+" \"status\": \"active\","
+" \"event_format\": \"json_post\","
+" \"delivery_info\": 0,"
+" \"single_event\": 0,"
+" \"max_parallel\": 10,"
+" \"events\": {"
+" \"spam_block\": ["
+" \"*\""
+" ],"
+" \"email_status\": ["
+" \"delivered\","
+" \"opened\","
+" \"clicked\","
+" \"unsubscribed\","
+" \"soft_bounced\","
+" \"hard_bounced\","
+" \"spam\""
+" ]"
+" }"
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"url": "https://yourhost.example.com/unione-webhook",
"status": "active",
"event_format": "json_post",
"delivery_info": 0,
"single_event": 0,
"max_parallel": 10,
"events": {
"spam_block": [
"*"
],
"email_status": [
"delivered",
"opened",
"clicked",
"unsubscribed",
"soft_bounced",
"hard_bounced",
"spam"
]
}
};
fetch('https://us1.unione.io/en/transactional/api/v1/webhook/set.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/webhook/set.json

Sets or edits a webhook, i.e. an event notification handler.

Parameters

Name Type Description
url Required
string(uri)
URL that will receive the notification when an event occurs. The URL should be unique for a user or a project. Only ASCII characters are supported for now in URL, please convert to Punycode if you need to use non-ASCII characters.
status Optional
string
Webhook status, “active” by default. “disabled” means that webhook has been disabled by the user, “stopped” means that webhook has been stopped by the system after 24h of failed calls (with minimum of 10 distinct events).
event_format Optional
string
Notification format. “json_post”(default) or “json_post_gzip”.
delivery_info Optional
integer
Shall detailed delivery info be returned(1) or not(0). When it’s 1, the information about SMTP response and internal delivery status is returned for “hard_bounced” and “soft_bounced” email statuses; the user agent is returned for “opened” and “clicked” statuses and URL for “clicked” status.
single_event Optional
integer
0=several event notifications can be reported in single webhook call, 1=only single event can be reported in one call (not recommended).
max_parallel Optional
integer
Maximum quantity of permitted parallel queries to your server. The more your server can handle - the better.
events Optional
object
Object containing events to notify of.
» spam_block Optional
array
If present then spam block events will be reported. Should contain single array element with “*” string.
» email_status Optional
array
If present then email status change events will be reported. Contains names of statuses to notify of.

200 Response

{
"status": "success",
"object": {
"id": 0,
"url": "http://example.com",
"status": "active",
"event_format": "json_post",
"delivery_info": 0,
"single_event": 0,
"max_parallel": 10,
"updated_at": "string",
"events": {
"spam_block": [
"*"
],
"email_status": [
"delivered",
"opened",
"clicked",
"unsubscribed",
"soft_bounced",
"hard_bounced",
"spam"
]
}
}
}

Response Schema

HTTP Code 200:

Webhook set successfully.

Name Type Description
status Required
string
“success” string
object Required
object
Object with all the webhook properties.
» id Required
integer
Webhook unique identifier.
» url Required
string(uri)
Webhook URL.
» status Required
string
Webhook status, “active” by default. “disabled” means that webhook has been disabled by the user, “stopped” means that webhook has been stopped by the system after 24h of failed calls (with minimum of 10 distinct events).
» event_format Required
string
Notification format. “json_post”(default) or “json_post_gzip”.
» delivery_info Required
integer
Shall detailed delivery info be returned(1) or not(0). When it’s 1, the information about SMTP response and internal delivery status is returned for “hard_bounced” and “soft_bounced” email statuses; the user agent is returned for “opened” and “clicked” statuses and URL for “clicked” status.
» single_event Required
integer
0=several event notifications can be reported in single webhook call, 1=only single event can be reported in one call (not recommended).
» max_parallel Required
integer
Maximum quantity of permitted parallel queries to your server. The more your server can handle - the better.
» updated_at Optional
string(utc-date-time)
Webhook properties last update date and time in UTC timezone in “YYYY-MM-DD hh:mm:ss” format.
» events Optional
object
Object containing events to notify of.
»» spam_block Optional
array
If present then spam block events will be reported. Should contain single array element with “*” string.
»» email_status Optional
array
If present then email status change events will be reported. Contains names of statuses to notify of.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

callback-format

 

Here you can see description of JSON parameters which will be sent to the URL you provide in webhook/set. Your server should response with 200 OK during 3 seconds or webhook call will be retried later. Read more about webhook concept here.

UniOne generates two types of events that have distinct event_name field and event_data structures:

  1. transactional_email_status - email delivery status change event. You can subscribe to selected statuses only.
  2. transactional_spam_block - event of activating/deactivating a spam block for single or multiple SMTP servers.
See HTTP sample
See HTTP sample
See HTTP sample
See HTTP sample
See HTTP sample
See HTTP sample
POST https://yourhost.example.com/unione-webhook HTTP/1.1
Host: yourhost.example.com
Content-Type: application/json

{
"auth":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"events_by_user":
[
{
"user_id":456,
"project_id":"6432890213745872",
"project_name":"MyProject",
"events":
[
{
"event_name":"transactional_email_status",
"event_data":
{
"job_id":"1a3Q2V-0000OZ-S0",
"metadata":
{
"key1":"val1",
"key2":"val2"
},
"email":"recipient.email@example.com",
"status":"sent",
"event_time":"2015-11-30 15:09:42",
"url":"http://some.url.com",
"delivery_info":
{
"delivery_status": "err_delivery_failed",
"destination_response": "550 Spam rejected",
"user_agent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36",
"ip":"111.111.111.111"
}
}
},
{
"event_name":"transactional_spam_block",
"event_data":
{
"block_time":"YYYY-MM-DD HH:MM:SS",
"block_type":"one_smtp",
"domain":"domain_name",
"SMTP_blocks_count":8,
"domain_status":"blocked"
}
}
]
}
]
}

Parameters

Name Type Description
auth Required
string
MD5-hash of the message body, in which the value “auth” is replaced by api key of the user/project; with this field the recipient of the notification can both authenticate and verify the notification integrity
events_by_user Required
array
Array with only one element, containing events of a user/project.
» user_id Required
integer
Unique user identifier.
» project_id Optional
string
Project identifier, present only if webhook was registered for the project using project API key.
» project_name Optional
string
Project name, present only if webhook was registered for the project using project API key.
» events Required
array
Array of events reported by webhook.
»» event_name Optional
string
Type of event data contained in event_data field, either “transactional_email_status” or “transactional_spam_block”.
»» event_data Optional
object
Object with different event properties depending on “event_name”. Below you can see all the properties, “transactional_email_status”-related first and then “transactional_spam_block”-related.
»»» job_id Optional
string
Job identifier returned earlier by email/send method. Property exists only if event_name=“transactional_email_status”.
»»» metadata Optional
object
Metadata passed in email/send method in recipients.metadata or global_metadata properties. This property exists only if event_name=“transactional_email_status”.
»»» email Optional
string(email)
Recipient’s email. This property exists only if event_name=“transactional_email_status”.
»»» status Optional
string
Email delivery status. This property exists only if event_name=“transactional_email_status”. Possible values are:

sent — the message has been sent, but not delivered yet.
delivered — the message has been delivered. It can be changed to “opened”, “clicked”, “unsubscribed” or “spam”.
opened — the message has been delivered and read. It can be changed to “clicked”, “unsubscribed” or “spam”.
clicked — the message has been delivered, read, and at least one of the links in email has been clicked. It can be changed to “unsubscribed” or “spam”.
unsubscribed — the message has been delivered to the recipient and read, but then the recipient unsubscribed. The status is final.
soft_bounced — temporary delivery failure. UniOne will try to deliver the message during 48 hours. In case of success the status changes to “delivered”, in case of failure to deliver during 48 hours message status changes to “hard_bounced”.
hard_bounced — failed to deliver the message, there will be no delivery attempts. It’s a final status. There are a lot of possible reasons, you can use SMTP response from delivery_info.destination_response field or UniOne internal reason classification from delivery_info.delivery_status field to analyze the reason.
spam — the message has been delivered, but it was reported as spam by the recipient. UniOne can receive and process the spam complaint from several domains, including msn.com, outlook.com, hotmail.com, live.com, ukr.net, yahoo.com, aol.com using FBL.
»»» event_time Optional
string(utc-date-time)
Event date & time in UTC time zone in “YYYY-MM-DD hh:mm:ss” format. This property exists only if event_name=“transactional_email_status”.
»»» url Optional
string(uri)
URL for “read” and “clicked” statuses. This property exists only if event_name=“transactional_email_status”.
»»» delivery_info Optional
object
Object with detailed delivery info.Event date & time in UTC time zone in “YYYY-MM-DD hh:mm:ss” format. This property exists only if webhook has delivery_info proeprty set to 1 and event_name=“transactional_email_status”.
»»»» delivery_status Required
string
UniOne internal detailed delivery status. Some possible values are:

err_user_unknown – email address doesn’t exist;
err_user_inactive – email address isn’t used anymore;
err_mailbox_discarded – email address was active earliear, but now it’s deleted;
err_mailbox_full – mailbox is full;
err_spam_rejected – email was rejected as a spam;
err_too_large – email size is over limit, according to recipient’s server;
err_unsubscribed – email was unsubscribed;
err_unreachable – numerous delivery failures lead to mark this email address as unreachable;
»»»» destination_response Optional
string
SMTP response.
»»»» user_agent Optional
string
User agent of recipient. Present only if detected for “clicked” and “read” statuses.
»»»» ip Optional
string
Recipient’s IP address. Present only if detected for “clicked” and “read” statuses.
»»» block_time Optional
string(utc-date-time)
Spam block date & time in UTC time zone in “YYYY-MM-DD hh:mm:ss” format. This property exists only if event_name=“transactional_spam_block”.
»»» block_type Optional
string
Spam block type, either single or multiple sending SMTP. For single sending SMTP block in common pool UniOne retries several other SMTPs. This property exists only if event_name=“transactional_spam_block”.
»»» domain Optional
string
Domain that blocked sending. This property exists only if event_name=“transactional_spam_block”.
»»» SMTP_blocks_count Optional
integer
Number of sending SMTPs blocked. This property exists only if event_name=“transactional_spam_block”.
»»» domain_status Optional
string
Whether it’s a block or unblock event. This property exists only if event_name=“transactional_spam_block”.

webhook-get

POST https://us1.unione.io/en/transactional/api/v1/webhook/get.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"url": "http://example.com"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"url" => "http://example.com"
];

try {
$response = $client->request('POST','webhook/get.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"url": "http://example.com"
}
r = requests.post(base_url+'/webhook/get.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/webhook/get.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/webhook/get.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/webhook/get.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"url\": \"http://example.com\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"url": "http://example.com"
};
fetch('https://us1.unione.io/en/transactional/api/v1/webhook/get.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/webhook/get.json

Gets properties of a webhook.

Parameters

Name Type Description
url Required
string(uri)
Webhook URL.

200 Response

{
"status": "success",
"object": {
"id": 0,
"url": "http://example.com",
"status": "active",
"event_format": "json_post",
"delivery_info": 0,
"single_event": 0,
"max_parallel": 10,
"updated_at": "string",
"events": {
"spam_block": [
"*"
],
"email_status": [
"delivered",
"opened",
"clicked",
"unsubscribed",
"soft_bounced",
"hard_bounced",
"spam"
]
}
}
}

Response Schema

HTTP Code 200:

Webhook returned successfully.

Name Type Description
status Required
string
“success” string
object Required
object
Object with all the webhook properties.
» id Required
integer
Webhook unique identifier.
» url Required
string(uri)
Webhook URL.
» status Required
string
Webhook status, “active” by default. “disabled” means that webhook has been disabled by the user, “stopped” means that webhook has been stopped by the system after 24h of failed calls (with minimum of 10 distinct events).
» event_format Required
string
Notification format. “json_post”(default) or “json_post_gzip”.
» delivery_info Required
integer
Shall detailed delivery info be returned(1) or not(0). When it’s 1, the information about SMTP response and internal delivery status is returned for “hard_bounced” and “soft_bounced” email statuses; the user agent is returned for “opened” and “clicked” statuses and URL for “clicked” status.
» single_event Required
integer
0=several event notifications can be reported in single webhook call, 1=only single event can be reported in one call (not recommended).
» max_parallel Required
integer
Maximum quantity of permitted parallel queries to your server. The more your server can handle - the better.
» updated_at Optional
string(utc-date-time)
Webhook properties last update date and time in UTC timezone in “YYYY-MM-DD hh:mm:ss” format.
» events Optional
object
Object containing events to notify of.
»» spam_block Optional
array
If present then spam block events will be reported. Should contain single array element with “*” string.
»» email_status Optional
array
If present then email status change events will be reported. Contains names of statuses to notify of.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

webhook-list

POST https://us1.unione.io/en/transactional/api/v1/webhook/list.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"limit": 0,
"offset": 0
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"limit" => 0,
"offset" => 0
];

try {
$response = $client->request('POST','webhook/list.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"limit": 0,
"offset": 0
}
r = requests.post(base_url+'/webhook/list.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/webhook/list.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/webhook/list.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/webhook/list.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"limit\": 0,"
+" \"offset\": 0"
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"limit": 0,
"offset": 0
};
fetch('https://us1.unione.io/en/transactional/api/v1/webhook/list.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/webhook/list.json

List all or some webhooks (event notification handlers) of a user or a project.

Parameters

Name Type Description
limit Optional
integer
Limits the number of webhooks returned. 50 is recommended.
offset Optional
integer
Index of the first webhook in the list, starting with 0.

200 Response

{
"status": "success",
"objects": [
{
"id": 0,
"url": "http://example.com",
"status": "active",
"event_format": "json_post",
"delivery_info": 0,
"single_event": 0,
"max_parallel": 10,
"updated_at": "string",
"events": {
"spam_block": [
"*"
],
"email_status": [
"delivered",
"opened",
"clicked",
"unsubscribed",
"soft_bounced",
"hard_bounced",
"spam"
]
}
}
]
}

Response Schema

HTTP Code 200:

Webhook list returned successfully.

Name Type Description
status Required
string
“success” string
objects Optional
array
Array of webhooks objects.
» id Required
integer
Webhook unique identifier.
» url Required
string(uri)
Webhook URL.
» status Required
string
Webhook status, “active” by default. “disabled” means that webhook has been disabled by the user, “stopped” means that webhook has been stopped by the system after 24h of failed calls (with minimum of 10 distinct events).
» event_format Required
string
Notification format. “json_post”(default) or “json_post_gzip”.
» delivery_info Required
integer
Shall detailed delivery info be returned(1) or not(0). When it’s 1, the information about SMTP response and internal delivery status is returned for “hard_bounced” and “soft_bounced” email statuses; the user agent is returned for “opened” and “clicked” statuses and URL for “clicked” status.
» single_event Required
integer
0=several event notifications can be reported in single webhook call, 1=only single event can be reported in one call (not recommended).
» max_parallel Required
integer
Maximum quantity of permitted parallel queries to your server. The more your server can handle - the better.
» updated_at Optional
string(utc-date-time)
Webhook properties last update date and time in UTC timezone in “YYYY-MM-DD hh:mm:ss” format.
» events Optional
object
Object containing events to notify of.
»» spam_block Optional
array
If present then spam block events will be reported. Should contain single array element with “*” string.
»» email_status Optional
array
If present then email status change events will be reported. Contains names of statuses to notify of.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

webhook-delete

POST https://us1.unione.io/en/transactional/api/v1/webhook/delete.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"url": "http://example.com"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"url" => "http://example.com"
];

try {
$response = $client->request('POST','webhook/delete.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"url": "http://example.com"
}
r = requests.post(base_url+'/webhook/delete.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/webhook/delete.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/webhook/delete.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/webhook/delete.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"url\": \"http://example.com\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"url": "http://example.com"
};
fetch('https://us1.unione.io/en/transactional/api/v1/webhook/delete.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/webhook/delete.json

Deletes an event notification handler

You can also temporarily deactivate webhook without deleting it by setting it’s status to “disabled” in webhook/set method.

Parameters

Name Type Description
url Required
string(uri)
Webhook URL.

200 Response

{
"status": "success"
}

Response Schema

HTTP Code 200:

Webhook deleted successfully.

Name Type Description
status Required
string
“success” string

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

Unsubscribed Methods

Methods dealing with unsubscribes. Note that you can’t resubscribe an unsubcribed recipient using WebAPI, but you can send him an email with subscription link using email/subscribe method.

unsubscribed-set

POST https://us1.unione.io/en/transactional/api/v1/unsubscribed/set.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"address": "user@example.com"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"address" => "user@example.com"
];

try {
$response = $client->request('POST','unsubscribed/set.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"address": "user@example.com"
}
r = requests.post(base_url+'/unsubscribed/set.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/unsubscribed/set.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/unsubscribed/set.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/unsubscribed/set.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"address\": \"user@example.com\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"address": "user@example.com"
};
fetch('https://us1.unione.io/en/transactional/api/v1/unsubscribed/set.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/unsubscribed/set.json

Registers a new unsubscribed email.

After registering an email as unsubscribed all future attempts to send a message to this email will be rejected. Please note that there’s no way to remove an email from unsubscribed thru the API. But you can send an email with a link to resubscribe using email/subscribe method or remove “unsubscribed” status manually on Email Search page in control panel (but only a limited number of unsubscribed email per day can be removed).

Parameters

Name Type Description
address Required
string(email)
Email to be unsubscribed.

200 Response

{
"status": "success",
"address": "user@example.com",
"message": "unsubscribed"
}

Response Schema

HTTP Code 200:

Email has been unsubscribed successfully.

Name Type Description
status Required
string
“success” string
address Required
string(email)
The unsubscribed email.
message Required
string
Unsubscription process details:
  • “unsubscribed” if email has just been unsubscribed,
  • “was inactive” if it was inactive due some reason,
  • “was unsubscribed” if it already was unsubscribed before the call,
  • “added and unsubscribed” if it’s a new email without status history and it was added and then unsubscribed immediately.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

unsubscribed-check

POST https://us1.unione.io/en/transactional/api/v1/unsubscribed/check.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"address": "user@example.com"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"address" => "user@example.com"
];

try {
$response = $client->request('POST','unsubscribed/check.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"address": "user@example.com"
}
r = requests.post(base_url+'/unsubscribed/check.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/unsubscribed/check.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/unsubscribed/check.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/unsubscribed/check.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"address\": \"user@example.com\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"address": "user@example.com"
};
fetch('https://us1.unione.io/en/transactional/api/v1/unsubscribed/check.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/unsubscribed/check.json

Checks if an email is unsubscribed.

Parameters

Name Type Description
address Required
string(email)
Email to check.

200 Response

{
"status": "success",
"address": "user@example.com",
"is_unsubscribed": true
}

Response Schema

HTTP Code 200:

Email unsubscription status successfully returned.

Name Type Description
status Required
string
“success” string
address Required
string(email)
Email that was checked.
is_unsubscribed Required
boolean
true if unsubscribed, false if not.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

unsubscribed-list

POST https://us1.unione.io/en/transactional/api/v1/unsubscribed/list.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"date_from": "2020-10-14"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"date_from" => "2020-10-14"
];

try {
$response = $client->request('POST','unsubscribed/list.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"date_from": "2020-10-14"
}
r = requests.post(base_url+'/unsubscribed/list.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/unsubscribed/list.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/unsubscribed/list.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/unsubscribed/list.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"date_from\": \"2020-10-14\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"date_from": "2020-10-14"
};
fetch('https://us1.unione.io/en/transactional/api/v1/unsubscribed/list.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/unsubscribed/list.json

Returns a list of all unsubscribed emails since provided date.

Parameters

Name Type Description
date_from Optional
string(utc-date)
Date in the format YYYY-MM-DD to get all unsubscribed emails from the “date_from” to the present day. If the parameter is not specified, the default period is today (from 00:00 UTC).

200 Response

{
"status": "success",
"unsubscribed": [
{
"address": "user@example.com",
"unsubscribed_on": "2020-10-15 22:14:59"
}
]
}

Response Schema

HTTP Code 200:

The list of unsubscribed emails returned successfully.

Name Type Description
status Required
string
“success” string
unsubscribed Required
array
Array of object describing unsubscribed emails.
» address Optional
string(email)
Unsubscribed email.
» unsubscribed_on Optional
string(utc-date-time)
Date and time when a recipient unsubscribed, in UTC timezone and “YYYY-MM-DD hh:mm:ss” format.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

Domain Methods

You can use these methods to setup sender domains and check their statuses. They might be useful in case you want to automate adding domains for your own clients.

To add new sender domain thru API you should take following steps:

domain-get-dns-records

POST https://us1.unione.io/en/transactional/api/v1/domain/get-dns-records.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"domain": "example.com"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"domain" => "example.com"
];

try {
$response = $client->request('POST','domain/get-dns-records.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"domain": "example.com"
}
r = requests.post(base_url+'/domain/get-dns-records.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/domain/get-dns-records.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/domain/get-dns-records.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/domain/get-dns-records.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"domain\": \"example.com\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"domain": "example.com"
};
fetch('https://us1.unione.io/en/transactional/api/v1/domain/get-dns-records.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/domain/get-dns-records.json

Returns info on domain DNS setup for using with UniOne.

In order to send emails you have to confirm that you own the domain that you are going to send emails from and setup DKIM signature for the domain. This method allows you to register your domain in UniOne and generate verification record and DKIM key, or return previously generated ones if domain is already registered. You should add then DNS records like this to all of the domains you want to confirm:

@ IN TXT "unione-validate-hash=483bb362ebdbeedd755cfb1d4d661"
us._domainkey IN TXT "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"
@ IN TXT "v=spf1 include:spf.unione.io ~all"

Syntax requirements of different DNS providers may differ:

Parameters

Name Type Description
domain Required
string
Domain to get DNS records for.

200 Response

{
"status": "success",
"domain": "example.com",
"verification-record": "unione-validate-hash=483bb362ebdbeedd755cfb1d4d661",
"dkim": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7"
}

Response Schema

HTTP Code 200:

Domain DNS info returned successfully.

Name Type Description
status Required
string
“success” string
domain Required
string
Domain to get DNS records for.
verification-record Required
string
Record to be added “as is” to verify ownership of this domain.
dkim Required
string
DKIM signature for the domain. This property contains only the key part, you should prepend it with “k=rsa, p=” part for the record to be valid (see example).

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

domain-validate-verification-record

POST https://us1.unione.io/en/transactional/api/v1/domain/validate-verification-record.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"domain": "example.com"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"domain" => "example.com"
];

try {
$response = $client->request('POST','domain/validate-verification-record.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"domain": "example.com"
}
r = requests.post(base_url+'/domain/validate-verification-record.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/domain/validate-verification-record.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/domain/validate-verification-record.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/domain/validate-verification-record.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"domain\": \"example.com\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"domain": "example.com"
};
fetch('https://us1.unione.io/en/transactional/api/v1/domain/validate-verification-record.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/domain/validate-verification-record.json

Triggers verification record validation for domain.

If you get 200 OK then it means the validation process started succesfully, but it doesn’t mean the verification record is valid. You should check later verification-record.status field returned by domain/list method to get the result. Please read more here.

Parameters

Name Type Description
domain Required
string
Domain to validate verification record for.

200 Response

{
"status": "success",
"message": "Record updated"
}

Response Schema

HTTP Code 200:

Verification record is valid.

Name Type Description
status Required
string
“success” string
message Required
string
Debug message.

HTTP Code default:

Error occured or record is invalid.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

domain-validate-dkim

POST https://us1.unione.io/en/transactional/api/v1/domain/validate-dkim.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"domain": "example.com"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"domain" => "example.com"
];

try {
$response = $client->request('POST','domain/validate-dkim.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"domain": "example.com"
}
r = requests.post(base_url+'/domain/validate-dkim.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/domain/validate-dkim.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/domain/validate-dkim.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/domain/validate-dkim.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"domain\": \"example.com\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"domain": "example.com"
};
fetch('https://us1.unione.io/en/transactional/api/v1/domain/validate-dkim.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/domain/validate-dkim.json

Validates DKIM record for domain.

If you get 200 OK then it means the validation process started succesfully, but it doesn’t mean the DKIM record is valid. You should check later dkim.status field returned by domain/list method to get the result. Please read more here.

Parameters

Name Type Description
domain Required
string
Domain to validate DKIM record for.

200 Response

{
"status": "success",
"message": "Record updated"
}

Response Schema

HTTP Code 200:

DKIM record validation has started successfully.

Name Type Description
status Required
string
“success” string
message Required
string
Debug message.

HTTP Code default:

Error occured or record is invalid.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

domain-list

POST https://us1.unione.io/en/transactional/api/v1/domain/list.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"domain": "example.com",
"limit": 50,
"offset": 0
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"domain" => "example.com",
"limit" => 50,
"offset" => 0
];

try {
$response = $client->request('POST','domain/list.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"domain": "example.com",
"limit": 50,
"offset": 0
}
r = requests.post(base_url+'/domain/list.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/domain/list.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/domain/list.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/domain/list.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"domain\": \"example.com\","
+" \"limit\": 50,"
+" \"offset\": 0"
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"domain": "example.com",
"limit": 50,
"offset": 0
};
fetch('https://us1.unione.io/en/transactional/api/v1/domain/list.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/domain/list.json

Returns a list of all registered domains for user or project, together with statuses of last validations.

Returns last status of ownership validation and DKIM validation for each domain. Read more here.

Parameters

Name Type Description
domain Optional
string
Optional domain name if you want to get the status of single domain only.
limit Optional
integer
Limits the number of domains returned. Default is 50.
offset Optional
integer
Index of the first domain in the list, starting with 0.

200 Response

{
"status": "success",
"domains": [
{
"domain": "example.com",
"verification-record": {
"value": "unione-validate-hash=483bb362ebdbeedd755cfb1d4d661",
"status": "confirmed"
},
"dkim": {
"key": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7",
"status": "active"
}
}
]
}

Response Schema

HTTP Code 200:

The list of the registered domains returned successfully.

Name Type Description
status Required
string
“success” string
domains Required
array
Array of objects describing domains.
» domain Required
string
Domain name.
» verification-record Required
object
Object describing verification record value and status.
»» value Optional
string
Record to be added “as is” to verify ownership of this domain.
»» status Optional
string
Only domains with “confirmed” verification record are allowed as sender domains.
» dkim Required
object
Object describing DKIM record value and status.
»» key Optional
string
DKIM signature for the domain. This property contains only the key part, you should prepend it with “k=rsa, p=” part for the record to be valid (see domain/get-dns-records).
»» status Optional
string
Only domains with “active” DKIM record are allowed as sender domains.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

Project Methods

Projects allow you to group several independent domains, webhooks, templates, and unsubscription lists together. It’s very useful if you have your own clients and manage their data from a single UniOne account. Each project receives its own API key, and all API calls with that API key only deal with the data of that project. This way, you can assign a separate project for each client and be sure that they won’t conflict; e.g. unsubscribing from one project won’t affect another.

Projects methods are disabled by default due to antispam measures. To enable them, contact support.

Please note that sending domains are confirmed and used on per-project basis by default. But it’s possible to allow projects to send emails from domains confirmed for main account - just ask support to enable it.

project-create

POST https://us1.unione.io/en/transactional/api/v1/project/create.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"project": {
"name": "Project 1A",
"send_enabled": true,
"custom_unsubscribe_url_enabled": true
}
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"project" => [
"name" => "Project 1A",
"send_enabled" => true,
"custom_unsubscribe_url_enabled" => true
]
];

try {
$response = $client->request('POST','project/create.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"project": {
"name": "Project 1A",
"send_enabled": true,
"custom_unsubscribe_url_enabled": true
}
}
r = requests.post(base_url+'/project/create.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/project/create.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/project/create.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/project/create.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"project\": {"
+" \"name\": \"Project 1A\","
+" \"send_enabled\": true,"
+" \"custom_unsubscribe_url_enabled\": true"
+" }"
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"project": {
"name": "Project 1A",
"send_enabled": true,
"custom_unsubscribe_url_enabled": true
}
};
fetch('https://us1.unione.io/en/transactional/api/v1/project/create.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/project/create.json

Creates a new project.

Parameters

Name Type Description
project Required
object
Object with project properties.
» name Required
string
Project name, unique for user account.
» send_enabled Optional
boolean
Whether email sending is enabled for this project or not.
» custom_unsubscribe_url_enabled Optional
boolean
If it’s false then UniOne adds default unsubdscribe footer to each email sent with API key of the project. If it’s true then appending default unsubscribe footer for this project is avoided and sending with custom unsubscribe url or even without unsubscribe url is permitted for the project. Please note that custom_unsubscribe_url_enabled=true is available only if removing unsubscribe link is approved for the user account by support. More on this here. When custom_unsubscribe_url_enabled is skipped on creating a project, it’s value is taken from user

200 Response

{
"status": "success",
"project_id": "6123462132634",
"project_api_key": "string"
}

Response Schema

HTTP Code 200:

Project created successfully.

Name Type Description
status Required
string
“success” string
project_id Required
string
Unqiue project identifier, ASCII string up to 36 characters long.
project_api_key Required
string
API key of the project. You can use it instead of the user API key parameter in all methods except project/* methods.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

project-update

POST https://us1.unione.io/en/transactional/api/v1/project/update.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"project_id": "string",
"project_api_key": "string",
"project": {
"name": "Project 1A",
"send_enabled": true,
"custom_unsubscribe_url_enabled": true
}
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"project_id" => "string",
"project_api_key" => "string",
"project" => [
"name" => "Project 1A",
"send_enabled" => true,
"custom_unsubscribe_url_enabled" => true
]
];

try {
$response = $client->request('POST','project/update.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"project_id": "string",
"project_api_key": "string",
"project": {
"name": "Project 1A",
"send_enabled": true,
"custom_unsubscribe_url_enabled": true
}
}
r = requests.post(base_url+'/project/update.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/project/update.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/project/update.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/project/update.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"project_id\": \"string\","
+" \"project_api_key\": \"string\","
+" \"project\": {"
+" \"name\": \"Project 1A\","
+" \"send_enabled\": true,"
+" \"custom_unsubscribe_url_enabled\": true"
+" }"
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"project_id": "string",
"project_api_key": "string",
"project": {
"name": "Project 1A",
"send_enabled": true,
"custom_unsubscribe_url_enabled": true
}
};
fetch('https://us1.unione.io/en/transactional/api/v1/project/update.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/project/update.json

Updates a project.

Parameters

Name Type Description
project_id Optional
string
Unique project identifier. You should identify project to update either with project_id or with project_api_key field. But we recommend usage of project_id as a more secure option.
project_api_key Optional
string
Optiona project API key. You should identify project to update either with project_id or with project_api_key field. But we recommend usage of project_id as a more secure option.
project Required
object
Object with project properties.
» name Required
string
Project name, unique for user account.
» send_enabled Optional
boolean
Whether email sending is enabled for this project or not.
» custom_unsubscribe_url_enabled Optional
boolean
If it’s false then UniOne adds default unsubdscribe footer to each email sent with API key of the project. If it’s true then appending default unsubscribe footer for this project is avoided and sending with custom unsubscribe url or even without unsubscribe url is permitted for the project. Please note that custom_unsubscribe_url_enabled=true is available only if removing unsubscribe link is approved for the user account by support. More on this here. When custom_unsubscribe_url_enabled is skipped on creating a project, it’s value is taken from user

200 Response

{
"status": "success",
"project_api_key": "string"
}

Response Schema

HTTP Code 200:

Project updated successfully.

Name Type Description
status Required
string
“success” string
project_api_key Optional
string
API key of the project. Returned only if the project to update was identified by project_api_key. Not returned in case of updating by project_id.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

project-list

POST https://us1.unione.io/en/transactional/api/v1/project/list.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"project_id": "string",
"project_api_key": "string"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"project_id" => "string",
"project_api_key" => "string"
];

try {
$response = $client->request('POST','project/list.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"project_id": "string",
"project_api_key": "string"
}
r = requests.post(base_url+'/project/list.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/project/list.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/project/list.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/project/list.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"project_id\": \"string\","
+" \"project_api_key\": \"string\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"project_id": "string",
"project_api_key": "string"
};
fetch('https://us1.unione.io/en/transactional/api/v1/project/list.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/project/list.json

Lists projects.

Parameters

Name Type Description
project_id Optional
string
Optional possibility to specify project_id to include only this project to list.
project_api_key Optional
string
Optional possibility to specify project_api_key to include only this project to list.

200 Response

{
"status": "success",
"projects": [
{
"id": "6123462132634",
"api_key": "string",
"name": "Project 1A",
"reg_time": "2020-12-28 17:15:45",
"send_enabled": true,
"custom_unsubscribe_url_enabled": true
}
]
}

Response Schema

HTTP Code 200:

Projects returned successfully.

Name Type Description
status Optional
string
“success” string
projects Optional
array
Array of objects where each object represents one project.
» id Required
string
Unqiue project identifier, ASCII string up to 36 characters long.
» api_key Required
string
API key of the project. You can use it instead of the user API key parameter in all methods except project/* methods.
» name Optional
string
Project name, unique for user account.
» reg_time Required
string(utc-date-time)
Date and time of project creation in UTC timezone in “YYYY-MM-DD hh:mm:ss” format.
» send_enabled Optional
boolean
Whether email sending is enabled for this project or not.
» custom_unsubscribe_url_enabled Optional
boolean
If it’s false then UniOne adds default unsubdscribe footer to each email sent with API key of the project. If it’s true then appending default unsubscribe footer for this project is avoided and sending with custom unsubscribe url or even without unsubscribe url is permitted for the project. Please note that custom_unsubscribe_url_enabled=true is available only if removing unsubscribe link is approved for the user account by support. More on this here. When custom_unsubscribe_url_enabled is skipped on creating a project, it’s value is taken from user

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

project-delete

POST https://us1.unione.io/en/transactional/api/v1/project/delete.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{
"project_id": "string",
"project_api_key": "string"
}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [
"project_id" => "string",
"project_api_key" => "string"
];

try {
$response = $client->request('POST','project/delete.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {
"project_id": "string",
"project_api_key": "string"
}
r = requests.post(base_url+'/project/delete.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/project/delete.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/project/delete.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/project/delete.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{"
+" \"project_id\": \"string\","
+" \"project_api_key\": \"string\""
+"}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {
"project_id": "string",
"project_api_key": "string"
};
fetch('https://us1.unione.io/en/transactional/api/v1/project/delete.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/project/delete.json

Deletes a project.

The project will be moved to the “trash bin” before being permanently deleted. You can restore the project by contacting support.

Parameters

Name Type Description
project_id Optional
string
Unique project identifier. You should identify project to delete either with project_id or with project_api_key field. We recommend usage of project_id as a more secure option.
project_api_key Optional
string
Optional project API key. You should identify project to delete either with project_id or with project_api_key field. We recommend usage of project_id as a more secure option.

200 Response

{
"status": "success"
}

Response Schema

HTTP Code 200:

Project deleted successfully.

Name Type Description
status Required
string
“success” string

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

System Methods

System operations.

system-info

POST https://us1.unione.io/en/transactional/api/v1/system/info.json HTTP/1.1
Host: us1.unione.io
Content-Type: application/json
Accept: application/json

{}
<?php

require 'vendor/autoload.php';

$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY',
);

$client = new \GuzzleHttp\Client([
'base_uri' => 'https://us1.unione.io/en/transactional/api/v1/'
]);

$request_body = [];

try {
$response = $client->request('POST','system/info.json', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}

// ...
import requests

base_url = 'https://us1.unione.io/en/transactional/api/v1'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-API-KEY': 'API_KEY'
}

request_body = {}
r = requests.post(base_url+'/system/info.json', json=request_body, headers=headers)
r.raise_for_status() # throw an exception in case of error
print(r.json())
require 'rest-client'
require 'json'

headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-API-KEY' => 'API_KEY'
}

result = RestClient.post 'https://us1.unione.io/en/transactional/api/v1/system/info.json',
params: {
}, headers: headers

p JSON.parse(result)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://us1.unione.io/en/transactional/api/v1/system/info.json";


await PostAsync(null, url);

}

/// Performs a POST Request
public async Task PostAsync(undefined content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(undefined content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
URL obj = new URL("https://us1.unione.io/en/transactional/api/v1/system/info.json");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("X-API-KEY", "API_KEY");
con.setDoOutput(true);
String requestBody = "{}";

try (OutputStream out = con.getOutputStream()) {
out.write(requestBody.getBytes());
out.flush();
}
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(responseCode);
System.out.println(response.toString());
const fetch = require('node-fetch');
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-API-KEY':'API_KEY'
};

const inputBody = {};
fetch('https://us1.unione.io/en/transactional/api/v1/system/info.json',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});

POST /en/transactional/api/v1/system/info.json

Gets user or project info by API key.

200 Response

{
"status": "success",
"user_id": 11344,
"email": "user@example.com",
"project_id": "6123462132634",
"project_name": "Project 1A",
"accounting": {
"period_start": "2016-08-29 09:12:33",
"period_end": "2016-09-29 09:12:33",
"emails_included": 0,
"emails_sent": 0
}
}

Response Schema

HTTP Code 200:

User or project info successfully returned.

Name Type Description
status Required
string
“success” string
user_id Required
integer
Unique user identifier.
email Required
string(email)
Email of the user.
project_id Optional
string
Unqiue project identifier, ASCII string up to 36 characters long. Present only if the API key used for request is the project API key.
project_name Optional
string
Project name, unique for user account. Present only if the API key used for request is the project API key.
accounting Optional
object
Object with accounting period properties. Present only if the API key used for request is the user API key.
» period_start Required
string(utc-date-time)
Date and time of accounting period start in UTC in “YYYY-MM-DD hh:mm:ss” format.
» period_end Required
string(utc-date-time)
Date and time of accounting period end in UTC in “YYYY-MM-DD hh:mm:ss” format.
» emails_included Required
integer(int64)
Number of emails included into accounting period.
» emails_sent Required
integer(int64)
Number of emails sent during accounting period. Can be bigger than emails_included in case of overage.

HTTP Code default:

Error occured.

Name Type Description
status Required
string
“error” string
message Required
string
Human-readable error message in English.
code Required
integer
API Error code.

API Errors

HTTP/1.1 500 Internal Server Error
Content-Length: 90
Content-Type: application/json
Connection: Closed

{
"status": "error",
"code": 150,
"message": "Аn unknown internal error occurred"
}

When method call fails with HTTP code other than 200, usually a JSON object is returned also with more details:

Field Type Description
status string Always contains “error” string.
code integer API error code (don’t confuse with HTTP code)
message string Human-readable error message in English.

Below you will find a list of almost all API error codes.

HTTP Code API Code Meaning and how to fix
401 101 API key is not passed or empty
Make sure you have passed correct X-API-KEY header or “api_key” JSON parameter.
401 102 Invalid key ‘$apiKey’
Use correct user API-key or project API key.
403 105 API is turned OFF
You can turn API on here.
403 106 User is inactive
To solve this problem, contact support.
400 111 JSON parsing error
Check your JSON request syntax.
403 114 The user has not been found.
Please send the request to the host you have been registered at, us1.unione.io or eu1.unione.io.
400 115 No DNS records found.
Use domain name with DNS records. Maybe domain is misspelled?
400 118 No DNS TXT records found
Add a DNS verification record to your domain with values returned by domain/get-dns-records.
500 120 Internal DKIM validation error
Please contact support.
400 121 Timeout searching domain.
DNS request has timed out. Please make sure your DNS provider is online and try again later.
400 122 DKIM record not found (almost the same as 120)
Please add to your domain a DKIM record with key returned by domain/get-dns-records method.
400 123 DKIM record malformed.
You should properly setup DKIM for your domain.
400 124 DKIM record does not match expected.
Seems like you have changed the record. While it’s technically correct, it doesn’t match the one we expect. You should use DKIM key returned by domain/get-dns-records method.
400 129 Unknown DKIM validation error with reason distinct to the ones from 120-124 errors.
Please check that you have correctly added a DKIM record with key returned by domain/get-dns-records method and try again. Please contact support if the error still occurs.
400 130 The domain is not allowed according to Registry policy
Please use another domain.
500 150 Аn unknown internal error occurred.
Unknown error occurred. Please try again later or contact support.
400 201 The message body is missing
Check that your message body is being passed properly.
400 202 Sender email is missing
Enter the sender email.
400 203 Email subject is missing
Enter the subject.
400 204 Email recipients are passed improperly
Make sure that the recipient’s list is passed as an array where each recipient is an array with obligatory “email” parameter.
400 205 Invalid sender email
Make sure the parameter is passed properly.
400 206 Sender email is not verified
To avoid this error please use an email on a verified domain.
400 207 MIME file type is incorrect
Check the file and the file type again.
400 208 Too many recipients
Reduce the number of recipients.
400 209 The attached file names are duplicated
Rename files with the same names.
400 210 Inline attachment names are duplicated
Rename files with the same names.
400 211 The attached file name is missing
Specify the name of the attached file.
400 212 Recipients passed improperly (“substitutions” array is not set)
The possible maximum substitutions number has been exceeded or substitutions have incorrect filetype (string/integer is allowed).
403 213 The user is trying to use the custom backend domain but it’s not allowed for that user
Try contacting support.
403 215 The user is not allowed to send
Try contacting support.
400 216 Recipients passed improperly
“Metadata” value should be a string or integer. Array for “metadata” key is expected.
400 217 Too many metadata fields passed
Maximum 10 metadata fields allowed.
400 218 Recipients passed improperly
Metadata key length should be less than 64.
400 219 Recipients passed improperly
Metadata value length should less than 1024.
400 220 The value in template_engine differs from simple/velocity
Check the value passed in the parameter “template_engine”
400 221 Thetag does not exist in the request or is invalid
Add the html <body> tag inside the <html> tag. The <body> tag is required to display HTML content.
400 222 Html part is too long
The HTML size should be less than 5 Mb.
400 223 The body is missing in the attachments “content” or the void is transferred
Add the “content” and specify a value for it.
403 224 Header ‘List-Unsubscribe’ is not allowed
You should avoid passing List-Unsubscribe header or ask support to enable “allow_skip_unsubscribe” option for you if you want to manage unsubscriptions on your side.
400 301 Event format is not supported
Required event format - json_post.
400 303 Events list contains an unsupported value or the event is not supported
Verify that the event list is entered correctly.
400 304 Webhook with the specified URL has not been found
Make sure the URL is passed correctly.
400 305 URL is not passed
Make sure the URL is passed correctly.
400 306 Events list is empty or missing
Verify that there is a list of events in the request.
400 309 The value of the parameter “max_parallel” is out of the valid range
Use a valid value of 5 to 100.
400 310 The specified value of the parameter “max_parallel” is not an integer
Use a valid value of 5 to 100.
403 403 Access denied. Not enough rights to use project API
Request support to turn on access to project API.
400 601 Template has not been found
Check the passed template id.
400 602 The template name is missing
Check the passed template name.
400 603 Template name passed in the request already belongs to another template
Use another name for this template.
400 604 Maximum number of templates has been reached
Delete already created templates to create new ones. The number of templates is limited to 10000.
403 901 Sending is blocked because limit is reached.
Each user has a maximum daily limit for sending to prevent abuse. This limit increases automatically in case of good delivery and is reset each night. You can smoothly increase amount of daily sending or you can conact support and ask for manual limit increase.
403 902 Sending limit for free tariff is reached.
Wait till next day or switch to paid tariff.
403 903 On free tariff you can send only to your own domains with confirmed verification record.
Please confirm ownership of all domains you want to send emails to or switch tariff to the paid one.
403 904 Insufficient funds. Credit card transaction failure.
Please try another card or contact support to resolve the situation.
403 905 You have reached the limit of emails included in your subscription plan.
Usually tariff allows paid overage. In this case it’s prohibited, possibly due to unpaid invoice. Please check that all invoices are paid or contact support to solve the problem.
500 908 Internal error, project owner not found
Please contact support.
400 1000 Missing recipient address
Specify the recipient address.
400 1001 Invalid recipient address value
Please enter a valid recipient address.
400 1002 Missing sender address
Specify the sender address.
400 1003 Sender address not verified
Verify the sender domain address.
400 1004 Invalid sender address value
Please enter a valid sender address.
400 1005 Sender name is too long
The sender name must be shorter. Please correct this value.
400 1100 Missing domain name
Specify the domain to be verified.
400 1101 Invalid domain value
Please enter a valid domain value.
400 1200 Missing domain name
Specify the domain for validating.
400 1201 Invalid domain value
Please enter a valid domain value.
400 1202 Domain is not registered in UniOne
Make a domain/get-dns-records method call.
400 1301 Invalid domain value
Specify the domain to be verified.
400 1302 Invalid limit value
The value of limit must be an integer in the range of 1 - 100.
400 1303 Invalid offset value
The value of offset must be greater than or equal to 0.
400 1304 Invalid offset value type
The value of offset must be an integer.
400 1305 Invalid limit value type
The value of limit must be an integer.
400 1400 Missing domain name
Specify the domain for validating.
400 1401 Invalid or non-existent domain
Either you have mistyped the domain name and should correct it or DNS changes have not yet propagated through DNS and you should wait a couple of hours and try again. There should be A, AAAA or MX record for domain.
400 1402 Domain is not registered in UniOne
Please call domain/get-dns-records method for domain to be registered.
400 1506 Error in ‘headers’ field. This value should have object type.
Please check your JSON and use object for “headers” field, not array or string or whatever.
400 1507 Error in ‘headers’ field. This container should contain 50 elements or less.
Please limit headers to no more than 50 elements.
400 1601, 1701 Error in the ‘project’ field. Project section is absent
Correct JSON structure.
400 1602, 1702 Error in the ‘name’ field. This value should not be blank
Use non-blank name.
400 1603, 1703 Error in the ‘name’ field. It should have ‘string’ type
Use string type for ‘name’ parameter.
400 1604, 1704 Error in the ‘name’ field. This value is too long. It should have 255 characters or less
Use shorter name.
400 1605, 1705 Error in the ‘name’ field. Project with such a name already exists
Use unique project name or delete existing project first.
400 1606 Error in the ‘send_enabled’ field. This value should be of type bool
Set parameter value to true or false only.
400 1607 Error in ‘custom_unsubscribe_url_enabled’ field. This value should be of type bool
Set parameter value to true or false only.
400 1706 Error in ‘project_api_key’ field. One of the two properties [’project_api_key’ or ‘project_id’] is required.
Don’t forget to send either project_id or project_api_key.
400 1707, 1802 Error in the ‘project_api_key’ field. Project not found
Use correct project_api_key. You can get a list of projects with their keys with project/list method.
400 1708 Error in the ‘project_api_key’ field. The value should have a string type
Use string type for ‘project_api_key’.
400 1709 Error in the ‘send_enabled’ field. The value should have a bool type
Set parameter value to true or false only.
400 1710 Error in ‘custom_unsubscribe_url_enabled’ field. The value should have a bool type
Set parameter value to true or false only.
400 1712, 1805, 1905 Error in ‘project_id’ field. This value should be of type string.
Please use string type for project_id field.
400 1713, 1804 Error in ‘project_api_key’ field. One of the two properties [‘project_api_key’ or ‘project_id’] must be empty
Please pass only one of the two parameters: either project_id or project_api_key, not both.
400 1714, 1806 Error in ‘project_id’ field. Project with ID:’NNNN’ not exists.
Project id is invalid. Maybe it was deleted or never existed?
400 1715, 1807 Error in ‘project_id’ field. This value is not valid.
Please check that you pass the project_id you have received by calling project/create method.
400 1801 Error in ‘project_api_key’ field. One of the two properties [’project_api_key’ or ‘project_id’] is required
Don’t forget to send either project_id or project_api_key.
400 1803, 1902 Error in the ‘project_api_key’ field. The value should have a string type
Use string type for ‘project_api_key’.
400 1901 Error in the ‘project_api_key’ field. Project not found
Use correct project_api_key or leave it blank to get list of all projects with their keys.
400 1904 Error in ‘project_id’ field. This value is not valid. The value should contain digits only.
Use correct numbers-only format for ‘project_id’.
400 2400 Error in ‘editor_type’ field. Wrong editor_type value. Use ‘html’.
You can only create ‘html’ templates thru API. Use ‘html’ for ‘editor_type’ field.
400 2401 Error in ‘editor_type’ field. This template was created in visual editor.
Pass ‘visual’ in ‘editor_type’ field.
400 2402 Error in ‘editor_type’ field. This value should not be blank.
Pass ‘html’ or ‘visual’ in ‘editor_type’ field.
400 2600 Error in “limit” field. This value should be greater than or equal to 0.
Set parameter value greater than or equal to 0.
400 2601 Error in “limit” field. This value should be of type int.
Use int type for “limit” parameter.
400 2602 Error in “offset” field. This value should be greater than or equal to 0.
Set parameter value greater than or equal to 0.
400 2603 Error in “offset” field. This value should be of type int.
Use int type for “offset” parameter.
400 2700 Error in “url” field. This value should be of type string.
Use string type for “url” parameter.
400 2701 Error in “url” field. This value should not be blank.
Make sure the URL is passed.
400 2702 Error in ‘offset’ field. This value should be greater than or equal to 0.
Set parameter value greater than or equal to 0.
400 2703 Error in “eventFormat” field. The value you selected is not a valid choice.
Use format “json_post” or “json_post_gzip” only.
400 2704 Error in “deliveryInfo” field. “delivery_info” value should be 1\0 either true\false.
Set parameter “delivery_info” value to 1\0 either true\false.
400 2705 Error in “singleEvent” field. “single_event” value should be 1\0 either true\false.
Set parameter “single_event” value to 1\0 either true\false.
400 2706 Error in “maxParallel” field. This value should be of type int.
Use int type for “maxParallel” parameter.
400 2707 Error in “maxParallel” field. This value should be between 5 and 100.
Use a valid value of 5 to 100.
400 2708 Error in “events” field. This value should be of type array.
Use array type for “events” parameter.
400 2709 Error in “events” field. This value should not be blank.
Use non-blank events.
400 2710 Error in “events” field. Field “email_status” is required.
Add “email_status” parameter.
400 2711 Error in “email_status” field. This value “test” is not a valid email_status.
Add valid email statuses in the value.
400 2712 Error in “spam_block” field. This value “test” is not a valid spam_block.
Add valid spam blocking events in the value.
400 2713 Error in “url” field. Webhook domain name not found
Make sure the domain is passed correctly.
400 2714 Error in “status” field. Invalid value, status could be one of “active” or “disabled”
Set status “active” or “disabled”.
400 2715 Error in “status” field. This value should be of type string
Use string type for “status” parameter.