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.

• 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"]).

{
    "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 formated message.

Subject: Hello

Hello World

6.4.1.3. HTTP response format

On success a JSON object with the result will be returned.

{
    "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