|
| 1 | +--- |
| 2 | +title: "Enabling APIs & Message Generation" |
| 3 | +subtitle: "Momentum" |
| 4 | +version: "5.3" |
| 5 | +date: "June 2026" |
| 6 | +description: "How to enable the Transmissions REST API, SMTPAPI (SMTP engagement tracking), and Message Generation on an MTA-only Momentum 5.3 cluster — including msg_gen and smtpapi configuration and the OpenResty NGINX proxy setup." |
| 7 | +lastUpdated: "06/05/2026" |
| 8 | +--- |
| 9 | + |
| 10 | +# 1. Purpose |
| 11 | + |
| 12 | +Following the initial installation of Momentum 5.3 in an MTA-only configuration, the following features can be added and enabled by following this procedure: |
| 13 | + |
| 14 | +- 5.3 Transmissions REST API |
| 15 | +- Message Generation functionalities |
| 16 | +- SMTPAPI for SMTP Engagement Tracking |
| 17 | + |
| 18 | +These procedures can also be performed after an upgrade to Momentum 5.3 if the pre-upgraded installation had not already had them done in the previous version. |
| 19 | + |
| 20 | +# 2. Important Caveats |
| 21 | + |
| 22 | +Before 4.2.31, the transmissions API and message generation functionality required the use of the Cassandra database. |
| 23 | + |
| 24 | +The elimination of Cassandra has the following feature implications, compared to previous releases: |
| 25 | + |
| 26 | +- Tags are not supported. They will be ignored by the Transmissions API and SMTPAPI. |
| 27 | +- Scheduled generation is not supported. Generation times set in the future will be rejected by the Transmissions API. |
| 28 | +- The use of stored templates or stored recipient lists is not supported. They will be rejected by the Transmissions API. Consequently, neither the Templates API nor the Recipient Lists API is supported. All transmissions must use an inline recipient(s) and an inline template. |
| 29 | +- No authentication, nor support for API keys. The Transmissions API will not be authenticated. |
| 30 | + |
| 31 | +As mentioned above, the transmissions API is not authenticated in the default installation. Additionally, if you enable the SMTPAPI for Engagement Tracking, you need to allow the click and open HTTP requests to the servers. This may require firewall or external router configuration outside of the scope of this document. For our purposes below, we will assume that port 80 on each MTA is accessible only internally and is used exclusively for the Transmissions API submissions over HTTP. If you are enabling Engagement tracking, you will need to map an external IP and port to the internal port 81, which will be used only for clicks and opens over HTTP. |
| 32 | + |
| 33 | +> **Note:** Since the Transmissions API does not require authentication and the Engagement Tracking requires inbound connections from the Internet, you are strongly advised to consult your IT support staff to ensure that only internal connections can be made to the Transmissions API and that external connections can only access an alternate listener (e.g., port 81 below). |
| 34 | +
|
| 35 | +# 3. Enable Message Generation |
| 36 | + |
| 37 | +## 3.1. Update the Configuration on the First Node |
| 38 | + |
| 39 | +1. Copy the **msg_gen.conf** sample configuration file to the appropriate location. |
| 40 | + |
| 41 | + ```bash |
| 42 | + cp /opt/msys/ecelerity/etc/sample-configs/default/msg_gen.conf \ |
| 43 | + /opt/msys/ecelerity/etc/conf/default/ |
| 44 | + ``` |
| 45 | + |
| 46 | +2. In the **/opt/msys/ecelerity/etc/conf/default/msg_gen.conf** file, edit the following lines in the **msg_gen** stanza: |
| 47 | + |
| 48 | + - Substitute your hostnames as appropriate. |
| 49 | + - If this is a single-node install, set **cluster_cfg = false**; otherwise, set it to **true**. |
| 50 | + - Engagement Tracking requires an active DNS name to be included in generated messages. This must resolve to a publicly accessible IP address and map to one or more of the Platform hosts. Replace `__EXTERNAL_DNS_HOSTNAME__` with this active DNS name. |
| 51 | + - In all configurations below, use your internal hostnames, not necessarily the same as public hostnames (if assigned). |
| 52 | + - The **mta_id** must be globally unique across the cluster and should not be changed after being configured initially. |
| 53 | + |
| 54 | + ``` |
| 55 | + msg_gen { |
| 56 | + engagement_tracking_host = "__EXTERNAL_DNS_HOSTNAME__:__EXTERNAL_PORT__" |
| 57 | + cluster_cfg = <true|false> |
| 58 | + node mta1.yourdomain.com { mta_id = 1 votes = 1 } |
| 59 | + node mta2.yourdomain.com { mta_id = 2 votes = 1 } |
| 60 | + ... |
| 61 | + node mtaN.yourdomain.com { mta_id = n votes = 1 } |
| 62 | + } |
| 63 | + ``` |
| 64 | +
|
| 65 | +3. Include **msg_gen.conf** in the **/opt/msys/ecelerity/etc/conf/default/ecelerity.conf** configuration file. Remove the comment character (#) from the existing line in `ecelerity.conf`: |
| 66 | +
|
| 67 | + ``` |
| 68 | + # include "msg_gen.conf" |
| 69 | + ``` |
| 70 | +
|
| 71 | +## 3.2. Configure Remaining MTA Nodes |
| 72 | +
|
| 73 | +1. Copy these config files to each MTA node in the cluster. |
| 74 | +
|
| 75 | + ```bash |
| 76 | + scp /opt/msys/ecelerity/etc/conf/default/msg_gen.conf \ |
| 77 | + mtaN.yourdomain.com:/opt/msys/ecelerity/etc/conf/default |
| 78 | + scp /opt/msys/ecelerity/etc/conf/default/ecelerity.conf \ |
| 79 | + mtaN.yourdomain.com:/opt/msys/ecelerity/etc/conf/default |
| 80 | + ``` |
| 81 | +
|
| 82 | +2. Restart **ecelerity** on all nodes: |
| 83 | +
|
| 84 | + ```bash |
| 85 | + sudo systemctl restart ecelerity |
| 86 | + ``` |
| 87 | +
|
| 88 | +# 4. Enable SMTPAPI |
| 89 | +
|
| 90 | +## 4.1. Update the Configuration on the First Node |
| 91 | +
|
| 92 | +1. Copy the **smtpapi.conf** file to the appropriate location: |
| 93 | +
|
| 94 | + ```bash |
| 95 | + cp /opt/msys/ecelerity/etc/sample-configs/default/smtpapi.conf \ |
| 96 | + /opt/msys/ecelerity/etc/conf/default/ |
| 97 | + ``` |
| 98 | +
|
| 99 | +2. Include **smtpapi.conf** in the **/opt/msys/ecelerity/etc/conf/default/ecelerity.conf** configuration file. Remove the comment character (#) from the line: |
| 100 | +
|
| 101 | + ``` |
| 102 | + # include "smtpapi.conf" |
| 103 | + ``` |
| 104 | +
|
| 105 | +3. Configure your ESMTP listener for outbound traffic to set up engagement tracking. Below is an example to set up a port 8025 listener for outbound traffic with open and click tracking turned on and HTTP links. Update **/opt/msys/ecelerity/etc/conf/default/ecelerity.conf** with the desired changes. This is an alternate injection port to the default port 25 listener. If you want to enable click/open tracking for all messages, add the following lines to the default port 25 stanza instead (everything inside the Listen context). |
| 106 | +
|
| 107 | + ``` |
| 108 | + Esmtp_Listener { |
| 109 | + Listen ":8025" { |
| 110 | + open_tracking_enabled = true |
| 111 | + click_tracking_enabled = true |
| 112 | + # Change this to your external DNS hostname and external port |
| 113 | + # number. This will appear in the tracked links. |
| 114 | + tracking_domain = "__EXTERNAL_DNS_HOSTNAME__:__EXTERNAL_PORT__" |
| 115 | + # HTTPS is also supported, but requires further configuration |
| 116 | + # and a TLS certificate valid for the external hostname. |
| 117 | + click_tracking_scheme = "http" |
| 118 | + open_tracking_scheme = "http" |
| 119 | + } |
| 120 | + } |
| 121 | + ``` |
| 122 | +
|
| 123 | +4. Test the configuration changes — this should display "OK", or an error message if there is a problem that needs correcting: |
| 124 | +
|
| 125 | + ```bash |
| 126 | + /opt/msys/ecelerity/bin/ec_console /tmp/2025 config reload |
| 127 | + ``` |
| 128 | +
|
| 129 | +5. Restart **ecelerity**: |
| 130 | +
|
| 131 | + ```bash |
| 132 | + sudo systemctl restart ecelerity |
| 133 | + ``` |
| 134 | +
|
| 135 | +## 4.2. Configure Remaining MTA Nodes |
| 136 | +
|
| 137 | +1. Copy these config files to each MTA node in the cluster. |
| 138 | +
|
| 139 | + ```bash |
| 140 | + scp /opt/msys/ecelerity/etc/conf/default/smtpapi.conf \ |
| 141 | + mtaN.yourdomain.com:/opt/msys/ecelerity/etc/conf/default |
| 142 | + scp /opt/msys/ecelerity/etc/conf/default/ecelerity.conf \ |
| 143 | + mtaN.yourdomain.com:/opt/msys/ecelerity/etc/conf/default |
| 144 | + ``` |
| 145 | +
|
| 146 | +2. Restart **ecelerity**: |
| 147 | +
|
| 148 | + ```bash |
| 149 | + sudo systemctl restart ecelerity |
| 150 | + ``` |
| 151 | +
|
| 152 | +# 5. Setup NGINX |
| 153 | +
|
| 154 | +Momentum uses [OpenResty NGINX](https://openresty.org/en/download.html). For Red Hat Enterprise Linux (RHEL) 8 and 9, the installation steps followed and tested with Momentum are [here](https://openresty.org/en/linux-packages.html#rhel). |
| 155 | +
|
| 156 | +> **Note:** If the procedure for enabling 5.3 Webhooks has already been performed on this cluster, NGINX has already been set up and configured. If that is the case, this entire section can be skipped now, and the procedure is complete. |
| 157 | +
|
| 158 | +> **Note:** By the time of the Momentum 5.3 release, there was no package available for RHEL 10; an **msys-openresty** package can be found at the [Message Systems Support](https://support.messagesystems.com/start.php) website for installation on that specific distro. |
| 159 | +
|
| 160 | +If you have **msys-nginx** installed, please uninstall it first. You can follow the **Upgrade Momentum Webhooks to 5.3** document to upgrade NGINX running on your box. |
| 161 | +
|
| 162 | +## 5.1. Install the Required Package |
| 163 | +
|
| 164 | +For every node you designate as an MTA, make sure OpenResty NGINX is installed. For instance, in a RHEL 9 node: |
| 165 | +
|
| 166 | +```bash |
| 167 | +sudo dnf list openresty |
| 168 | +``` |
| 169 | +
|
| 170 | +Your results should look like this: |
| 171 | +
|
| 172 | +``` |
| 173 | +Installed Packages |
| 174 | +openresty.x86_64 1.27.1.2-1.el9 @openresty |
| 175 | +``` |
| 176 | +
|
| 177 | +## 5.2. Configure NGINX |
| 178 | +
|
| 179 | +On MTA nodes, an NGINX process acts as an API proxy and load balancer for various API endpoints. In this section, you will configure NGINX for the MTAs. |
| 180 | +
|
| 181 | +> **Note:** OpenResty NGINX has its configuration located under **/usr/local/openresty/nginx**. If yours is different, you can use **sudo find / -name nginx.conf -print** to find the location used by your installation. |
| 182 | +
|
| 183 | +1. Copy the following files. |
| 184 | +
|
| 185 | + ```bash |
| 186 | + sudo mkdir -p /usr/local/openresty/nginx/conf.d /var/log/nginx |
| 187 | + cd /opt/msys/ecelerity/etc/sample-configs/nginx |
| 188 | + sudo cp -i conf/nginx.conf /usr/local/openresty/nginx/conf/ |
| 189 | + sudo cp -i conf/logrotate /etc/logrotate.d/openresty |
| 190 | + sudo cp -i web_proxy.conf /usr/local/openresty/nginx/conf.d/ |
| 191 | + sudo cp -i app.loc /usr/local/openresty/nginx/conf.d/ |
| 192 | + sudo cp -i momo.loc /usr/local/openresty/nginx/conf.d/ |
| 193 | + sudo cp -i default.cors /usr/local/openresty/nginx/conf.d/ |
| 194 | + sudo cp -i momo_upstream.conf /usr/local/openresty/nginx/conf.d/ |
| 195 | + # This will ask you if you want to overwrite the destination |
| 196 | + # file. It is safe to enter "y" here. It will overwrite a similar |
| 197 | + # sample configuration installed by the |
| 198 | + # msys-ecelerity-engagement-proxy package. |
| 199 | + sudo cp -i click_proxy_upstream.conf /usr/local/openresty/nginx/conf.d/ |
| 200 | + ``` |
| 201 | +
|
| 202 | + **If using or planning to enable webhooks**, copy the following file from the NGINX sample-configs: |
| 203 | +
|
| 204 | + ```bash |
| 205 | + sudo cp -i api_webhooks_upstream.conf /usr/local/openresty/nginx/conf.d/ |
| 206 | + ``` |
| 207 | +
|
| 208 | +2. For each of the following files, edit the associated "upstream stanza" to point to port 2081 on all MTA nodes. See the example below. |
| 209 | +
|
| 210 | + - `/usr/local/openresty/nginx/conf.d/click_proxy_upstream.conf` (port 2081) |
| 211 | + - `/usr/local/openresty/nginx/conf.d/momo_upstream.conf` (port 2081) |
| 212 | +
|
| 213 | + Example: |
| 214 | +
|
| 215 | + ``` |
| 216 | + cat /usr/local/openresty/nginx/conf.d/click_proxy_upstream.conf |
| 217 | + upstream click_proxy { |
| 218 | + server mta1.yourdomain.com:2081; |
| 219 | + server mta2.yourdomain.com:2081; |
| 220 | + ... |
| 221 | + server mtaN.yourdomain.com:2081; |
| 222 | + least_conn; |
| 223 | + } |
| 224 | + ``` |
| 225 | +
|
| 226 | +3. **If using or planning to enable webhooks**, edit **/usr/local/openresty/nginx/conf.d/web_proxy.conf**. Remove the comment character (#) from the line: |
| 227 | +
|
| 228 | + ``` |
| 229 | + # include "app.loc" |
| 230 | + ``` |
| 231 | +
|
| 232 | +4. **If using or planning to enable webhooks**, edit **/usr/local/openresty/nginx/conf.d/api_webhooks_upstream.conf** and add all of your MTA nodes to the **upstream** stanza: |
| 233 | +
|
| 234 | + ``` |
| 235 | + upstream api_webhooks { |
| 236 | + # List of all Webhooks api instances in the cluster: |
| 237 | + server mta1.yourdomain.com:2084; |
| 238 | + server mta2.yourdomain.com:2084; |
| 239 | + ... |
| 240 | + server mtaN.yourdomain.com:2084; |
| 241 | + least_conn; |
| 242 | + } |
| 243 | + ``` |
| 244 | +
|
| 245 | +## 5.3. Enable Click/Open Listener |
| 246 | +
|
| 247 | +If you are enabling the Click/Open listeners, you need to add a Listen stanza permitting NGINX to service the clicks and opens. You can add this to the **/usr/local/openresty/nginx/conf.d/web_proxy.conf** file or add a new **click_tracking.conf** file in the same directory. |
| 248 | +
|
| 249 | +``` |
| 250 | +server { |
| 251 | + listen 81; # need to be mapped from external port |
| 252 | + server_name _; |
| 253 | + more_set_headers 'Server: msys-http'; |
| 254 | + more_clear_headers 'X-Powered-By'; |
| 255 | + location /o { |
| 256 | + proxy_pass http://click_proxy; |
| 257 | + } |
| 258 | + location /q { |
| 259 | + proxy_pass http://click_proxy; |
| 260 | + } |
| 261 | + location /f { |
| 262 | + proxy_pass http://click_proxy; |
| 263 | + } |
| 264 | + location /robots.txt { |
| 265 | + access_log off; |
| 266 | + add_header Content-Type: text/plain; |
| 267 | + return 200 "User-Agent: *\nDisallow: /\n"; |
| 268 | + } |
| 269 | + location / { |
| 270 | + access_log off; |
| 271 | + return 404; |
| 272 | + more_set_headers "Content-Type: text/plain"; |
| 273 | + } |
| 274 | +} |
| 275 | +``` |
| 276 | +
|
| 277 | +## 5.4. Test the NGINX Configuration |
| 278 | +
|
| 279 | +```bash |
| 280 | +sudo openresty -t |
| 281 | +``` |
| 282 | +
|
| 283 | +Your results should look like this: |
| 284 | +
|
| 285 | +``` |
| 286 | +nginx: the configuration file /usr/local/openresty/nginx/conf/nginx.conf syntax is ok |
| 287 | +nginx: configuration file /usr/local/openresty/nginx/conf/nginx.conf test is successful |
| 288 | +``` |
| 289 | +
|
| 290 | +## 5.5. Start NGINX |
| 291 | +
|
| 292 | +```bash |
| 293 | +sudo systemctl restart openresty |
| 294 | +``` |
| 295 | +
|
| 296 | +## 5.6. Configure the Remaining MTA Nodes |
| 297 | +
|
| 298 | +1. Copy the NGINX configuration files to all the remaining MTA nodes. (`$PWD` is a Linux shell variable that always contains the current working directory, i.e., the equivalent of the response from the `pwd` command.) |
| 299 | +
|
| 300 | + ```bash |
| 301 | + cd /usr/local/openresty/nginx/conf |
| 302 | + scp nginx.conf mtaN.yourdomain.com:$PWD |
| 303 | + cd /etc/logrotate.d |
| 304 | + scp openresty mtaN.yourdomain.com:$PWD |
| 305 | + cd /usr/local/openresty/nginx/conf.d |
| 306 | + scp web_proxy.conf mtaN.yourdomain.com:$PWD |
| 307 | + scp app.loc mtaN.yourdomain.com:$PWD |
| 308 | + scp momo.loc mtaN.yourdomain.com:$PWD |
| 309 | + scp default.cors mtaN.yourdomain.com:$PWD |
| 310 | + scp momo_upstream.conf mtaN.yourdomain.com:$PWD |
| 311 | + scp click_proxy_upstream.conf mtaN.yourdomain.com:$PWD |
| 312 | + # and if using webhooks: |
| 313 | + scp api_webhooks_upstream.conf mtaN.yourdomain.com:$PWD |
| 314 | + ``` |
| 315 | +
|
| 316 | +2. Start NGINX on all the remaining MTA nodes. |
| 317 | +
|
| 318 | + ```bash |
| 319 | + # If NGINX was started previously, run restart instead of start |
| 320 | + sudo systemctl start openresty |
| 321 | + ``` |
0 commit comments