# Halon HTTP submission Version: 2.2-stable This is an extended version of the built-in [HTTP submission](https://docs.halon.io/manual/http_submission.html) available in [Halon](https://docs.halon.io/manual). It provides support for message generation and text substitutions using the [Handlebars](https://handlebarsjs.com) templating language as well as user engagement [tracking](#tracking). See the [examples](#examples) section for some examples on what is possible to do using this API. ## Table of contents * [Installation](#install) * [Distributions](#install:distributions) * [Ubuntu](#install:ubuntu) * [RHEL](#install:rhel) * [Startup](#install:startup) * [Upgrade](#upgrade) * [Configuration](#config) * [Authentication directives](#config:authentication-directives) * [Listener directives](#config:listener-directives) * [Tracking directives](#config:tracking-directives) * [Other directives](#config:other-directives) * [Endpoint reference](#endpoint) * [Authentication](#endpoint:authentication) * [HTTP request format](#endpoint:http-request-format) * [HTTP response format](#endpoint:http-response-format) * [Examples](#examples) * [Tracking](#tracking) * [Installation](#tracking_install) * [Prerequisites](#tracking_install:prerequisites) * [Distributions](#tracking_install:distributions) * [Ubuntu](#tracking_install:ubuntu) * [RHEL](#tracking_install:rhel) * [Startup](#tracking_install:startup) * [Upgrade](#tracking_upgrade) * [Configuration](#tracking_config) * [Listener directives](#tracking_config:listener-directives) * [Secret directives](#tracking_config:secret-directives) * [Host directives](#tracking_config:host-directives) * [Queue directives](#tracking_config:queue-directives) * [Other directives](#tracking_config:other-directives) * [Environment directives](#tracking_config:environment-directives) * [Payload format](#tracking_payload) * [Events reference](#tracking_events) * [Click event](#tracking_events:click-event) * [Open event](#tracking_events:open-event) * [Unsubscribe event](#tracking_events:unsubscribe-event) * [Changelog](#changelog) # Installation The extended HTTP submission is installed using a Linux distribution package manager according to the corresponding instructions. It’s installed as a [native plugin](https://docs.halon.io/manual/plugins.html) for the *halon* process. ## Distributions ### Ubuntu To install the .deb package use the following commands. ```console # apt-get update # apt-get install halon-extras-http-submission ``` ### RHEL To install the .rpm package use the following commands. ```console # yum install halon-extras-http-submission ``` ## Startup When the initial [configuration](#config) is in place, the *halon* process can be restarted with: ```console # systemctl restart halon ``` # Upgrade In order to upgrade the package, install the new package over the previous installed one (see the installation chapter). After the upgrade the *halon* service needs to be restarted. # Configuration *halon* loads the non-reloadable configuration from the `plugins` section in `/etc/halon/smtpd.yaml`. It is described by, and can be validated with, the [submission.schema.json](http://lbovet.github.io/docson/index.html#https://docs.halon.io/json-schemas/submission/2.2-stable/submission.schema.json) [JSON schema](https://docs.halon.io/json-schemas/submission/2.2-stable/). ## Authentication directives ### apikeys[] List of allowed API keys for the HTTP server (sent in the *X-API-Key* header). ## Listener directives ### serverid Which `serverid` to use. The server should be of type `plugin`. **Required.** ### transportid Which `transportid` to use. The default is the one configured for the server in `smtpd-app.yaml`. ### port Which TCP port to listen on. **Required.** ### address IPv4 or IPv6 address to listen on. The default is to listen to all IPv4 and IPv6 addresses. ### pki The X.509 certificate and private key. The private key and certificate should have either a `path` or `data` property. ```yaml pki: certificate: data: |- -----BEGIN CERTIFICATE----- ... privatekey: data: |- -----BEGIN PRIVATE KEY----- ... ``` ### proxy[] Can either be a boolean or a list of IP addresses and subnets to trust as being reverse proxies. If it’s a boolean and it’s set to *true* it will trust all IP-addresses and subnets as being reverse proxies. ## Tracking directives ### tracking.click If click tracking should be enabled or not. The default is *false*. > **Note** > > This setting can be overriden in the HTTP request by setting the `tracking.click` property. > It can also be turned off for individual links by including the `tracking=off` attribute inside the anchor of a link **before** the `href`. ### tracking.open If open tracking should be enabled or not. The default is *false*. > **Note** > > This setting can be overriden in the HTTP request by setting the `tracking.open` property. ### tracking.unsubscribe If one-click list unsubscribe should be enabled or not. The default is *false*. > **Note** > > This setting can be overriden in the HTTP request by setting the `tracking.unsubscribe` property. ### tracking.url The base url that should be used for the rewritten links and tracking pixels. **Required.** > **Note** > > This setting can be overriden in the HTTP request by setting the `tracking.url` property. ### tracking.secret.id The ID of the secret that should be used to generate the hash of the tracking payload. This must be an integer between *1* and *254*. **Required.** ### tracking.secret.key The key for the secret that should be used to generate the hash of the tracking payload. **Required.** ## Other directives ### threads The amount of worker threads that should be started to handle incoming requests. The default is as many as there are CPU cores. ### maxsize The maximum request body size to accept. The default is 10 485 760 bytes. ### source Pass source information in the metadata. The default is *false*. # Endpoint reference The only endpoint currently available on the extended HTTP API is `/v1/submission`. ## Authentication Authentication is done by using a `X-API-Key` HTTP header. ## HTTP request format Message injection is done by sending a POST request containing a JSON object. Optional gzip compression is supported by setting the `Content-Encoding: gzip` HTTP header and then encoding the JSON payload before sending it. It is described by, and can be validated with, the [submission-request.schema.json](http://lbovet.github.io/docson/index.html#https://docs.halon.io/json-schemas/submission/2.2-stable/submission-request.schema.json) [JSON schema](https://docs.halon.io/json-schemas/submission/2.2-stable/). See the [examples](#examples) section for some examples. ## HTTP response format On success a JSON array containing the result for each recipient will be returned. The results will be sent out the same order as the recipients were sent in. > ```JSON > [ > { > "result": { > "code": 250, > "enhanced": [ > 2, > 0, > 0 > ], > "reason": [ > "Ok: queued as c720e1c5-cb5f-4a01-9b91-fd28b649c176" > ] > }, > "transaction": { > "id": "c720e1c5-cb5f-4a01-9b91-fd28b649c176" > }, > "metadata": { > "foo": "bar" > } > }, > { > "error": "Request timed out (connect)" > } > ] > ``` # Examples *This is an example how to use curl to inject a basic message with a text and html part as well as a custom header.* ```console curl http://127.0.0.1:80/v1/submission \ -H "Content-Type: application/json" \ -H "X-API-Key: badsecret" \ -d @- << EOF { "sender": { "localpart": "bounces", "domain": "example.com" }, "recipients": [ { "localpart": "john", "domain": "example.net" } ], "message": { "from": "Example ", "subject": "Hello World", "text": "Hello World", "html": "Hello World", "headers": { "X-Custom-Header": "My custom header" } } } EOF ``` *This is an example how to use curl to inject a message with text substitutions for two recipients.* ```console curl http://127.0.0.1:80/v1/submission \ -H "Content-Type: application/json" \ -H "X-API-Key: badsecret" \ -d @- << EOF { "sender": { "localpart": "bounces", "domain": "example.com" }, "recipients": [ { "localpart": "john", "domain": "example.net", "substitutions": { "name": { "first": "John", "last": "Doe" } } }, { "localpart": "jane", "domain": "example.net", "substitutions": { "name": { "first": "Jane", "last": "Doe" } } } ], "message": { "from": "Example ", "subject": "Hello {{ name.first }}", "text": "Hello {{ name.first }}", "html": "Hello {{ name.first }} {{ name.last }}" } } EOF ``` *This is an example how to use curl to inject a message with a text part, html part and an attachment.* ```console curl http://127.0.0.1:80/v1/submission \ -H "Content-Type: application/json" \ -H "X-API-Key: badsecret" \ -d @- << EOF { "sender": { "localpart": "bounces", "domain": "example.com" }, "recipients": [ { "localpart": "john", "domain": "example.net" } ], "message": { "from": "Example ", "subject": "Hello World", "text": "Hello World", "html": "Hello World", "attachments": [{ "name": "test.zip", "type": "application/zip", "data": "UEsDBBQACAAIABhEeFQAAAAAAAAAAAAAAAAIACAAVGVzdC50eHRVVA0AB6AePGKgHjxioB48YnV4CwABBPUBAAAEFAAAAAMAUEsHCAAAAAACAAAAAAAAAFBLAwQUAAgACAAYRHhUAAAAAAAAAACBAQAAEwAgAF9fTUFDT1NYLy5fVGVzdC50eHRVVA0AB6AePGKgHjxiqx48YnV4CwABBPUBAAAEFAAAAGNgFWNnYGJg8E1MVvAPVohQgAKQGAMnEBsxMDD6A2kgn7GRgSjgGBISBGGBdDCCGOg6WaDi/AwM4sn5uXqJBQU5qXohqRUlrnnJ+SmZeekQ/UB5BgEGBimEmpzE4pLS4tSUlMSSVOWAYKg98kDCA2gcQl1uYnIORA5klBQDgyhCrrA0sSgxryQzL5WhtCRN18La0NjEyNDc0sJkjpxNEkjTlQncMhB3irRe6Ths5Jk8nf2X1LFsy1jiggAdFOobGFgYWZsZGScbpiYaWIN9mpJZYs0AAFBLBwj/uAAV1QAAAIEBAABQSwECFAMUAAgACAAYRHhUAAAAAAIAAAAAAAAACAAgAAAAAAAAAAAApIEAAAAAVGVzdC50eHRVVA0AB6AePGKgHjxioB48YnV4CwABBPUBAAAEFAAAAFBLAQIUAxQACAAIABhEeFT/uAAV1QAAAIEBAAATACAAAAAAAAAAAACkgVgAAABfX01BQ09TWC8uX1Rlc3QudHh0VVQNAAegHjxioB48YqsePGJ1eAsAAQT1AQAABBQAAABQSwUGAAAAAAIAAgC3AAAAjgEAAAAA" }] } } EOF ``` *This is an example how to use curl to inject a message with an image embedded in the html part.* ```console curl http://127.0.0.1:80/v1/submission \ -H "Content-Type: application/json" \ -H "X-API-Key: badsecret" \ -d @- << EOF { "sender": { "localpart": "bounces", "domain": "example.com" }, "recipients": [ { "localpart": "john", "domain": "example.net" } ], "message": { "from": "Example ", "subject": "Hello World", "html": "", "attachments": [ { "type": "image/png", "cid": "80a3ddf7-2874-44b9-8e44-33ae575eb95b", "data": "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" } ] } } EOF ``` # Tracking The extended HTTP submission supports rewriting URL:s and adding tracking pixels to track user engagement. To simplify integration with these rewritten URL:s and tracking pixels we also provide an optional tracking service that can be used to handle the incoming HTTP requests for these, generate webhook [events](#tracking_events) and finally redirect the user. If you prefer to handle this part yourself, see the [payload format](#tracking_payload) section. * [Installation](#tracking_install) * [Prerequisites](#tracking_install:prerequisites) * [Distributions](#tracking_install:distributions) * [Ubuntu](#tracking_install:ubuntu) * [RHEL](#tracking_install:rhel) * [Startup](#tracking_install:startup) * [Upgrade](#tracking_upgrade) * [Configuration](#tracking_config) * [Listener directives](#tracking_config:listener-directives) * [Secret directives](#tracking_config:secret-directives) * [Host directives](#tracking_config:host-directives) * [Queue directives](#tracking_config:queue-directives) * [Other directives](#tracking_config:other-directives) * [Environment directives](#tracking_config:environment-directives) * [Payload format](#tracking_payload) * [Events reference](#tracking_events) * [Click event](#tracking_events:click-event) * [Open event](#tracking_events:open-event) * [Unsubscribe event](#tracking_events:unsubscribe-event) # Installation The tracking part of the extended HTTP submission is installed using a Linux distribution package manager according to the corresponding instructions, or by manually copying the files to the `/opt/halon/submission-tracking` directory. ## Prerequisites A [Redis](https://redis.io) server running either locally or externally. See the [`redis.host`](#tracking_config:confval-redis.host) setting for more information. ## Distributions ### Ubuntu To install the .deb package use the following commands. ```console # apt-get update # apt-get install halon-submission-tracking ``` ### RHEL To install the .rpm package use the following commands. ```console # yum install halon-submission-tracking ``` ## Startup When the initial [configuration](#tracking_config) is in place, the program can be started with: ```console # systemctl start halon-submission-tracking ``` # Upgrade In order to upgrade the package, install the new package over the previous installed one (see the installation chapter). After the upgrade the service will be stopped and requires to be manually started. # Configuration *halon-submission-tracking* loads the non-reloadable configuration from `/etc/halon/submission-tracking.yaml`. It is described by, and can be validated with, the [submission-tracking.schema.json](http://lbovet.github.io/docson/index.html#https://docs.halon.io/json-schemas/submission-tracking/2.2-stable/submission-tracking.schema.json) [JSON schema](https://docs.halon.io/json-schemas/submission-tracking/2.2-stable/) (included in our [Visual Studio Code integration](https://docs.halon.io/manual/vscode.html)). The default startup configuration file in `/opt/halon/submission-tracking/share` can normally be used as a base: ```console # cp /opt/halon/submission-tracking/share/submission-tracking.yaml /etc/halon/ ``` ## Listener directives ### listeners[] One or more listen directives needs to be configured which specify which TCP port and address to listen on. **Required.** ### listeners[].port Which TCP port to listen on. **Required.** ### listeners[].address IPv4 or IPv6 address to listen on. The default is to listen to all IPv4 and IPv6 addresses. ### listeners[].pki The X.509 certificate and private key. The private key and certificate should have either a `path` or `data` property. ```yaml pki: certificate: data: |- -----BEGIN CERTIFICATE----- ... privatekey: data: |- -----BEGIN PRIVATE KEY----- ... ``` ### listeners[].proxy[] A list of IP addresses and subnets to trust as being a reverse proxy. ## Secret directives ### secrets[] One or more secrets needs to be configured which are used to validate the hash of the tracking payload. **Required.** ### secrets[].id The ID of the secret that should be used to validate the hash of the tracking payload. This must be an integer between *1* and *254*. **Required.** ### secrets[].key The key for the secret that should be used to validate the hash of the tracking payload. **Required.** ## Host directives ### hosts[] One or more host directives needs to be configured which specify the webhook event receiver node(s). **Required.** ### hosts[].port Which TCP port to connect to. **Required.** ### hosts[].address Hostname, IPv4 address or IPv6 address to connect to. **Required.** ### hosts[].path The URL path. The default is `/`. ### hosts[].tls.enabled If TLS should be used for the requests. The default is *false*. ### hosts[].tls.verify If the server certificate should be verified. The default is *true*. ### hosts[].apikey The API key that will be used for the requests (sent in the *X-API-Key* header). ## Queue directives ### queues.timeout.connect The connect timeout (in seconds) against the webhook event receiver node(s). The default is 30. ### queues.timeout.socket The socket timeout (in seconds) against the webhook event receiver node(s). The default is 900. ### queues.retry.interval The interval (in seconds). The default is 0 (No interval). ### queues.retry.count The retry count. The default is 0 (No retries). ### queues.min_items Minimum items to send in bulk request. The default is 1. > **Note** > > This value is unique to each worker (child process). ### queues.max_items Maximum items to send in bulk request. The default is 1. > **Note** > > This value is unique to each worker (child process). ### queues.max_interval Maximum time to wait for [`queues.min_items`](#tracking_config:confval-queues.min_items) (in seconds). The default is to wait indefinitely. > **Note** > > This value is unique to each worker (child process). ## Other directives ### workers The amount of child processes that should be started to handle incoming requests. The default is as many as there are CPU cores. ### redis.host The hostname or IP of the redis server. The default is *localhost*. ## Environment directives ### environment.privdrop.user ### environment.privdrop.group # Payload format Below is a description of the payload format used for the rewritten URL:s and tracking pixels. This is only relevant if you want to implement a custom tracking service rather than the one we provide, otherwise, see the [events](#tracking_events) section. The payload format is a [base64url](https://en.wikipedia.org/wiki/Base64#URL_applications) encoded string where: * The first byte is the [`tracking.secret.id`](#config:confval-tracking.secret.id). * The next 32 bytes is a HMAC SHA-256 hash of the tracking data using the [`tracking.secret.key`](#config:confval-tracking.secret.key). * All the bytes after this is for the tracking data which is a JSON object compressed using zlib DEFLATE (without an appended zlib header) in the following format: ```JSON { "r": "john.doe@example.com", "m": "<36e76ce2-b5a6-11ec-b8dd-000c292d8854@c568c9a1654f>", "u": "http://example.com/example/path", "a": {} } ``` > **Note** > > We also have a [HSL module](https://github.com/halon-extras/tracking) if you want to implement engagement tracking during SMTP submission as well. # Events reference Below are the events which are currently implemented for tracking user engagement. > > **Note** > > > > Events are sent in bulk as a JSON array. ## Click event A click event is generated when a user clicks on a link that has been rewritten in an email. It is described by, and can be validated with, the [submission-tracking-click.schema.json](http://lbovet.github.io/docson/index.html#https://docs.halon.io/json-schemas/submission-tracking/2.2-stable/submission-tracking-click.schema.json) [JSON schema](https://docs.halon.io/json-schemas/submission-tracking/2.2-stable/). > ```JSON > { > "type": "click", > "event_id": "325128fc-b5a6-11ec-b8dd-000c292d8854", > "timestamp": "1649248573401", > "recipient": "john.doe@example.com", > "message_id": "<36e76ce2-b5a6-11ec-b8dd-000c292d8854@c568c9a1654f>", > "ip": "1.2.3.4", > "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.3 Safari/605.1.15", > "url": "http://example.com/example/path", > "additional": {} > } > ``` ## Open event An open event is generated when a user loads the tracking pixel in an email. It is described by, and can be validated with, the [submission-tracking-open.schema.json](http://lbovet.github.io/docson/index.html#https://docs.halon.io/json-schemas/submission-tracking/2.2-stable/submission-tracking-open.schema.json) [JSON schema](https://docs.halon.io/json-schemas/submission-tracking/2.2-stable/). > ```JSON > { > "type": "open", > "event_id": "3f01df67-b5a6-11ec-b8dd-000c292d8854", > "timestamp": "1649248582414", > "recipient": "john.doe@example.com", > "message_id": "<469c01df-b5a6-11ec-b8dd-000c292d8854@c568c9a1654f>", > "ip": "1.2.3.4", > "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.3 Safari/605.1.15", > "additional": {} > } > ``` ## Unsubscribe event An unsubscribe event is generated when a user does a one-click list unsubscribe on an email. It is described by, and can be validated with, the [submission-tracking-unsubscribe.schema.json](http://lbovet.github.io/docson/index.html#https://docs.halon.io/json-schemas/submission-tracking/2.2-stable/submission-tracking-unsubscribe.schema.json) [JSON schema](https://docs.halon.io/json-schemas/submission-tracking/2.2-stable/). > ```JSON > { > "type": "unsubscribe", > "event_id": "3f01df67-b5a6-11ec-b8dd-000c292d8854", > "timestamp": "1649248582414", > "recipient": "john.doe@example.com", > "message_id": "<469c01df-b5a6-11ec-b8dd-000c292d8854@c568c9a1654f>", > "ip": "1.2.3.4", > "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.3 Safari/605.1.15", > "additional": {} > } > ``` # Changelog ## 2.2.1 Released 2026-11-17 - **Bug** Handle NUL bytes same way as built-in HTTP submission API - **Bug** Fix memory leak on error paths ## 2.2.0 Released 2026-07-07 - **Imp** Added `message.id` property to request to set custom `Message-ID` header - **Imp** Added `raw_headers` option - **Fix** Fixed issue where certain structured headers were encoded when they shouldn’t be ## 2.1.1 Released 2026-06-02 - **Fix** Fix encoding for non-ASCII address headers (From, To and CC) ## 2.1.0 Released 2026-05-19 - **Imp** Re-add option to pass source information ## 2.0.4 Released 2026-04-27 - **Fix** Updated third-party dependencies ## 2.0.3 Released 2026-03-23 - **Fix** Updated third-party dependencies ## 2.0.2 Released 2026-03-05 - **Fix** Updated third-party dependencies ## 2.0.1 Released 2025-12-10 - **Fixes** Use separate package for Node ## 2.0.0 Released 2025-11-26 - **Imp** Convert to native plugin instead of a separate service ## 1.8.2 Released 2024-07-25 - **Bug** Fix issue with HTML entities in redirected URL:s ## 1.8.1 Released 2024-05-03 - **Bug** Fix issue with events containing UTF-8 characters ## 1.8.0 Released 2024-04-17 - **Imp** Add one-click list unsubscribe feature ([`tracking.unsubscribe`](#config:confval-tracking.unsubscribe)) - **Sec** Upgraded bundled Node to 18.20.2 ## 1.7.0 Released 2024-02-14 - **Imp** Support using `email` property instead of `localpart` and `domain` for `sender` and `recipients` in HTTP request ## 1.6.0 Released 2023-11-24 - **Imp** Add support for AMP Email - **Imp** Bundle Node 18.18.0 LTS - **Bug** Fix issue with newlines and CID attachments ## 1.5.0 Released 2023-09-14 - **Imp** Add *X-Forwarded-For* setting - **Imp** Allow setting *proxy* setting to `true` to trust all IP-addresses and subnets as being reverse proxies ## 1.4.2 Released 2023-08-16 - **Imp** Improved memory management ## 1.4.1 Released 2023-05-15 - **Sec** Update dependencies to fix vulnerability alerts - **Imp** Bundle Node 16.20.0 LTS ## 1.4.0 Released 2023-03-10 - **Imp** Add support for reverse proxies ## 1.3.1 Released 2023-02-27 - **Bug** Never override source ## 1.3.0 Released 2023-02-24 - **Imp** Add option to pass source information ## 1.2.0 Released 2023-02-21 - **Imp** Add support for per recipient metadata and additional ## 1.1.1 Released 2023-02-08 - **Bug** Add tracking pixel at the end if no body tag is found ## 1.1.0 Released 2023-01-25 - **Imp** Use 7bit or quoted-printable encoding for HTML part rather than base64 when possible ## 1.0.2 Released 2022-10-18 - **Bug** Don’t generate build_id links ## 1.0.1 Released 2022-05-20 - **Bug** Fix race condition with privdrop in primary process ## 1.0.0 Released 2022-05-07 First release