Generic selectors
Exact matches only
Search in title
Search in content
Search in posts
Search in pages

sendEmail method

It is a method to send a single individual email without personalization and with limited possibilities to obtain statistics. A reasonable use scenario is personal notification of a client about an individual event (for example, changes in the status of an order in an on-line store). A combination of the createEmailMessage / createCampaign methods is used for mass campaigns with the similar letters.

To send transactional letters, use the UniOnethe transactional letter service from UniSender.

Messages sent via sendEmail are not censored by a human, so the number of messages allowed to be sent per day using this method is limited by default to 1000 for new users (subsequently, the limit will be automatically increased, provided that there is a positive delivery statistics), and the maximum message size will be limited to 1 megabyte.

The limit on the number of calls per minute is 60. The minimum interval between sendings to the same recipient is 60 seconds.

Since messages can be made as individual as possible, field substitution is not performed, except for the {{UnsubscribeUrl}} value.

You can find out the delivery status of the message sent using the checkEmail method. To speed up the work of the sendEmail method, delivery statuses are stored for a limited period of time, i.e. only for one month.

Principle of use

Syntax and URL to call the method
sendEmail (email, sender_name, sender_email, subject, body, list_id [attachments, lang, track_read, track_links, bool, string cc, array | string headers, string wrap_type, string images_as, bool error_checking, metadata])
Example:https://api.unisender.com/en/api/sendEmail?format=json&api_key=KEY &email
=TONAME <EMAILTO>&sender_name=
FROMNAME&sender_email=FROMMAIL&subject=SUBJECT
&body=HTMLBODY&list_id=X&attachments[filename1]=FILE1&attachments
[filename2]=FILE2&lang=LANG&error_checking=1&metadata[meta1]=
value1&metadata[meta2]=value2
Arguments
api_key * API access key.
email * Message recipient’s address.

Recipient’s name can be transferred as well:

Vasya Pupkin <vpupkin@gmail.com>

Please note that the name must be specified before the address, and there must be a space between them.

When using a GET request to transfer Cyrillic letters in the name, you must encode the string (URL encoding)

sender_name * Sender’s name. It is an optional string that does not match the email address (with the sender_email argument).
sender_email * Sender’s email address. This email must be checked (to do this, you need to manually create at least one email with this return address via the web interface, then click on the “send the confirmation request” link and follow the link from the email).
subject * String with the letter subject.
body * Text of the letter in the HTML format. User substitution fields are virtually not supported to speed up processing (it is assumed that the letter is composed individually for the recipient), and only the availability is guaranteed.The text may also include relative links to images stored in the user’s folder on our server, and such images will be included in the letter itself. Links to images on the server should be as follows: “/en/user_file?resource=images&name=IMAGE”, where instead of IMAGE must be the file name from your server folder, for example image.jpg or folder/image.jpg.

If the image is not stored on our server, you can insert the image as a file attachment (see the description of the attachments argument).

list_id * Code of the list from which the recipient will be offered to unsubscribe in case he follows the unsubscribe link. Codes of all lists can be obtained by calling getLists. If the recipient is not present in the address book of your account in the system or is not in the specified list, it will be added to the database and/or list automatically.
attachments Files attached to the letter (their binary content, base64 cannot be used!).
attachments – ассоциативный массив файлов-вложений. В качестве ключа указывается имя файла, в качестве значения – содержимое файла, например:

attachments[quotes.txt]=text%20file%content

Using a PHP script, the file contents can be obtained through the file_get_contents function. For example:

$api_query = array(....,"attachments[test.pdf]"=>file_get_contents('test.pdf'),...);

Attachments will be added to the message in the same order as they are listed. Inline images can be inserted into the text through adding them as attachments and referring to them in HTML as follows: <img src=”3_name.jpg”>. You need to substitute the ordinal number of the attachment (the numbering starts from one for each recipient) instead of the number three, and the attachment name instead of name.jpg.

It is assumed that the HTML text contains only the content of the body tag. If you transfer the entire HTML text, test such letters additionally as headers outside the body may be modified.

lang Two-letter language code for the string with the unsubscribe link that is added to each letter automatically.

If it is not specified, the language code from the из URL request to API is used.

In addition to the string with the unsubscribe link, this language also affects the interface of the unsubscribe page. Languages ru, ua, it and en are fully supported, and in case of some other languages (da, de, es, fr, nl, pl, pt, tr), the string with a link will be translated, and the control interface will be in English.

track_read The value obtained is either 0 or 1 – whether to track the fact of reading the email. The default value is 0 (do not track). If 1, a link to a small image tracking the reference will be added to the email.
track_links The value obtained is either 0 or 1 – to track whether the recipient has followed the links in the emails, the default value is 0 (do not track). If 1, all external links will be replaced with special ones that allow you to track the fact of a click-through, and then forward the user to the desired page.
cc List of email addresses separated by commas. It contains addresses of secondary recipients of the letter who are sent a copy of the letter. It must contain no more than 10 elements. You can use the cc parameter to debug or to prove that you have sent the letter.
headers Text with a list of headers, each header is in a separate string in the MIME format. Currently, only two headers are supported, Reply-To and Priority, the rest will be ignored. Example:

