SMTP API

SMTP allows sending up to 3000 emails per hour using single connection, and with 50 maximum permitted connections it could be up to 150 000 emails per hour. Web API allows sending up to several millions emails per hour, so consider using Web API if speed is your priority. But the good news is that SMTP integration is very simple, you just need to set some connection parameters. And don't forget to read our emails about API updates or take a look on changelog periodically.

SMTP Connection parameters

  • host: either smtp.us1.unione.io or smtp.eu1.unione.io (for accounts registered at us1.unione.io and eu1.unione.io, respectively).

  • port25, 465 or 587. Only encrypted TLS connections are supported, with recommended version 1.2 or higher. We provide no support neither for unencrypted port 25 SMTP connections nor for encrypted SSL connections due to security reasons. TLS 1.0 and TLS 1.1 support will be terminated in the middle of 2021.

  • usernameuser_id (you can see it in the upper left corner of the screen under your email after login) or project_id (you can get it by project/create or project/list method, and also on Projects page).

  • passwordAPI key of your account or project_api_key (you can get it by project/create or project/list method, and also on Projects page)

  • encoding: connection encoding should be set to UTF-8

Extended features

You can use extended features of UniOne while sending thru SMTP, such as substitutions(merge tags), templates, link and read tracking.To access these features you should pass an extra header X-UNIONE with parameters in JSON format. Many parameters from email/send are supported together with extra parameter "global_language". E.g.:

{
  "global_language": "en",
  "template_engine": "velocity",
"template_id": "5c046a8b-6f6b-4f0b-a5b6-1d0ff8953ac7",   "global_substitutions": {   "DiscountCode":"XMAS",   "Name": "John"   },   "global_metadata": {   "meta-campaign": "transactional"   },   "track_links":1,   "track_read":1, "skip_unsubscribe":0 }

All supported X-UNIONE JSON parameters

Name Type Description
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"
template_id Optional string Optional identifier of the template that had been created by template/set method or in UniOne web interface.
global_language Optional string Language used for unsubscribe footer and unsubscribe page interface. "en" by default. Supported languages: be, de, en, es, fr, it, pl, pt, ru, ua, kz. You can ask our support if you need other languanges.
global_substitutions Optional object Object for passing the substitutions (e.g., first name of recipient).
global_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.
track_links Optional boolean
  • 0 - click tracking is off
  • 1 - click tracking is on (default)
track_read Optional boolean
  • 0 - email read tracking is off
  • 1 - email read tracking is on (default)
skip_unsubscribe Optional boolean
  • 0 - append a footer with unsubscription link to HTML body (default)
  • 1 - don't 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.

strict Optional boolean

This parameter sets the way "To:", "CC:", and "BCC:" headers are processed (see also Implementation details):

  • false - each addressee listed in "To:", "CC:", and "BCC:" will receive their own copy (default value)
  • true - headers are processed with strict adherence to SMTP specs
tags Optional array An array of strings. The maximum string length is 50 characters. You can include up to 4 strings which must be unique. No more than 10 000 tags are allowed per project; if you try to add more, email/send will return an error. You may use tags to categorize emails by your own criteria, and they will be passed along by event-dump methods.

 

Implementation details

  • Maximum accepted email size is 10 megabytes.
  • Please don't forget that all headers, including X-UNIONE header, should be encoded according to MIME standard, if contain non-ASCII characters. The majority of programming languages have special functions for such an encoding. For example, in PHP it's a mb_encode_mimeheader function.
  • There's a limit of 300 bytes for header line length in UniOne. You should divide a header into several lines if it's longer than 300 bytes. Usually the same function that does MIME encoding also takes care of line splitting. For example, in PHP it's the same mb_encode_mimeheader.
  • Please note that unsubscribe link is automatically added to the footer of your email, unless you pass skip_unsubscribe=1 parameter in X-UNIONE header or ask support to disable unsubscribe link for all of your SMTP and API sent emails. Information about unsubscriptions can be obtained through webhooks or by calling suppression/get и suppression/list methods (where "cause"="unsubscribed").
  • Please note that by default UniOne deviates from the SMTP specification in the way it handles the "CC:" and "BCC:" fields. Each address listed in these fields will receive its own copy of the letter, in which the MIME To: header will contain that target address only, and original "To:" and "CC:" headers will be removed. Each copy will be charged for according to your tariff. Also, values for global_substitutions will apply to all copies; thus, for personalized emails it is advised to use single messages. If you need the SMTP specification to be followed strictly, with "To:" and "CC:" headers being left intact (which may be required to implement carbon copy and blind carbon copy functionality), you may set the strict parameter value to true in the X-UNIONE header (or, alternatively, contact tech support to have strict=true set by default for all of your letters, without having to specify the parameter in X-UNIONE. To prevent malpractices, we also perform additional validation on RCPT TO: it must contain only addresses that are present in "To:" and "CC:" MIME headers, or addresses on your own validated domains. Passing the name in the MIME headers "To:" and "CC:", the characters '<', '>', '@', ',' are forbidden. The number of addresses in CC and BCC must not exceed 10 for each header, and BCC may contain only addresses on your verified domain.
  • The <body> tag is required to display the HTML content in case you are using the <html> tag. We won't accept an email without the <body> tag when the <html> tag is present.

Supported headers

We accept these headers:

  • standard "From", "To", "CC", "BCC", "Reply-To", "Subject" header (but they may be changed due to substitutions and other implementation details described above)
  • "List-Unsubscribe", "List-Subscribe", "List-Help", "List-Owner" and "List-Archive" headers are accepted in two cases:
    • either you have requested earlier and tech support has approved full removal of unsubscribe links for user_id/project_id used as SMTP login
    • or you have requested earlier and tech support has approved dynamic removal of unsubscribe links for given user_id/project_id AND you have passed skip_unsubscribe=1 parameter in X-UNIONE header
  • headers starting with "X-" are left "as is", with a limit of 50 headers.

All other headers are stripped out.

Response

After the sending SMTP API returns Id which can be used as a value of job_id in webhooks.