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 UniOne — the transactional letter service from Selzy.
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.selzy.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 <[email protected]> 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 is an associative array of attachment files. The file name is specified as the key, and the contents of the file are specified as the value, for example: 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 is en. In addition to the string with the unsubscribe link, this language also affects the interface of the unsubscribe page. Languages en, ua, it and ru 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 | It contains address of secondary recipient of the letter who are sent a copy of the letter. It must contain no more than 1 element. You can use the cc parameter to debug or to prove that you have sent the letter. Billing always occurs as for sending a separate letter, it is not included in the list of used addresses of Light / Standard subscription tariffs. |
| 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: [email protected] 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": "[email protected]", "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":"[email protected]", "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 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:
|
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.selzy.com/en/api/sendEmail?format=json&api_key=KEY &[email protected]&sender_name=Mike&[email protected] &subject=Sample+Subject&body=Hello,+World!&list_id=112233
— send the message "Hello, World" to [email protected] with the return address [email protected].