{ "openapi": "3.0.0", "servers": [ { "description": "UniOne API-server instance", "url": "https://api.unione.io/en/transactional/api/v1" } ], "info": { "description": "All UniOne API methods require HTTPS connection. UniOne accepts HTTP POST requests in JSON format up to 10 megabytes long and returns HTTP response also in JSON. API endpoint (or base URL) depends on which datacenter the user is registered at.
The preferred way is to use https://api.unione.io/en/transactional/api/v1 endpoint, but also you can use https://eu1.unione.io/en/transactional/api/v1 or https://us1.unione.io/en/transactional/api/v1 directly, depending on the host your account was registered at.\n", "version": "1.87", "title": "Web API", "termsOfService": "https://unione.io/terms.html", "contact": { "url": "https://cp.unione.io/en/support" } }, "security": [ { "apiKeyAuth": [] } ], "tags": [ { "name": "Email", "description": "This group of methods is related with email sending." }, { "name": "Email-validation", "description": "Email validation methods. As a result of the check, you’ll get detailed information on email validity. It will help eliminate nonexistent emails, decrease the number of complaints, clean up the subscribers list and eventually enhance your sender reputation score. For example, you may add validation to a subscription form on your site to let users know they’ve just entered an invalid address." }, { "name": "Template", "description": "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](https://docs.unione.io/en/template-engines)." }, { "name": "Webhook", "description": "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.\n\nYou 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.\n\nPlease note that your webhook handler should be able to process at least 5 parallel requests, up to 100 events each (but you can configure the maximum number of parallel connections up to 100, which is recommended).\n\nIf 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](https://cp.unione.io/en/user/alerting/technical/). \n\nThe format of webhook request and details of each event are described [here](#callback-format).\n" }, { "name": "Suppression", "description": "Methods for managing suppression lists. An email can be added to suppression list because of unsubscription, bounce or complain." }, { "name": "Domain", "description": "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.\n\nTo add new sender domain thru API you should take following steps:\n- Get DNS records with [domain/get-dns-records](#domain-get-dns-records) method and add them to your DNS provider.\n- Every 5-10 minutes call [domain/list](#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.\n- If verification-record.status=\"unconfirmed\" then you should call [domain/validate-verification-record](#domain-validate-verification-record) to trigger verification record validation.\n- If dkim.status=\"inactive\" then start DKIM checking by calling [domain/validate-dkim](#domain-validate-dkim) (UniOne itself checks DKIM every 30 minutes also)\n- 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.\n" }, { "name": "Event-dump", "description": "These methods are used to obtain a list of events for a given period of time. The data is stored for up to 45 days, depending on your tariff, i. e. you may fetch all event data starting from 00:00:00 31 days ago and up to current time. For custom tarifs with big sending volumes event dumps are available only for the last 7 days." }, { "name": "Tag", "description": "This family of methods is used to manage user-defined tags. Tags are used to categorize letters based on your own criteria, e. g. to create a distinction between marketing and transactional letters or group together all notifications for a particular order type. UniOne allows you to assign tags to all outgoing emails, and the tags you’ve set may then be used to filter and analyze delivery statistics." }, { "name": "Project", "description": "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.\n\nProjects methods are disabled by default due to antispam measures. To enable them, [contact support](https://cp.unione.io/en/support).\n\nPlease 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](https://cp.unione.io/en/support) to enable it.\n" }, { "name": "System", "description": "System operations." }, { "name": "Obsolete", "description": "Obsolete methods dealing with unsubscribes. We recommend using the more flexible [suppression](#suppression) methods instead. Note that you can't resubscribe an unsubscribed recipient using WebAPI, but you can send him an email with subscription link using email/subscribe method." } ], "paths": { "/email/send.json": { "post": { "operationId": "email-send", "x-render-on-readme": true, "tags": [ "Email" ], "summary": "Sends an email or a bunch of emails", "description": "While sending you can provide substitutions (merge tags), use a template, turn on read or click tracking, etc.\n\nRestrictions:\n* maximum request size is 10 MB\n* maximum number of recipients is 500\n* The symbol '/' is not allowed in attachment names\n\nIf 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.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "$ref": "#/components/schemas/MessageObject" } } } } } }, "responses": { "200": { "description": "Email successfully accepted for sending.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "job_id" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "job_id": { "type": "string", "example": "1ZymBc-00041N-9X", "description": "Job identifier, might be useful for investigating errors." }, "emails": { "type": "array", "description": "Array of recipients emails successfully accepted for sending.", "items": { "type": "string", "format": "email" } }, "failed_emails": { "type": "object", "description": "Object with emails rejected for sending as property names and their statuses as property values, e.g.: {\"email1@gmail.com\": \"temporary_unavailable\"}. Possible statuses:We may added new statuses in the future.\n", "items": { "type": "string", "additionalProperties": { "type": "string" } }, "example": { "email1@gmail.com": "temporary_unavailable", "bad@address": "invalid", "email@example.com": "duplicate", "root@example.org": "permanent_unavailable", "olduser@example.net": "unsubscribed" } } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/email/subscribe.json": { "post": { "operationId": "email-subscribe", "tags": [ "Email" ], "summary": "Sends an email with (re)subscribe link.", "description": "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.\nThere 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.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from_email", "from_name", "to_email" ], "properties": { "from_email": { "type": "string", "format": "email", "example": "email@example.com", "description": "Sender’s email. (Field alias \"email_address_from\" is supported, too)." }, "from_name": { "type": "string", "example": "Example", "description": "Sender’s name. (Field alias \"name_from\" is supported, too)." }, "to_email": { "type": "string", "format": "email", "example": "email@example.com", "description": "Recipient’s email. (Field alias \"email_address_to\" is supported, too)." } } } } } }, "responses": { "200": { "description": "Email successfully accepted for sending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/template/set.json": { "post": { "operationId": "template-set", "tags": [ "Template" ], "summary": "Creates or updates an email template.", "description": "Restrictions:\n* The maximum request size is 10 MB.\n* The number of templates is limited to 10000.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Object with all the properties of the template.", "required": [ "template" ], "properties": { "template": { "$ref": "#/components/schemas/TemplateObject" } } } } } }, "responses": { "200": { "description": "Template set successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "template" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "template": { "$ref": "#/components/schemas/TemplateObject" } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/template/get.json": { "post": { "operationId": "template-get", "tags": [ "Template" ], "summary": "Gets template properties by it's id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Template id." } } } } } }, "responses": { "200": { "description": "Template returned successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "template" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "template": { "$ref": "#/components/schemas/TemplateObject" } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/template/list.json": { "post": { "operationId": "template-list", "tags": [ "Template" ], "summary": "Returns the list of all or some templates of the account.", "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "default": 50, "description": "Limits the number of templates returned, default is 50." }, "offset": { "type": "integer", "default": 0, "description": "Index of the first template in the list, starting with 0." } } } } } }, "responses": { "200": { "description": "Template list returned successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "templates" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "templates": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateListObject" }, "description": "Array of template objects." } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/template/delete.json": { "post": { "operationId": "template-delete", "tags": [ "Template" ], "summary": "Deletes a template by id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000000", "description": "Template id." } } } } } }, "responses": { "200": { "description": "Template deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhook/set.json": { "post": { "operationId": "webhook-set", "tags": [ "Webhook" ], "summary": "Sets or edits a [webhook](#webhook), i.e. an event notification handler.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://yourhost.example.com/unione-webhook", "description": "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](https://en.wikipedia.org/wiki/Punycode) if you need to use non-ASCII characters." }, "status": { "$ref": "#/components/schemas/WebhookStatusString" }, "event_format": { "$ref": "#/components/schemas/WebhookEventFormatString" }, "delivery_info": { "$ref": "#/components/schemas/WebhookDeliveryInfoInteger" }, "single_event": { "$ref": "#/components/schemas/WebhookSingleEventInteger" }, "max_parallel": { "$ref": "#/components/schemas/WebhookMaxParallelInteger" }, "events": { "$ref": "#/components/schemas/WebhookEventsObject" } } } } } }, "callbacks": { "callback-format": { "{$request.body#/url}": { "post": { "summary": "Webhook callback format description.", "x-code-samples": [ { "lang": "php", "source": "See HTTP sample" }, { "lang": "python", "source": "See HTTP sample" }, { "lang": "ruby", "source": "See HTTP sample" }, { "lang": "csharp", "source": "See HTTP sample" }, { "lang": "java", "source": "See HTTP sample" }, { "lang": "javascript", "source": "See HTTP sample" }, { "lang": "http", "source": "POST https://yourhost.example.com/unione-webhook HTTP/1.1\nHost: yourhost.example.com\nContent-Type: application/json\n\n{\n \"auth\":\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n \"events_by_user\":\n [ \n { \n \"user_id\":456,\n \"project_id\":\"6432890213745872\",\n \"project_name\":\"MyProject\",\n \"events\":\n [ \n { \n \"event_name\":\"transactional_email_status\",\n \"event_data\":\n { \n \"job_id\":\"1a3Q2V-0000OZ-S0\",\n \"metadata\":\n {\n \"key1\":\"val1\",\n \"key2\":\"val2\"\n },\n \"email\":\"recipient.email@example.com\",\n \"status\":\"sent\",\n \"event_time\":\"2015-11-30 15:09:42\",\n \"url\":\"http://some.url.com\",\n \"delivery_info\": \n {\n \"delivery_status\": \"err_delivery_failed\",\n \"destination_response\": \"550 Spam rejected\",\n \"user_agent\":\"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36\",\n \"ip\":\"111.111.111.111\",\n \"country_code\":\"DE\",\n \"country\":\"Germany\",\n \"city\":\"Berlin\",\n \"sender_ip\":\"192.0.2.10\"\n }\n }\n },\n {\n \"event_name\":\"transactional_spam_block\",\n \"event_data\":\n {\n \"block_time\":\"YYYY-MM-DD HH:MM:SS\",\n \"block_type\":\"one_smtp\",\n \"domain\":\"domain_name\", \n \"SMTP_blocks_count\":8,\n \"domain_status\":\"blocked\"\n }\n }\n ]\n }\n ]\n}\n" } ], "requestBody": { "required": true, "description": "Here you can see description of JSON parameters which will be sent to the URL you provide in [webhook/set](#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](#webhook).

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

  1. __transactional_email_status__ - email delivery status change event. You can subscribe to selected statuses only.
  2. __transactional_spam_block__ - event of activating/deactivating a spam block for single or multiple SMTP servers.
", "content": { "application/json": { "schema": { "type": "object", "required": [ "auth", "events_by_user" ], "properties": { "auth": { "type": "string", "description": "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": { "type": "array", "description": "Array with only one element, containing events of a user/project.", "items": { "type": "object", "required": [ "user_id", "events" ], "properties": { "user_id": { "$ref": "#/components/schemas/UserIdInteger" }, "project_id": { "type": "string", "description": "Project identifier, present only if webhook was registered for the project using project API key." }, "project_name": { "type": "string", "description": "Project name, present only if webhook was registered for the project using project API key." }, "events": { "type": "array", "description": "Array of events reported by webhook.", "items": { "type": "object", "properties": { "event_name": { "type": "string", "enum": [ "transactional_email_status", "transactional_spam_block" ], "description": "Type of event data contained in event_data field, either \"transactional_email_status\" or \"transactional_spam_block\"." }, "event_data": { "type": "object", "description": "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.", "properties": { "job_id": { "type": "string", "example": "1ZymBc-00041N-9X", "description": "Job identifier returned earlier by [email/send](#email-send) method. Property exists only if event_name=\"transactional_email_status\"." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "campaign_id": "c77f4f4e-3561-49f7-9f07-c35be01b4f43", "customer_hash": "b253ac7" }, "description": "Metadata passed in [email/send](#email-send) method in recipients.metadata or global_metadata properties. This property exists only if event_name=\"transactional_email_status\"." }, "email": { "type": "string", "format": "email", "description": "Recipient's email. This property exists only if event_name=\"transactional_email_status\"." }, "status": { "type": "string", "enum": [ "sent", "delivered", "opened", "clicked", "unsubscribed", "subscribed", "soft_bounced", "hard_bounced", "spam" ], "description": "Email delivery status. This property exists only if event_name=\"transactional_email_status\". Possible values are:

__accepted__ — the message has been accepted, but not sent yet.
__sent__ — the message has been sent, but not delivered yet.
__delivered__ — the message has been delivered. It can be changed to “opened”, “clicked”, “unsubscribed”, “subscribed” or “spam”.
__opened__ — the message has been delivered and read. It can be changed to “clicked”, “unsubscribed”, “subscribed” 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”, “subscribed” or “spam”.
__unsubscribed__ — the message has been delivered to the recipient and read, but then the recipient unsubscribed. It can be changed to “subscribed”.
__subscribed__ — the message has been delivered to the recipient and read, but then the recipient unsubscribed and subscribed again. It can be changed to “unsubscribed”.
__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](https://en.wikipedia.org/wiki/Feedback_loop_(email))." }, "event_time": { "type": "string", "format": "utc-date-time", "example": "2020-12-24 16:05:58", "description": "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": { "type": "string", "format": "uri", "description": "URL for \"opened\" and \"clicked\" statuses. This property exists only if event_name=\"transactional_email_status\"." }, "delivery_info": { "type": "object", "description": "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\".", "properties": { "delivery_status": { "type": "string", "description": "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_will_retry__ -- email was temporary rejected, delivery will be retried later;
__err_mailbox_discarded__ -- email address was active earlier, but now it's deleted;
__err_mailbox_full__ -- mailbox is full;
__err_spam_rejected__ -- email was rejected as a spam;
__err_blacklisted__ -- email was rejected because sender IP or sender domain is found in a black list;
__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 permanently unavailable;
__err_skip_letter__ -- sending has been canceled because the email address is temporarily unavailable;
__err_domain_inactive__ -- the domain does not accept mail or does not exist;
__err_destination_misconfigured__ -- the domain does not accept mail due to incorrect settings on the recipient’s side, and the server’s response contains information about a cause that can be fixed (for example, an inoperative blacklist is used, etc.);
__err_delivery_failed__ -- delivery failed due to other reasons;
__err_spam_skipped__ -- sending has been canceled because the campaign has been blocked as a spam;
__err_lost__ -- the message was not sent due to inconsistency of its parts or it has been lost because of the failure on our side. The sender needs to re-send the letter on his own, since the original has not been saved;

We reserve the right to change or add internal delivery statuses as we need, so the following list is provided as an example only, without any description: ok_sent, ok_delivered, ok_read, ok_link_visited, ok_unsubscribed, ok_resubscribed, ok_spam_folder, ok_fbl, not_sent, skip_dup_unreachable, skip_dup_temp_unreachable, skip_dup_mailbox_full, err_spam_removed, err_resend, err_unknown, err_retry_letter, err_src_invalid, err_dest_invalid, err_not_available, err_internal, err_no_dns, err_no_smtp, err_giveup." }, "destination_response": { "type": "string", "description": "SMTP response." }, "user_agent": { "type": "string", "example": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36", "description": "User agent of recipient. Present only if detected for \"clicked\" and \"opened\" statuses." }, "ip": { "type": "string", "example": "111.222.33.44", "description": "Recipient's IP address. Present only if detected for \"clicked\" and \"opened\" statuses." }, "country_code": { "type": "string", "example": "DE", "description": "ISO 3166-1 alpha-2 country code detected from recipient IP. Present for \"clicked\" and \"opened\" statuses." }, "country": { "type": "string", "example": "Germany", "description": "Country detected from recipient IP. Present for \"clicked\" and \"opened\" statuses." }, "city": { "type": "string", "example": "Berlin", "description": "City detected from recipient IP. Present for \"clicked\" and \"opened\" statuses." }, "sender_ip": { "type": "string", "example": "192.0.2.10", "description": "IP address of the SMTP server that sent the message. Present only for \"delivered\", \"soft_bounced\" and \"hard_bounced\" statuses, if available." } } }, "block_time": { "type": "string", "format": "utc-date-time", "example": "2020-12-24 16:05:58", "description": "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": { "type": "string", "enum": [ "one_smtp", "all_smtp" ], "description": "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": { "type": "string", "example": "example.com", "description": "Domain that blocked sending. This property exists only if event_name=\"transactional_spam_block\"." }, "SMTP_blocks_count": { "type": "integer", "description": "Number of sending SMTPs blocked. This property exists only if event_name=\"transactional_spam_block\"." }, "domain_status": { "type": "string", "enum": [ "blocked", "unblocked" ], "description": "Whether it's a block or unblock event. This property exists only if event_name=\"transactional_spam_block\"." } } } } } } } } } } } } } }, "responses": { "200": { "description": "Your server returns code 200 in 3 seconds if it successfully processed the callback." } } } } } }, "responses": { "200": { "description": "Webhook set successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "object" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "object": { "$ref": "#/components/schemas/WebhookObject" } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhook/get.json": { "post": { "operationId": "webhook-get", "tags": [ "Webhook" ], "summary": "Gets properties of a [webhook](#webhook).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://example.com/webhook", "description": "Webhook URL." } } } } } }, "responses": { "200": { "description": "Webhook returned successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "object" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "object": { "$ref": "#/components/schemas/WebhookObject" } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhook/list.json": { "post": { "operationId": "webhook-list", "tags": [ "Webhook" ], "summary": "List all or some [webhooks](#webhook) (event notification handlers) of a user or a project.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Limits the number of webhooks returned. 50 is recommended." }, "offset": { "type": "integer", "default": 0, "description": "Index of the first webhook in the list, starting with 0." } } } } } }, "responses": { "200": { "description": "Webhook list returned successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "object" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "objects": { "type": "array", "description": "Array of webhooks objects.", "items": { "$ref": "#/components/schemas/WebhookObject" } } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhook/delete.json": { "post": { "operationId": "webhook-delete", "tags": [ "Webhook" ], "summary": "Deletes an event notification handler", "description": "You can also temporarily deactivate webhook without deleting it by setting it's status to \"disabled\" in [webhook/set](#webhook-set) method.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://example.com/webhook", "description": "Webhook URL." } } } } } }, "responses": { "200": { "description": "Webhook deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/unsubscribed/set.json": { "post": { "operationId": "unsubscribed-set", "tags": [ "Obsolete" ], "summary": "Registers a new unsubscribed email.", "description": "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](#email-subscribe) method or remove \"unsubscribed\" status manually on [Email Search page](https://cp.unione.io/en/user/email) in control panel (but only a limited number of unsubscribed email per day can be removed).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "format": "email", "example": "email@example.com", "description": "Email to be unsubscribed." } } } } } }, "responses": { "200": { "description": "Email has been unsubscribed successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "address", "message" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "address": { "type": "string", "format": "email", "description": "The unsubscribed email." }, "message": { "type": "string", "enum": [ "unsubscribed", "was inactive", "was unsubscribed", "added and unsubscribed" ], "description": "Unsubscription process details: \n" } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/unsubscribed/check.json": { "post": { "operationId": "unsubscribed-check", "tags": [ "Obsolete" ], "summary": "Checks if an email is unsubscribed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "format": "email", "example": "email@example.com", "description": "Email to check." } } } } } }, "responses": { "200": { "description": "Email unsubscription status successfully returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "address", "is_unsubscribed" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "address": { "type": "string", "format": "email", "description": "Email that was checked." }, "is_unsubscribed": { "type": "boolean", "description": "true if unsubscribed, false if not." } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/unsubscribed/list.json": { "post": { "operationId": "unsubscribed-list", "tags": [ "Obsolete" ], "summary": "Returns a list of all unsubscribed emails since provided date.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date_from": { "type": "string", "format": "utc-date", "example": "2020-10-14", "description": "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)." } } } } } }, "responses": { "200": { "description": "The list of unsubscribed emails returned successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "unsubscribed" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "unsubscribed": { "type": "array", "description": "Array of object describing unsubscribed emails.", "items": { "type": "object", "properties": { "address": { "type": "string", "format": "email", "description": "Unsubscribed email." }, "unsubscribed_on": { "type": "string", "format": "utc-date-time", "example": "2020-10-15 22:14:59", "description": "Date and time when a recipient unsubscribed, in UTC timezone and \"YYYY-MM-DD hh:mm:ss\" format." } } } } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/suppression/set.json": { "post": { "operationId": "suppression-set", "tags": [ "Suppression" ], "summary": "Adds an email address to the suppression list. You can always remove this address from the suppression list later using the [suppression/delete](#suppression-delete) method.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "cause" ], "properties": { "email": { "type": "string", "format": "email", "example": "email@example.com", "description": "Email to add in suppression list." }, "cause": { "type": "string", "example": "unsubscribed", "description": "Cause of email being suppressed. One of:" }, "created": { "type": "string", "format": "utc-date-time", "example": "2021-12-19 10:15:49", "description": "When suppression was created, in UTC timezone in \"YYYY-MM-DD hh:mm:ss\" format." } } } } } }, "responses": { "200": { "description": "Email has been added to the suppression list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/suppression/get.json": { "post": { "operationId": "suppression-get", "tags": [ "Suppression" ], "summary": "Gets a reason and date of email suppression.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "email@example.com", "description": "Email to get suppression details for." }, "all_projects": { "type": "boolean", "default": false, "description": "If a user has projects functionality enabled, he/she can pass all_projects=true to search in all projects' data." } } } } } }, "responses": { "200": { "description": "Method call has succeeded (but suppressions array can be empty if sending to email is not suppressed).", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "email", "suppressions" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "email": { "type": "string", "format": "email", "description": "The email for which suppression details were requested." }, "suppressions": { "type": "array", "items": { "$ref": "#/components/schemas/SuppressionGetObject" }, "description": "Array of suppression objects." } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/suppression/list.json": { "post": { "operationId": "suppression-list", "tags": [ "Suppression" ], "summary": "Returns a suppression list since provided date.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cause": { "type": "string", "example": "unsubscribed", "description": "Cause of email being suppressed. One of:We may add some new causes in the future." }, "source": { "type": "string", "example": "user", "description": "Source of email being suppressed. One of:" }, "start_time": { "type": "string", "format": "utc-date", "example": "2020-10-14 17:00:00", "description": "Date in the format YYYY-MM-DD hh:mm:ss to get suppression list from the \"start_time\" to the present day. Ignored if \"cursor\" is not empty." }, "cursor": { "type": "string", "example": "Ajfb6Hvdkn3hdhhvG57xbdufhG5", "description": "The parameter indicates from which position the selection is to be started. Must be empty or omitted for the first data chunk. In order to get subsequent chunks, you must set the \"cursor\" parameter in your request, using the value received in response to the previous request." }, "limit": { "type": "integer", "example": 50, "description": "Limits the number of records to be returned at one time, default is 50." } } } } } }, "responses": { "200": { "description": "Returns a suppression list since provided date.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "suppressions", "cursor" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "suppressions": { "type": "array", "items": { "$ref": "#/components/schemas/SuppressionListObject" }, "description": "Array of suppression objects." }, "cursor": { "type": "string", "example": "Ajfb6Hvdkn3hdhhvG57xbdufhG5", "description": "The parameter indicates from which position the selection is to be started. Must be empty or omitted for the first data chunk. In order to get subsequent chunks, you must set the \"cursor\" parameter in your request, using the value received in response to the previous request." } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/suppression/delete.json": { "post": { "operationId": "suppression-delete", "tags": [ "Suppression" ], "summary": "Deletes an email from suppression list (only records with is_deletable=true). If there are no entries of this email in the suppression list, API error 3003 is returned. If such entries exist but no one can be deleted, API error 3004 is returned. If daily limit of deletes exceeded, API error 906 is returned.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "email@example.com", "description": "An email to delete from suppression list." } } } } } }, "responses": { "200": { "description": "Email has been deleted from the suppression list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domain/get-dns-records.json": { "post": { "operationId": "domain-get-dns-records", "tags": [ "Domain" ], "summary": "Returns info on domain DNS setup for using with UniOne.", "description": "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.\nYou should add then DNS records like this to all of the domains you want to confirm:\n\n`@ IN TXT \"unione-validate-hash=483bb362ebdbeedd755cfb1d4d661\"`
\n`us._domainkey IN TXT \"k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7\"`
\n`@ IN TXT \"v=spf1 include:spf.unione.io ~all\"`
\n\n- First record value should contain \"verification-record\" field returned by get-dns-records method \"as is\".\n- 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.\n- 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.\n\nSyntax requirements of different DNS providers may differ:\n- sometimes it's necesarry to put full domain name instead of @ sign.\n- some providers require add TTL value (like 3600)\n- some providers don't require quotes for enclosing values\nPlease check requirements of your provider and advice your users to do it.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "example.com", "description": "Domain to get DNS records for." } } } } } }, "responses": { "200": { "description": "Domain DNS info returned successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "domain", "verification-record", "dkim" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "domain": { "type": "string", "example": "example.com", "description": "Domain to get DNS records for." }, "verification-record": { "type": "string", "example": "unione-validate-hash=483bb362ebdbeedd755cfb1d4d661", "description": "Record to be added \"as is\" to verify ownership of this domain." }, "dkim": { "type": "string", "example": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7", "description": "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)." } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domain/validate-verification-record.json": { "post": { "operationId": "domain-validate-verification-record", "tags": [ "Domain" ], "summary": "Triggers verification record validation for domain.", "description": "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](#domain-list) method to get the result. Please read more [here](#domain).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "example.com", "description": "Domain to validate verification record for." } } } } } }, "responses": { "200": { "description": "Verification record is valid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "message": { "type": "string", "example": "Record updated", "description": "Debug message." } } } } } }, "default": { "description": "Error occured or record is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domain/validate-dkim.json": { "post": { "operationId": "domain-validate-dkim", "tags": [ "Domain" ], "summary": "Validates DKIM record for domain.", "description": "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](#domain-list) method to get the result. Please read more [here](#domain).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "example.com", "description": "Domain to validate DKIM record for." } } } } } }, "responses": { "200": { "description": "DKIM record validation has started successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "message": { "type": "string", "example": "Record updated", "description": "Debug message." } } } } } }, "default": { "description": "Error occured or record is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domain/list.json": { "post": { "operationId": "domain-list", "tags": [ "Domain" ], "summary": "Returns a list of all registered domains for user or project, together with statuses of last validations.", "description": "Returns last status of ownership validation and DKIM validation for each domain. Read more [here](#domain).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com", "description": "Optional domain name if you want to get the status of single domain only." }, "limit": { "type": "integer", "default": 50, "description": "Limits the number of domains returned. Default is 50." }, "offset": { "type": "integer", "default": 0, "description": "Index of the first domain in the list, starting with 0." } } } } } }, "responses": { "200": { "description": "The list of the registered domains returned successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "domains" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "domains": { "type": "array", "description": "Array of objects describing domains.", "items": { "type": "object", "required": [ "domain", "verification-record", "dkim" ], "properties": { "domain": { "type": "string", "example": "example.com", "description": "Domain name." }, "verification-record": { "type": "object", "description": "Object describing verification record value and status.", "properties": { "value": { "type": "string", "example": "unione-validate-hash=483bb362ebdbeedd755cfb1d4d661", "description": "Record to be added \"as is\" to verify ownership of this domain." }, "status": { "type": "string", "enum": [ "confirmed", "unconfirmed" ], "description": "Only domains with \"confirmed\" verification record are allowed as sender domains." } } }, "dkim": { "type": "object", "description": "Object describing DKIM record value and status.", "properties": { "key": { "type": "string", "example": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDo7", "description": "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](#domain-get-dns-records))." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Only domains with \"active\" DKIM record are allowed as sender domains." } } } } } } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/domain/delete.json": { "post": { "operationId": "domain-delete", "tags": [ "Domain" ], "summary": "Deletes a domain. Attention: you should use project's API key to delete a project's domain.", "description": "Deletes a domain.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com", "description": "Domain name to delete." } }, "required": [ "domain" ] } } } }, "responses": { "200": { "description": "Domain has been successfully deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "$ref": "#/components/schemas/SuccessStatusString" }, "message": { "type": "string", "example": "Domain deleted", "description": "Domain deleted" } } } } } }, "default": { "description": "Error occured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/event-dump/create.json": { "post": { "operationId": "event-dump-create", "tags": [ "Event-dump" ], "summary": "This asynchronous method initiates the preparation of data dump in CSV format. The number of dump files created or stored is limited to 10; to order more files, you have to delete one of the previous ones or wait until they will be deleted automatically. A newly created dump file is kept for 8 hours. If the request period is more than a day or there are too many events then several files will be generated and each file will contain no more than 100,000 events. File contains columns with the following information - 'event_time', 'job_id', 'from_email', 'email', 'status', 'delivery_status', 'metadata', 'destination_response', 'user_agent', 'url', 'ip', 'tags' and 'project_id' (for accounts with projects enabled). You can change the fields and include 'subject' field using 'dump_fileds' parameter.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "start_time" ], "properties": { "start_time": { "type": "string", "format": "utc-date-time", "example": "2022-07-20 00:00:00", "description": "Date and time in YYYY-MM-DD hh:mm:ss format, specifying period start time. Data is stored for up to 32 days, depending on your tariff." }, "end_time": { "type": "string", "format": "utc-date-time", "example": "2022-07-21 00:00:00", "description": "Date and time in YYYY-MM-DD hh:mm:ss format, specifying period end time (non-inclusive)." }, "limit": { "type": "integer", "example": 50, "description": "Maximum number of events returned (default is 50). If this value is over 100 000, several files will be created, each having 100 000 events maximum." }, "all_projects": { "type": "boolean", "default": false, "description": "For accounts with projects enabled, the value all_projects=true allows to fetch data for all existing projects." }, "filter": { "$ref": "#/components/schemas/FilterObject" }, "dump_fields": { "$ref": "#/components/schemas/DumpFieldsObject" }, "aggregate": { "type": "string", "example": "day_status", "description": "Allows you to obtain aggregated statistics for a given time period. The two allowed values are: