6.4. HTTP submission

Halon supports message submission through a HTTP API. This HTTP API allows you to submit messages directly to the EOD data hook. This API should be used to submit messages generated from a message generation platform, only doing slight modifications such as adding headers, or performing DKIM signing etc. HTTP submission endpoints are configured as servers in the startup configuration.

Note

If you need something more powerful that supports message generation and text substitutions using the Handlebars templating language as well as user engagement tracking see our extended HTTP submission API.

6.4.1. Endpoint reference

The only endpoint currently available on the HTTP API is /v1/submission.

6.4.1.1. Authentication

Authentication is done by using a X-API-Key HTTP header.

6.4.1.2. HTTP request format

Message injection is done by sending a POST request with two named multipart/form-data parts. Optional gzip compression is supported, if the parts are named options.gzip and rfc822.gzip respectively.

• options (application/json)

This should be a JSON object containing sender and recipients information as well as an optional metadata properties (this properties appears JSON decoded in the EOD hook as $arguments["metadata"]). The sender and recipients domain support internationalized domain names (U-labels).

{
    "sender": { "localpart": "sender", "domain": "example.com" },
    "recipients": [
        {"localpart": "recipient1", "domain": "example.org" },
        {"localpart": "recipient2", "domain": "example.org" }
    ],
    "metadata": { "jobid": "xyz" }
}

• rfc822 (message/rfc822)

This part should be a RFC822 formatted message.

Subject: Hello

Hello World

6.4.1.3. HTTP response format

On success a JSON object with the result will be returned. The output is not pretty printed unless the query string ?pretty=true is given.

{
    "result": {
        "code": 250,
        "enhanced": [
            2,
            0,
            0
        ],
        "reason": [
            "Ok: queued as 7c9e67bb-661f-4ccb-b8ee-521a0e723324"
        ]
    },
    "transaction": {
        "id": "7c9e67bb-661f-4ccb-b8ee-521a0e723324"
    },
    "metadata": {
        "foo": "bar"
    }
}

6.4.2. Examples

This is an example how to use curl to inject a message.

$ curl --request POST \
    --header "X-API-Key: badsecret" \
    --form "[email protected];type=application/json" \
    --form "[email protected];type=message/rfc822" \
    http://127.0.0.1:80/v1/submission?pretty