It is a method to send a single individual email without personalization and with limited possibilities to obtain statistics. A common use case is personal notification of a client about an individual event (for example, changes in the status of an order in an online store). A combination of the createEmailMessage / createCampaign methods is used for mass campaigns with similar message.
To send transactional letters, use the UniOne — the transactional letter service from Selzy.
Messages sent via sendEmail are not moderated by a human, so the number of messages allowed to be sent per day using this method is limited by default to 1,000 for new users (subsequently, the limit will be automatically increased, provided the good delivery statistics), and the maximum message size will be limited to 1 MB.
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 as personalized as possible, field substitution is not performed, except for the {{UnsubscribeUrl}} value.
You can learn the delivery status of the sent message using the checkEmail method. To ensure better performance of the sendEmail method, delivery statuses are stored 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: Mary Smith <[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 confirmed (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 email subject. |
| body * | Text of the email in the HTML format. User merge tags are not supported to speed up processing (it is assumed that an email is created specifically 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 email 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 * | ID of the list from which the recipient will be offered to unsubscribe in case he follows the unsubscribe link. IDs of all lists can be obtained by calling getLists. If the recipient is not present in the contact list 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 email (their binary content, base64 cannot be used!). Attachments are an associative array of attachment files. The file name is specified as the key, and the contents of the file is 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 (starts from "1" for each recipient) for the number "3", and the attachment name for name.jpg. It is assumed that the HTML text contains only the contents of the body tag. If you transfer the entire HTML text, test such emails 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 email automatically.
If it is not specified, the language code is en. In addition to the string with the unsubscribe link, the selected language also affects the interface of the unsubscribe page. 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 while the user interface remain 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 the value is 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 followed the links in the emails, the default value is 0 ("do not track"). If the value is 1, all external links will be replaced with the 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 the address of a secondary recipient of the email who is sent with a copy of the email. It must contain no more than 1 element. You can use the cc parameter to debug or to prove that you have sent the email. Billing always occurs as for sending a separate email and such an email address is not included in the list of used addresses in Lite and Standard plans. |
| headers | 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 email in an additional «wrapping» of the HTML code in order to improve its compatibility with various mailbox providers and to align the text of the message to 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 | Allows changing the processing mode of the images attached to the email. It may have the following values: attachments (behavior by default when the parameter is not set) — images will be saved inside the email as attachments, only_links — images sent in the image request will be stored on our server, only links to them will be displayed in the email (this will reduce the size of the email), 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 the one set for you in the profile. |
| ref_key | The parameter can be transferred by the user to assign an identifier key to the email. 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 format:
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 left to ensure the compatibility:
{"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].