Reply-To: my@email.info
Priority: normal
wrap_type Placing the HTML text of the letter in an additional «wrapping» of the HTML code in order to improve its compatibility with various mail services and to align the text of the message on the specified side. If the argument is absent, the text will be wrapped. Also, the parameter can obtain the following values: skip (do not apply), right (right alignment), left (left alignment), center (center alignment)..
images_as It allows changing the processing mode of the images attached in the letter. It may have the following values: attachments (behavior by default when the parameter is not set) — images will be saved inside the letter as attachments, only_links — images sent in the image request will be stored on our service, only links to them will be displayed in the letter (this will reduce the size of the letter), user_default — one of the above modes will be used which are set for a specific user by the customer support service or by the reseller. The parameter transferred in the request has a higher priority than that set for you in the profile.
ref_key The parameter can be transferred by the user to assign an identifier key to the letter. The obtained key value must be unique. Example:

…&ref_key=123

error_checking The value obtained is either 0 or 1. To ensure backward compatibility, the default value is 0, but we recommend you to always transfer this parameter with the value 1.
metadata The metadata sent in the request is returned in Webhooks metadata can be transferred in the following form:

metadata[meta1]=value1&metadata[meta2]=value2
Return value
Example of the new format of the return value:

{
    "result": 
        [   {"index": 0, "email": "qwe.rty@uio.com", "errors": 
                [  {"code": "unchecked_sender_email", "message": "Unconfirmed sender's Email"}
                ]
        }
    ]
}

The result is returned in this format the call is made with error_checking = 1.

{"result":
    [   {"index":0,"email":"zzx@zzx.c", "errors":
            [   {"code":"unchecked_sender_email","message":"Unconfirmed sender's"}
            ]
        },
        {"index":1,"email":"bad@bad", "errors":
            [   {"code":"invalid_email","message":"Invalid email address"}
            ]
        }
    ]
}

The result is returned in this format when the call is made with error_checking = 1 using the cc argument. The return value is a JSON array of objects (the number of elements is equal to the number of emails sent, taking into account cc) with the following fields:

index Unique index of the email address corresponding to the position of the address in the source array of recipients. If the cc parameter is used, there may be indices that are missing in the original email array, they are indices of message copies.
email Email address to which the message was sent corresponds to the address from the email argument or to any address from the cc argument.
id Unique message code – string of up to 64 characters.
If sending is not possible because of an error, the id field is absent. You should also take into account the fact that not all errors are detected at the time of receipt of the sending request. In this case, the message is accepted for processing and receives an id, and the error can be detected later using the checkEmail method.
errors Field representing an array of objects with errors associated with the email address. The field is present only when the input data is invalid and the message cannot be sent to the specified email address. Each array element is a JSON object with the code and message fields, where code contains the conditional error code and the message is a message describing the error. The list of possible error codes:

  • retry_later
    Temporary error. Try later (the recommended timeout is a minute).
  • attachment_is_not_bytestring
    The content of the attachment is not a scalar value.
  • attachment_quota_error
    The attachment size limit has been exceeded.
  • body_empty
    The body of the letter is missing.
  • body_exceeds_length
    The body of the letter exceeds the size permitted.
  • empty_subject
    The subject of the letter is not specified.
  • subject_exceeds_length
    The subject of the letter exceeds the size permitted.
  • wrong_header_parameter
    The mandatory header parameter is not specified.
  • header_not_allowed
    The header specified is not supported.
  • invalid_email
    Invalid email address.
  • empty_sender_name
    Sender’s name is not specified.
  • invalid_sender_email
    Invalid sender’s email address.
  • unchecked_sender_email
    Sender’s email address is not confirmed.
  • unsupported_lang
    The specified language is not supported by the system.
  • has_been_sent
    Email has already been sent to this recipient.
  • unsubscribe_link_missing
    You have forgotten to add the unsubscribe link.
  • unsubscribed_globally
    The address has been unsubscribed globally.
Example of the old format of the return value that has been left for compatibility purposes:

{"result": {
    "email_id":14362456134
}

This format is used under the following conditions: the call must not contain the error_checking parameter or it must have the zero value, the message is sent without the use of the ‘cc’ argument. In this case, the return value is a JSON object with a single documented field:

email_id Unique message code. It can be used to control the delivery using the checkEmail method.

Example of forming the URL request

https://api.unisender.com/en/api/sendEmail?format=json&api_key=KEY
&email=test@example.com&sender_name=Mike&sender_email=mike@example.com
&subject=Sample+Subject&body=Hello,+World!&list_id=112233

— send the message “Hello, World” to test@example.org with the return address mike@example.com.