SMTP API

SMTP allows sending up to 5000 emails per hour using single connection, and with 10 maximum permitted connections it could be up to 50 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).

  • port: 25, 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.

  • username: user_id (you can see it in upper left corner of the screen under your email after login) or project_id (you can get it by project/createproject/get or project/list method).

  • password: API key of your account or project_api_key (you can get it by project/createproject/get or project/list method)

  • 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",
  "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"
global_language Optional string Language used for unsubscribe footer and unsubscribe page interface. "en" by default. 
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 - 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.

 

Implementation details

  • 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 unsubscribed/check and unsubscribed/list methods.
  • Also note that all recipients mentioned in "To:", "CC:", "BCC:" headers will receive separate copy of email and each copy will be counted as a separate email according to you subscription plan. All merge tags from global_substitutions parameter will be applied equally to each copy, so there's no reason to use multiple "To:" email addresses if you want to personalize emails with substitutions, you should just send separate emails.
  • 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.