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.
-
https://us1.unione.io/en/transactional/api/v1 - UniOne USA & Canada Instance
-
https://eu1.unione.io/en/transactional/api/v1 - UniOne European Instance
Authentication
Every method call requires authentication by providing user API key or project API key in either of two places:
- X-API-KEY HTTP header
- api_key JSON field
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:
- maximum request size is 5 MB
- maximum number of recipients is 500
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. |
| 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:
|
| »» 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:
|
| » 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:
|
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:
- The maximum request size is 5 MB.
- The number of templates is limited to 10000.
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:
|
| » 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:
|
| » 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:
|
| » 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:
|
| » 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:
- transactional_email_status - email delivery status change event. You can subscribe to selected statuses only.
- transactional_spam_block - event of activating/deactivating a spam block for single or multiple SMTP servers.
See HTTP sampleSee HTTP sampleSee HTTP sampleSee HTTP sampleSee HTTP sampleSee HTTP samplePOST 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”. |
| 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:
|
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:
- Get DNS records with domain/get-dns-records method and add them to your DNS provider.
- Every 5-10 minutes call domain/list method for your domain (or several domains) and check verification-record.status and dkim.status in the response. You can call it more often if you like, but please not more than once per minute.
- If verification-record.status=“unconfirmed” then you should call domain/validate-verification-record to trigger verification record validation.
- If dkim.status=“inactive” then start DKIM checking by calling domain/validate-dkim (UniOne itself checks DKIM every 30 minutes also)
- When you get verification-record.status=“confirmed” and dkim.status=“active” for the domain then you can stop checking it’s status with domain/list and start using it as a sender domain.
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"
- First record value should contain “verification-record” field returned by get-dns-records method “as is”.
- Second record value should contain “dkim” field value after “p=”. Mind the name of this record! “us._domainkey.” prefix is important for DKIM selector of UniOne to work properly.
- Third record contains optional, but very recommended SPF entry. Probably you already have one, then just add append include:spf.unione.io right after v=spf1.
Syntax requirements of different DNS providers may differ:
- sometimes it’s necesarry to put full domain name instead of @ sign.
- some providers require add TTL value (like 3600)
- some providers don’t require quotes for enclosing values Please check requirements of your provider and advice your users to do it.
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. |
| 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. |