Transactional SMTP

Client-side Configuration

For your website or other system to send Transactional Emails through Maxemail, set your SMTP delivery details to the following:

  • Transactional Server: trx.mxmfb.com
  • Authentication: Use the email address and password of the relevant customer-level user.
  • Connection Ports:
    • 587 (recommended)
    • 465 (legacy)
    • 25 (compatibility)

Recommendation

ESMTPS on port 587 is recommended, using the STARTTLS command.

SMTPS on port 465 is provided for legacy purposes, for clients that do not support STARTTLS. SMTPS connections require SSL negotiation before any mail data is exchanged.

Port 25 is provided for systems that do not allow port configuration, but STARTTLS is still required as encryption is enforced.


If you are developing a process using .NET, the .NET SmtpClient does not support an SSL session up front for port 465 - so the EnableSSL property is actually a bit deceiving (see http://msdn.microsoft.com/en-us/library/system.net.mail.smtpclient.enablessl.aspx).

It will work with EnableSSL if you connect on port 587, where it establishes a plain text connection and issues the STARTTLS command to begin an SSL session.

Sender Requirements

The email address used as your SMTP sender (ie. for the MAIL FROM command) must match with the allowed domains configured for your customer space. This address will then be used in the email's From header, overwriting any existing value. Where the existing value has an alias, the alias will be maintained. The final email's SMTP sender and Return-Path email header will be set to Maxemail, to enable bounce management.

Example


Email from client to Maxemail

Email from Maxemail to recipient

SMTP sender / MAIL FROM / Return-Path header

outgoing@oxfordstones.com

trx-123-123-123@mxm.mxmfb.com

From address header

Oxford Stones <newsletters@oxfordstones.com>

Oxford Stones <outgoing@oxfordstones.com>

Recipient Requirements

Certain requirements must be satisfied in order to send email via Maxemail's SMTP service.

  • Only one recipient can be listed in the email's To header. Any additional recipients in the to, cc or bcc header will be discarded
  • The recipient listed in the To header must exist in the SMTP RCPT TO command
  • Of the remaining recipients listed in the RCPT TO command, the first will be used as a BCC recipient, and any others discarded
  • Any BCC recipient will get an email rendered as though for the To recipient but without any tracking

Response

Any errors in the SMTP request will be returned as an SMTP error with a 4xx or 5xx response code.

A valid request will return a unique identifier for this Transactional Email send, as a string. This string will be included in any Transactional reports.

Additional options

Additional settings can be configured per email sent to the SMTP server, by setting special header values in your email data payload.

Flags

Flags allow tracking and delivery options to be controlled per email. If this header is set, it overrides the options set per customer space and/or from address.

  • The header is called X-Mxm-Flags
  • The value is a bitwise integer, see the table below for values
  • Only one header should be set
    • If multiple are defined the first is used and subsequent entries are ignored

Bitwise value

Description

1

Enable open tracking

2

Enable click-through tracking

4

Enable Master Unsubscribe List check

8

Ignore Master Bounce List check

Example

Track opens and clicks:

X-Mxm-Flags: 3

Tags

Multiple Transactional Email tags can be added to each email by use of a header, allowing filtering of reports by one or more tags.

  • The header is called X-Mxm-Tag
  • The value is treated as text
  • Comma separates individual tags
  • Whitespace is stripped
  • Multiple headers can be set, each set of header values will be appended to any tags already defined.

Example

Multiple tags in a single header:

X-Mxm-Tag: order,confirmation,guest

Multiple tags in multiple headers:

X-Mxm-Tag: order
X-Mxm-Tag: confirmation
X-Mxm-Tag: guest