Skip to main content
LoginTry Now
Momentum Documentation
Momentum 4.x
Momentum 3.x
Momentum Mobile
Changelog
Submit a Ticket
Community
Customers
Developer Blog
Developer Hub
Service Status
Momentum
Momentum 4.x
Modules Reference
smtpapi – SMTP Engagement Tracking

smtpapi – SMTP Engagement Tracking

Last updated March 2020

**Configuration Change. ** Engagement tracking for SMTP injections is available as of version 4.1-HF4.

The smtpapi module implements engagement tracking for SMTP injections and provides for open-tracked images and click-tracked links to be included in the message bodies.

Note

Message Generation is a licensed feature that must be configured in order to use SMTP Engagement Tracking. For more information, see “msg_gen – Message Generation”.

Configuration

To track engagement in SMTP messages, the smtpapi module must be included in the ecelerity.conf file, as follows:

smtpapi { }

The smtpapi module has the following dependencies:

  • cassandra_client – Used for tag storage (automatically loaded)

  • engagement_tracker – Handles the creation of open-tracked and click-tracked links and the corresponding parsing of the links when an open or click event occurs and determines if metadata is included in click tracking (automatically loaded)

    For additional information, see “engagement_tracker – HTTP Engagement Tracking”.

  • msys.rest.templates.lua – Provides functionality to render the tracking links into the message

  • substitution_engine – Required to substitute the rendered links into the message (automatically loaded)

  • httpsrv – Required for http server lua bindings

Hookpoint

The smtpapi module implements the post_validate_data_spool_each_rcpt hook to perform its message examination and transformations.

Enabling Engagement Tracking

In the default configuration, engagement tracking for SMTP injections is disabled and the associated configuration options are set to default values. To globally enable engagement tracking, change the default configuration. See “Configuration Options for Engagement Tracking”.

You can override the configuration for a specific message by specifying the attributes in an optional X-MSYS-API header or through policy by specifying the corresponding context variables. In these cases, the behavior is determined by the following order of precedence, from highest to lowest:

For example, if the smtpapi_open_tracking context variable is not specified, the open_tracking attribute in the X-MSYS-API header is used. If this attribute is also not specified, the value of the open_tracking_enabled configuration option is used.

While the configuration options for engagement tracking are not required when using the X-MSYS-API header or Lua Policy, the value of the configuration option will be used if the corresponding X-MSYS-API header field or context variable is not specified. This is especially important for tracking_domain, as the default value of "localhost:8080" is not appropriate for production environments.

Configuration Options for Engagement Tracking

When tracking engagement in SMTP messages, configure the following options or ensure that the default values meet your needs. For details about each option, including the associated context variables in Lua Policy and X-MSYS-API header fields, follow each link:

These options are valid in the esmtp_listener, listen, pathway, pathway_group, and peer scope.

Note

The smtpapi does NOT fallback to the msg_gen level configuration, and there are NO X-MSYS-API header fallbacks for click_tracking_scheme, open_tracking_scheme, tracking_domain, and tracking_link_expiry. Be sure to configure these options when using the X-MSYS-API header.

The following is an example configuration in the esmtp_listener scope:

ESMTP_Listener {
        SMTP_Extensions = (XREMOTEIP XDUMPCONTEXT XCLIENT XSETCONTEXT)
        Listen "127.0.0.1:8650" {
        }
        Listen "[::1]:8650" {}
        open_tracking_enabled = "false"
        click_tracking_enabled = "true"
}
Was this page helpful?