email/send

This method sends transactional emails to your subscribers.

Restrictions:

  • maximum request size - 5 MB

  • maximum number of recipients - 500 emails

  • subject and body of the message must be specified

  • the variables set in "substitutions" and "global_substitutions" objects can contain letters, numbers, "_" and "-". The first character can only be a letter; spaces are not allowed.

Test request

POST /en/transactional/api/v1/email/send.json
{
  "api_key": "apiKey",
  "message": 
  {
    "template_engine" : "simple",
    "template_id" : "template_id",
    "global_substitutions": 
    {
      "someVar":"some val"
    },
    "global_metadata": 
    {
      "key1" : "val1"
    },
    "body": 
    {
      "html": "<b>Hello {{substitutionName}}</b>",
      "plaintext": "Some plain text",
      "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": "Example subject",
    "from_email": "email@example.org",
    "from_name": "userName",
    "reply_to": "email@example.org",
    "track_links" : 1,
    "track_read"  : 1,
    "recipients": [
      {
        "email": "email@example.org",
        "substitutions": 
        {
          "substitutionName": "substitutionVal",
          "to_name": "Name Surname"
        },
        "metadata":
        {
           "key1" : "val1"
        }
      },
      {
        "email": "bad_email@com",
        "substitutions": 
        {
          "substitutionName": "substitutionVal",
          "UNSUB_hash": "Qwcd1789"
        }
      }
    ],
    "headers": 
    {
      "X-MyHeader": "some_useful_data"
    },
    "attachments": [
      {
        "type": "text/plain",
        "name": "myfile.txt",
        "content": "ZXhhbXBsZSBmaWxl" 
      }
    ],
    "inline_attachments": [
      {
        "type": "image/png",
        "name": "IMAGECID",
        "content": "iVBORw0KGgo" 
      }
    ],
    "options": 
    {
      "unsubscribe_url": "someurl"
    }
  }
}

Success response example


{
  "status":"success",
  "job_id":"1ZymBc-00041N-9X",
  "emails":["email@gmail.com"]
}

Request parameters

Name Type Description
api_key Mandatory string User API key
message Mandatory object Object contains all the parameters of the message
message.template_engine Optional string Sets the template engine for handling the substitutions. Accepts values: "simple" и "velocity". If the parameter is not passed, the system will use the default value - "simple"
message.template_id Optional string (required, if "body" is not passed) Unique identifier of the template that had been created before. How to create templates. If "body" is passed, "template_id" will be ignored
message.global_substitutions Optional object Object for passing the substitutions (e.g., company name). If the substitution names are duplicated in object "substitutions", the values of the variables will be taken from the object "substitutions". The substitutions can be used in the following parameters:
  • body.html
  • body.plaintext
  • body.amp
  • subject
  • options.unsubscribe_url
  • from_name
message.global_metadata
(obsolete alias: message.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.
message.body Optional object (required, if "template_id" is not passed) Object, contains HTML / plaintext / AMP parts of the email. To include inline attachments, use "inline_attachments" array
message.body.html Mandatory string Html part of the email body
message.body.plaintext Optional string Plaintext part of the email body
message.body.amp Optional string AMP part of the email body
message.subject Mandatory string Email subject
message.from_email Mandatory string Sender’s email
message.from_name Optional string Sender’s name
message.reply_to Optional string Email address of the recipient to which the email response is directed
message.track_links Optional boolean
  • 0 - click tracking is off
  • 1 - click tracking is on (default)
message.track_read Optional boolean
  • 0 - email read tracking is off
  • 1 - email read tracking is on (default)
message.recipients Mandatory array of objects Contains recipient’s emails and the object that includes variables for substitutions and their values
message.recipients.email Mandatory string Recipient’s email
message.recipients.substitutions Optional object Object to pass the substitutions for the user (e.g. user name, product name to be shown for this user. See Template engines). The substitutions can be used in the following parameters:
  • body.html
  • body.plaintext
  • body.amp
  • subject
  • options.unsubscribe_url
  • from_name

message.recipients.substitutions. to_name

Optional string Variable for substitution in SMTP header "To", is used to substitute the recipient name. The string "To" in the recipient’s inbox will look like: Name Surname <recipient.email@example.com>. The string is limited to 78 symbols
message.recipients.substitutions. UNSUB_hash Optional string Example of the variable that can be used to put user hash into the custom unsubscribe link
message.recipients.metadata Optional object Object for passing the metadata specific for single recipient, such as "key" : "value". Max key quantity: 10. Max key length: 64 symbols. Max value length: 1024 symbols. The metadata is returned by Webhook.
message.headers Optional object Object, contains email headers. Only headers with "X-" name prefix are accepted, all other are ignored.
message.attachments Optional array Parameters array of attachments. Contains parameters: "type", "name", "content"
message.attachments[n].type Mandatory string Attachment type, see MIME. Example: "type" : "text/plain". If unsure, use "application/octet-stream"
message.attachments[n].name Mandatory string Attachment name in the format: "name.extension"
message.attachments[n].content Mandatory string File contents in base64.
message.inline_attachments Optional array Inline attachment's parameters array, to be included in HTML body. Usually images.
message.inline_attachments[n].type Mandatory string Attachment type, see MIME. Example: "type" : "image/png". 
message.inline_attachments[n].name Mandatory string Attachment content id. For example, "name"="IMAGECID" should be referenced in HTML like <img src="cid:IMAGECID">
message.inline_attachments[n].content Mandatory string Attachment content, base64-encoded.
message.skip_unsubscribe Optional boolean
  • 0 - append a footer with unsubscription link to HTML body (default)
  • 1 - dont append a footer with unsubscription link to HTML body (but List-Unsubscribe header is still set if options.unsubscribe_url is not empty)

In order to use skip_unsubscribe=1 value you should ask support to enable it first.

message.force_send Optional boolean
  • 0 - avoid sending to unsubscribed/unreachable emails
  • 1 - send an email without respecting it's possible unsubscribed/unreachable status.

In order to use force_send=1 value please contact support to sign a special agreement anti-spam agreement.

message.options Optional object Object, contains additional options
message.options.unsubscribe_url Optional string Custom unsubscribe link

 

Success response fields

Name Type Description
status Mandatory string Contains "success" value
job_id Mandatory string Unique identifier of the executed sending
emails Mandatory array Array contains the email addresses to which messages were successfully delivered
failed_emails Mandatory object

Object contains emails to which the sending for some reasons has not been carried out. The object is filled in the format: "address" : "state"

Possible states of addresses to which sending failed:

unsubscribed - specified email is unsubscribed;

invalid - the email does not exist or has been entered incorrectly;

duplicate - the email already exists in the request, email duplicating is prevented;

temporary_unavailable - the email address is unavailable. This means that over the next three days, sending to this address will return an error. Email may be temporarily unavailable due to one of the following:

  • a previous email has been rejected by the recipient's server for spam;

  • the recipient's mailbox is full;

  • domain does not accept mail due to incorrect settings on the recipient's side;

  • domain does not accept any mail at all, for any reason;

  • the mailbox is not used;

  • sending server was rejected due to blacklisting;

permanent_unavailable - the email address is permanently unavailable, unsubscribed globally, or the recipient reported spam in the previous emails

 

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

 

Successful request, completed with errors


{
  "status":"success",
  "job_id":"1ZymBc-00041N-9X",
  "emails":["email@gmail.com"],
  "failed_emails":
    { "email1@gmail.com":"unsubscribed", "email2@gmail.com":"invalid", 
    "email@gmail.com":"duplicate", "email3@gmail.com":"temporary_unavailable" }
}

 

Error response fields

status - "error" string

message - human readable error message in English

code - one of the generic error codes or error code from the table below:

Code Meaning How to fix
201 The message body is missing Check that your message body is being passed properly
202 Sender email is missing Enter the sender email
203 Email subject is missing Enter the subject
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. Example
205 Invalid sender email Make sure the parameter is passed properly
206 Sender email is not verified To avoid this error, use an email on a verified domain
207 MIME file type is incorrect Check the file and the file type again
208 Too many recipients Reduce the number of recipients
209 The attached file names are duplicated Rename files with the same names
210 Inline attachment names are duplicated Rename files with the same names
211 The attached file name is missing Specify the name of the attached file
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)
213 The user is trying to use the custom backend domain but currently, this option is not allowed for that user Try contacting support
215 The user is not allowed to send Try contacting support
216 Recipients passed improperly "Metadata" value should be a string or integer. Array for "metadata" key is expected
217 Too many metadata fields passed Maximum 10 metadata fields allowed
218 Recipients passed improperly Metadata key length should be less than 64
219 Recipients passed improperly Metadata value length should less than 1024
220 The value in template_engine differs from simple/velocity Check the value passed in the parameter "template_engine"
221 The <body> tag does not exist in the request or is invalid Add the html <body> tag to the request
222 Html part is too long The HTML size should be less than 5 Mb
223 The body is missing in the attachments "content" or the void is transferred Add the "content" and specify a value for it
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.
902 Sending limit for free tariff is reached. Wait till next day or switch to paid tariff.
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.
904 Insufficient funds. Credit card transaction failure. Please try another card or contact support to resolve the situation. 
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.
908 Internal error, project owner not found Please contact support

 

Custom unsubscribe link


UniOne adds a standard footer with an unsubscribe link to each email. The language of the default unsubscribe link depends on the language of the email/send request (e.g. for /en/transactional/api/v1/email/send.json, the link language is English).

To change the default unsubscribe link and configure the opt-out settings on your side, follow these steps:

  1. Contact support to disable the default unsubscribe link;

  2. Add "unsubscribe_url" : "URL" into object "Options". URL - custom unsubscribe link used in the email. Substitutions also work in the unsubscribe link, so if you pass a variable in the object "substitutions", you can use this variable in the unsubscribe link for setting user hash.
    Example:   
    "substitutions": {"UNSUB_hash": "Qwcd1789"}
    and
    "options": {"unsubscribe_url":"http://emlportal.com/en/v5/te_unsubscribe?hash= { {UNSUB_hash}}"}

  3. Insert the unsubscribe link into the email body.