GreenArrow Email Software Documentation

HTTP Submission API

Overview

GreenArrow Engine provides an HTTP message submission API.

The information is provided to the API as a POST or PUT request of JSON content. (The header of content-type: application/json must be provided.)

The API provides a response of JSON content with a content type of application/json.

The uploaded information can be compressed using gzip or deflate compression. The header of Content-Encoding: gzip or Content-Encoding: deflate must be provided when doing this.

There is a size limit per submission.

To see the size limit on your server, check the post_max_size variable in the file /var/hvmail/apache/php/lib/php.ini

Authentication is performed by providing a username/password for an Email User, or the username api with an API key, in the JSON document.

The API is provided at /api/v1/send.json on your GreenArrow server’s HTTP service.

In order to maximize your injection speed, we strongly recommend use of batching (see the Request for Multiple Messages section of this document) and HTTP keep-alive.

Example

Example JSON document:

{
        "username":"[email protected]",
        "password":"test",
        "message":{
                "html":"html content goes <b>here</b>",
                "text":"text content goes here",
                "subject":"this is the subject",
                "to":[
                        {
                                "email":"[email protected]",
                                "name":"John Doe"
                        }
                ],
                "from_email":"[email protected]",
                "from_name":"Your Company"
        }
}

Example JSON reply for success:

{"success":1,"message_id":"[email protected]","result_reason":"success_immediate"}

Example JSON reply for failure:

{"success":0,"error":"no data in POST or PUT payload","result_reason":"request_error"}

or:

{"success":0,"error":"incorrect username\/password","result_reason":"request_error"}

The result_reason field is included on every response and on every per-message result inside a batch response. See Result Reason below for the full list of values and how to use it for retry decisions.

Submitting this request with curl:

cat <<'EOT' > post_body.txt
{
        "username":"[email protected]",
        "password":"test",
        "message":{
                "html":"html content goes <b>here</b>",
                "text":"text content goes here",
                "subject":"this is the subject",
                "to":[
                        {
                                "email":"[email protected]",
                                "name":"John Doe"
                        }
                ],
                "from_email":"[email protected]",
                "from_name":"Your Company",
                "mailclass":"trans",
                "headers":{
                        "X-foo":"bar"
                }
        }
}
EOT

curl -X POST -H "Content-Type: application/json" --data-binary @post_body.txt http://127.0.0.1/api/v1/send.json

The API can also be accessed through TLS:

(Remove the --insecure option if you have a valid TLS certificate.)

curl -X POST -H "Content-Type: application/json" --data-binary @post_body.txt --insecure https://127.0.0.1/api/v1/send.json

Compression

The content can be gzip or deflate compressed. This allows payloads with lots of messages to be reduced in size.

This requires the Content-Encoding: gzip or Content-Encoding: deflate header on the HTTP request.

Example:

cat <<'EOT' | gzip -c -9 > post_body.txt.gz
{
        "username":"[email protected]",
        "password":"test",
        "message":{
                "html":"html content goes <b>here</b>",
                "text":"text content goes here",
                "subject":"this is the subject",
                "to":[
                        {
                                "email":"[email protected]",
                                "name":"John Doe"
                        }
                ],
                "from_email":"[email protected]",
                "from_name":"Your Company",
                "mailclass":"trans",
                "headers":{
                        "X-foo":"bar"
                }
        }
}
EOT

curl -X POST -H "Content-Type: application/json" -H "Content-Encoding: gzip" --data-binary @post_body.txt.gz http://127.0.0.1/api/v1/send.json

Request Document

username

string

/

required

Email address of an email user or an Engine User, or api to authenticate with an API key.

password

string

/

required

Password for the user indicated by username, or the API key when username is api.

max_request_time

integer

/

optional

The maximum number of seconds to spend injecting messages before issuing a response. The actual request time may be slightly longer than this value, as this doesn’t account for network overhead and other latencies in generating the response.

Messages that are rejected due to this timeout will receive one of the following error messages:

not attempting because message injection has taken too long
not attempting because previous messages have taken too long

  • Must be an integer between 1 and 60 (inclusive).
  • Defaults to 31 seconds.
injection_method

string

/

optional

How GreenArrow gives the messages of this request to SimpleMH, the message processor that adds click and open tracking and DKIM signatures.

  • redis (default): GreenArrow adds each message to a queue in Redis, and returns its response when the message is in the queue. SimpleMH processes the queue. When the queue is full, GreenArrow waits for space, as Message Acceptance Throttling and Back-Pressure describes.
  • qmqp: GreenArrow gives each message to SimpleMH over QMQP, and returns its response when SimpleMH has processed the message and added it to the MTA’s queue. GreenArrow does not wait for space in the Redis queue. If SimpleMH rejects a message, the message fails with the message_validation_error result reason.

With qmqp, a message with individualize_messages: true fails with the error “individualized messages are not supported with injection_method "qmqp"”.

A request with any other value fails with the request_error result reason.

message

hash

/

required



This object can either be set directly to the message key, or you may provide the messages key with an array of these objects.

With individualize_messages: true, the message is a template. Where the rules of a field are different for a template, the field says so.

id

string

/

optional

Extra identifier for the message. This value is returned in the response in order to assist in mapping specific messages to responses. It is not otherwise used. It is not the same as the Message-ID header.

individualize_messages

boolean

/

optional

/

default: false

When true, the message is a template, and GreenArrow makes one message for each to recipient. See Individualized Messages. A value that is not a boolean is a validation error.

message_variables

hash

/

optional

Default values of the variables, for all recipients of a template. A recipient’s variables replace these values. See Individualized Messages. Without individualize_messages: true, this field is a validation error.

mime

string

/

optional

A fully-assembled RFC 5322 Internet Message Format message, including its own headers and body. Use this when you want to supply the complete message yourself instead of having GreenArrow assemble it from html, text, subject, from_email, and related fields.

GreenArrow does not validate the content of this field beyond verifying that it is a non-empty string.

When mime is specified:

  • The following fields are not allowed - specifying any of them is a validation error: html, text, amp_html, subject, to, cc, bcc, from_email, from_name, attachments, message_id_domain, headers. (With individualize_messages: true, to is allowed.)
  • envelope_recipients is required. (With individualize_messages: true, to is required instead, and envelope_recipients is not allowed.)
  • return_path may be specified to set the envelope sender. If omitted, the message is injected with a blank envelope sender (<> — the RFC 5321 null sender). If you’re using Bounce & FBL Handling, this will be overwritten.
  • mailclass and route may still be specified and behave the same as usual.

GreenArrow will:

  1. Normalize CRLF line endings to LF before injection.
  2. Append a trailing newline if the message does not already end with one.

When mime is used, the response will include a message_id field only if the message contains a Message-ID header whose value is enclosed in angle brackets (e.g. <[email protected]>). GreenArrow does not generate a Message-ID header in this mode.

html

string

HTML version of the content for the email message. Either the html or text key is required. Both may be specified.

text

string

Text version of the content for the email message. Either the html or text key is required. Both may be specified.

amp_html

string

AMP for Email version of the content for the email message. This cannot be the only part of the email (i.e. you must specify html and/or text in addition to amp_html).

subject

string

/

required

Subject line of the email.

envelope_recipients

array

/

optional

The list of envelope recipients to which to deliver this email.

Envelope recipients are the recipients, separate from the recipients specified in the email headers, to which the email will actually be delivered. They are the RFC5321.RcptTo addresses and are transmitted using the SMTP RCPT TO command.

If not specified (meaning the envelope_recipients key is missing or the value is null), then the email addresses specified in the to, cc, and bcc fields will be used as the envelope recipients.

Each entry in the list is a string representing an email address. If the domain name of the email address contains UTF-8 characters, it must be converted to Punycode prior to calling this API.

Not allowed with individualize_messages: true. The to addresses are then the envelope recipients.

to

array

/

required



List of To recipients.

These are used to create the To header of the email. And if envelope_recipients is not specified, then they are also included in the envelope recipients of the email.

With individualize_messages: true, each message gets a To header with only its own recipient, or the To header of the mime document. See Individualized Messages.

Each entry in the list is an object consisting of:

email

string

/

required

The recipient’s email address. If the domain name of the email address contains UTF-8 characters, it must be converted to Punycode prior to calling this API.

name

string

/

optional

The recipient’s name. This will appear in the To header. With individualize_messages: true, it must be a string.

The fields below are for individualized messages. Without individualize_messages: true, each one is a validation error.

variables

hash

/

optional

The values of this recipient’s variables. They take precedence over message_variables.

message_id

string

/

optional

The Message-ID of this recipient’s message: a msg-id in angle brackets, such as <[email protected]>. When it is absent, GreenArrow derives one from the Message-ID of the template. See Individualized Messages.

click_tracking_id

string

/

optional

The X-GreenArrow-Click-Tracking-ID of this recipient’s message: 1 to 300 printable ASCII characters, with no space at the start or end.

headers

hash

/

optional

Headers of this recipient’s message, as a hash of header name to value. Each header replaces all headers of the template that have the same name. A value must not contain a line break, except in a folded line. These names are not allowed, and they are not case-sensitive: To, Cc, Bcc, From, Message-ID, X-GreenArrow-Click-Tracking-ID, and each X-GreenArrow-INTERNAL-* name. When the message has a route, X-GreenArrow-MtaID and X-GreenArrow-Route are also not allowed.

cc

array

/

optional



List of CC (carbon copy) recipients.

These are used to create the Cc header of the email. And if envelope_recipients is not specified, then they are also included in the envelope recipients of the email.

Not allowed with individualize_messages: true.

Each entry in the list is an object consisting of:

email

string

/

required

The recipient’s email address. If the domain name of the email address contains UTF-8 characters, it must be converted to Punycode prior to calling this API.

name

string

/

optional

The recipient’s name. This will appear in the CC header.

bcc

array

/

optional

List of BCC (blind carbon copy) recipients.

If envelope_recipients is not specified, then these recipients are included in the envelope recipients of the email. Otherwise, they have no effect on the created email.

Each entry in the array is a recipient’s email address. If the domain name of the email address contains UTF-8 characters, it must be converted to Punycode prior to calling this API.

Not allowed with individualize_messages: true.

from_email

string

/

required

Email address to use in From header.

from_name

string

/

optional

Name to use in From header.

return_path

string

/

optional

Return-Path to use. This is also known as the bounce address and envelope sender. Note that this gets overwritten if SimpleMH is configured to set the Return-Path for you.

mailclass

string

/

default: The default Mail Class

Name of the SimpleMH Mail Class to use. This key has the same effect as the X-GreenArrow-MailClass header.

route

string

/

optional

/

CloudMTA only

Name or numeric ID of the Route to use for delivering the message. The Route is validated before injection — if the specified Route does not exist, the message will be rejected with an error. If both route and X-GreenArrow-MtaID are provided via the headers parameter, route takes precedence.

message_id_domain

string

/

optional

Fully qualified domain name to use in the domain portion of the Message-ID header generated by GreenArrow. This is typically the hostname of the system that generated the message. The domain listed in /var/hvmail/control/me is used by default. If the message that you inject already has a Message-ID header set, then it is left intact.

received_header

string

/

optional

Controls the Received header that is added to the message. Must be one of the following values:

  • none – Do not add a Received header.
  • show_source – Add the default Received header, which includes the injection source IP address.
    Received: from 1.2.3.4 by 5.6.7.8 with https;
     08 Mar 2026 14:52:52 +0000
    
  • hide_source – Add a Received header that does not include the injection source IP address.
    Received: by mail.example.com for <[email protected]>;
     08 Mar 2026 14:52:52 +0000 (envelope-from <[email protected]>)
    

If not specified, the system default behavior is used (controlled by the http_submission_api_received_header directive).

The domain used in the hide_source header is the domain of the message’s envelope sender at the time the header is written. This is typically the bounce domain configured in the Mail Class.

headers

hash

/

optional

Headers to add to the email. The key is the header name and the value is the raw text of the value of the header.

If either the Message-ID or Date headers are not provided, this API will automatically add these headers to the message.

The automatic Date header takes the form:

Date: 18 Feb 2021 14:52:52 -0000

The automatic Message-ID header takes the form:

Message-ID: <[email protected]>

See the message_id_domain field above for more information on how this domain can be set. When providing your own Message-ID, be sure to include the angled brackets around the value. This is the required format of the Message-ID header as defined in RFC 5322.

idempotence_key

string

/

optional

/

not available on CloudMTA

This parameter is not available on GreenArrow CloudMTA. A message that provides it there is rejected with the error “the idempotence_key parameter is not supported on this server”.

A caller-supplied string used to prevent duplicate message injection. When provided, GreenArrow records an MD5 hash of this value and retains it for the duration configured by http_submission_idempotence_retention_duration (default: 4 hours).

If a second request arrives with the same idempotence_key within the retention window, GreenArrow returns a successful response with "duplicate": 1 and "message_id": null without injecting a second copy of the message.

When idempotence_key is provided, the response always includes a duplicate field:

  • "duplicate": 0 — the message was accepted and injected normally.
  • "duplicate": 1 — the key was already seen; the message was not re-injected.

When idempotence_key is absent, the duplicate field is not included in the response.

With individualize_messages: true, a duplicate key queues no batch, so GreenArrow makes no messages for it.

While one request injects a message with a key, another request with the same key fails with the result reason duplicate_in_progress. Retry it: the retry returns "duplicate": 1 if the first request injected the message, and injects the message if the first request failed. If a request stops before it injects its message, its key is released after 2 minutes.

If GreenArrow cannot tell whether a request injected its message, for example because its connection to Redis or SimpleMH failed at that moment, the request fails with the result reason internal_error. Then requests with the same key fail with duplicate_in_progress until the retention window ends, so that a retry does not inject a second copy of the message.

Example response for a first (non-duplicate) injection:

{"success":1,"message_id":"[email protected]","duplicate":0}

Example response when the same key is submitted a second time:

{"success":1,"message_id":null,"duplicate":1}

attachments

array

/

optional



Attachments to add to the message. Each element in the array is an object consisting of:

filename

string

/

required

Name of the file to attach.

content_type

string

/

required

The content type, such as application/pdf.

content

string

/

optional

The raw content of the attachment. GreenArrow will base64 encode this value for you before attaching the file to the message. Exactly one of content or content_base64 must be specified.

content_base64

string

/

optional

The base64-encoded content of the attachment. GreenArrow will verify that this value can be base64 decoded before accepting it. Exactly one of content or content_base64 must be specified.

content_id

string

/

optional

Content-ID of the attachment. No default (not present in the generated message).

The Content-ID must be an email address that meets the msg-id EBNF definition from RFC5322.

Note: The Content-ID is defined in RFC2392, but no EBNF definition of the Content-ID header is provided in that RFC. It is described as akin to the Message-ID header. RFC5322 gives an EBFN definition of the Message-ID header, but not the Content-ID header. GreenArrow requires that the value of the Content-ID header meet the msg-id EBNF definition from RFC5322 (excluding the obsolete formatting options), which is the requirement for the value of the Message-ID header.

This value should be globally unique (for example, it might contain a UUID in the local part).

content_disposition

string

/

optional

Content-Disposition of the attachment. May be: inline, attachment

Defaults to inline.

allow_content_id_as_localpart_only

boolean

/

optional

When enabled, the content_id may be specified as just the localpart (without @domain). For example, you could use my-image instead of [email protected]. The Content-ID will still be validated against RFC5322 requirements for the localpart.

Individualized Messages

A message with individualize_messages: true is a template. GreenArrow queues it as one batch, and then makes one message from it for each to recipient. In each message, GreenArrow replaces the placeholders with the variables of its recipient. Each message goes only to its recipient.

{
        "username":"[email protected]",
        "password":"test",
        "message":{
                "individualize_messages":true,
                "subject":"Hey %recipient.first_name%, your plan renews soon",
                "text":"Hi %recipient.first_name%, your %recipient.plan% plan renews on %recipient.renews_on%.",
                "headers":{"List-Unsubscribe":"<https://example.com/u/%recipient.account_id%>"},
                "from_email":"[email protected]",
                "to":[
                        {
                                "email":"[email protected]",
                                "name":"Alice Adams",
                                "variables":{"first_name":"Alice","plan":"Pro","renews_on":"12 Oct 2026","account_id":"A-1001"}
                        },
                        {
                                "email":"[email protected]",
                                "variables":{"first_name":"Bob","plan":"Team","renews_on":"19 Oct 2026"}
                        }
                ],
                "message_variables":{"account_id":"unknown"}
        }
}

Recipients. Each message has one envelope recipient, to[i].email. When GreenArrow builds the message from html, text and the other fields, the To header of each message has only its recipient, with to[i].name. When the message is mime, the document keeps its own To header, with its placeholders replaced. Write To: %recipient% to address each message to its recipient. cc, bcc and envelope_recipients are not allowed.

Placeholders. %recipient.{name}% is replaced with the value of the variable {name}: from to[i].variables, or else from message_variables. %recipient% is replaced with to[i].email. Variable names are case-sensitive. A placeholder with no value does not change. The simplemh_batch_unresolved_placeholders_total metric counts these placeholders.

A value is written in the message as follows:

Value Text in the message
A string The string as it is. GreenArrow does not escape it, also in an HTML part.
A number The number, as PHP writes it: 1.50 is written as 1.5
true, false, null True, False, None
An object or an array Compact JSON. An empty object is written as [].

To put a value in HTML, escape it before you send it. To have a number written exactly as you write it, send it as a string, such as "1.50". %recipient.address.city% is not a nested name: it is replaced only by a variable called address.city. A value is not searched for placeholders.

Where placeholders are replaced. GreenArrow replaces placeholders in the header values of the message and in its text parts (text/* parts that are not attachments):

  • It decodes a quoted-printable or base64 part, replaces the placeholders, and encodes the part again. A 7bit or 8bit part, or a part with no Content-Transfer-Encoding, becomes quoted-printable. Each part that changes is written in UTF-8, and its charset becomes utf-8. A part with no placeholder does not change.
  • It finds placeholders in RFC 2047 encoded words. A header value that is not ASCII after the replacement is written as RFC 2047 encoded words, =?UTF-8?b?...?=. A long value has more than one.
  • In the address headers (From, Sender, Reply-To, To and Cc), it writes a value into a display name as it is, with no quotes, and encodes only a display name that is not ASCII.
  • It does not replace placeholders in attachments, in MIME parameters such as filename, or in X-GreenArrow-INTERNAL-* headers.

The fields of each recipient. GreenArrow writes to[i].message_id, to[i].click_tracking_id and to[i].headers into the recipient’s message after it replaces the placeholders. Each one replaces the headers of the same name. GreenArrow does not replace placeholders in these fields.

Without to[i].message_id, the Message-ID of the recipient’s message is 32 hexadecimal digits at the domain of the template’s Message-ID. It is different for each recipient, and the same each time GreenArrow makes that message. The template’s Message-ID is kept when it is not one msg-id in angle brackets, or when it has a placeholder. Then each message has the template’s Message-ID header, with its placeholders replaced. When a mime template has no Message-ID, its messages have none, unless the Mail Class has Add Message-ID if missing enabled.

The response. The response has one result for the template, as for any message. Its message_id reports the template’s Message-ID, not a list of recipient IDs. For a message built from fields, the generated ID is reported without angle brackets; a supplied bracketed Message-ID header is reported with them. For mime, the response reports only the text inside the angle brackets, and omits message_id if the document has no bracketed Message-ID. A recipient’s message shares the template’s Message-ID when GreenArrow keeps the header unchanged, or when that recipient’s to[i].message_id sets the same value. A placeholder in the template’s Message-ID is replaced for each recipient, so the delivered IDs may differ from the response. A successful result means that GreenArrow queued the batch, not that it made the messages.

Making the messages. GreenArrow makes the messages of each batch in the background, after the response. It makes up to simplemh_batch_workers batches at the same time. The queue of batches has the limits simplemh_batch_queue_max_batches and simplemh_batch_queue_max_memory. When the queue is at a limit, the API waits for space, as described in Message Acceptance Throttling and Back-Pressure. max_injection_size applies to the template.

When GreenArrow cannot make the messages of a batch, it tries again 5 times, with waits of 1, 2, 4, 8 and 16 seconds. After that, it keeps the batch in the Redis stream engine.simplemh-batch.failed for investigation, and counts it in the simplemh_batch_failed_total metric. The messages that it made before the failure are delivered.

An instance drain moves a batch that is still in progress to another instance. That instance starts at the first recipient, so recipients whose messages were already made may receive duplicates.

In a request for multiple messages. Each message of messages can set individualize_messages. Each template is its own batch. GreenArrow injects the other messages as usual.

Request for Multiple Messages

Up to 500 messages may be submitted per API request.

(Note: Not all messages in a request are guaranteed to be queued. A response will be provided within max_request_time seconds with as many messages as could be queued in that time. See the section “Message Acceptance Throttling and Back-Pressure” below.)

To submit multiple messages in a single request, provide a document like this:

{
        "username":"[email protected]",
        "password":"test",
        "messages":[
                {
                        "html":"html content goes <b>here</b>",
                        "text":"text content goes here",
                        "subject":"this is the subject",
                        "to":[
                                {
                                        "email":"[email protected]",
                                        "name":"John Doe"
                                }
                        ],
                        "from_email":"[email protected]",
                        "from_name":"Your Company"
                },
                {
                        "html":"html content goes <b>here</b>",
                        "text":"text content goes here",
                        "subject":"this is the subject",
                        "to":[
                                {
                                        "email":"[email protected]",
                                        "name":"Bob Smith"
                                }
                        ],
                        "from_email":"[email protected]",
                        "from_name":"Your Company"
                }
        ]
}

The JSON document most be an object with the following keys:

Key Description
username Same as single message document
password Same as single message document
messages A list containing one or more objects which contain the same information as the message key in a single message document.
injection_method Same as single message document

The output can be in two formats.

(1) An error that applies globally to the entire request:

{"success":0,"error":"incorrect username\/password"}

(2) Or the overall request succeeded and a specific success value is provided for each message:

{
        "success":1,
        "messages":[
                {
                        "success":1,
                        "message_id":"[email protected]",
                        "attempted":1,
                        "id":"1"
                },
                {
                        "success":1,
                        "message_id":"[email protected]",
                        "attempted":1,
                        "id":"2"
                }
        ]
}

If there is an internal error, then the subsequent messages in the request will not be attempted. For example:

{
        "success":1,
        "messages":[
                {
                        "success":1,
                        "message_id":"[email protected]",
                        "attempted":1,
                        "id":"1"
                },
                {
                        "success":0,
                        "error":"internal error: unable to make socket connection (Connection refused)",
                        "attempted":1,
                        "id":"2"
                },
                {
                        "success":0,
                        "error":"not attempting due to previous internal errors",
                        "attempted":0,
                        "id":"3"
                }
        ]
}

In this request of three messages, the second message encountered an internal error so the third message was not even attempted. The attempted key provides data on if the message was even attempted.

It is very important to handle error conditions and retry messages appropriately.

If the attempted value is 0 for a message, this lets you know that you should retry it.

Here are the two error messages that cause messages to not be attempted:

  • not attempting due to previous internal errors – a previous message encountered an internal error, so the rest of the messages in the batch are not attempted and return this error message. Please retry these messages in a different batch.

  • not attempting because previous messages have taken too long – this happens when the system is not able to pre-process messages as fast as you are trying to send them to this API (see Message Acceptance Throttling and Back-Pressure below). Only the messages that can be accepted within max_request_time seconds will be accepted, and the rest of the messages in the batch will not be attempted and return this error. This is put in place so that an HTTP timeout does not prevent you from getting any answer to the HTTP request.

For programmatic handling, see the result_reason field below; it lets you distinguish retryable failures (such as internal errors and aborts after throttling) from non-retryable failures (such as request and message validation errors) without parsing the human-readable error text.

Result Reason

Every per-message result and every top-level error response includes a result_reason field that summarizes the outcome of the request. Use it to decide whether to retry a failed message without having to pattern-match on the error text.

The same set of values is also emitted as the result label on the http_submission_api_injection_result_total metric.

success_immediate

The message was accepted and queued without having to wait due to backpressure.

Retryable: no - message was successfully injected

success_after_throttled

The message was accepted and queued, but only after waiting due to backpressure. See Message Acceptance Throttling and Back-Pressure.

Retryable: no - message was successfully injected

duplicate

The message was detected as a duplicate via the idempotence_key; it was not re-injected.

Retryable: no — message was previously injected

duplicate_in_progress

Another request is injecting a message with the same idempotence_key. This message was not injected.

Retryable: yes — the retry returns duplicate if the other request injected its message

aborted_after_throttled

GreenArrow stopped waiting on backpressure before this message could be queued; the request returned the not attempting because message injection has taken too long error.

Retryable: yes

message_validation_error

The message failed a per-message validation check (for example, a missing required field or an invalid email address).

Retryable: no — fix the message and re-submit

request_error

A problem with the overall request that is not a per-message validation error (for example, a missing/incorrect username/password, malformed JSON, or a missing top-level key).

Retryable: no — fix the request and re-submit

internal_error

An internal GreenArrow error occurred while handling the message.

Retryable: yes

skipped_batch_internal_error

A previous message in the same batch hit an internal_error; this message in the batch was skipped without being attempted.

Retryable: yes — re-submit in a different batch

skipped_batch_timeout

A previous message in the same batch caused the request to take too long; this message in the batch was skipped without being attempted.

Retryable: yes — re-submit, ideally with a smaller batch

HTTP keep-alive

For maximum speed, it is recommended to use HTTP keep-alive in your HTTP API, so that you re-use the same TCP connection for each new request.

This can have a significant performance impact because TCP slow-start is bypassed for subsequent requests.

Message Acceptance Throttling and Back-Pressure

Message batches may not be larger than 500 messages.

However, not all messages in a batch are guaranteed to be queued.

The HTTP API will queue as many messages as possible within max_request_time seconds and then provide a status response indicating which messages were queued. (This max_request_time seconds does not include network delay for transferring data.) The purpose of replying within max_request_time seconds is to prevent HTTP timeouts – which would prevent the caller from knowing whether messages were successfully queued or not.

This is how GreenArrow throttles how fast messages are accepted through the HTTP API so that they can not be accepted faster than messages are pre-processed (click/open tracking & DKIM signing) and added to the MTA’s ram-queue. This is a form of “back-pressure,” which is the MTA slowing down the message injection to the speed it can handle.

(Another common form of “back-pressure” is a fraction-of-a-second delay on accepting a message in an SMTP conversation, which has the effect of slowing down the overall speed of messages injection.)

Messages that were unable to be queued due to this limit will be returned with the not attempting because previous messages have taken too long error message (documented above). It is imperative that you re-submit messages returned with this (and the other) error messages documented above.

This error message is the MTA communicating that the batch size is too large.

Recommended batch size

We recommend that your batches be small enough to be accepted within 10 seconds.

There is little benefit to batches that take longer than 10 seconds to be accepted. (At this size, the per-batch overhead is a very small portion of the equation, and larger batches do not gain much if anything.)

There is no benefit (and only a cost) to attempting batches larger than can be handled within max_request_time seconds.

How many messages can be processed within 10 seconds depends on many things, for example: how many other senders are concurrently using the HTTP API, how many messages are currently being injected through other injection methods, and the overall capacity of the system.

We recommend either (a) using a conservative static batch size or (b) dynamically adjusting the batch size based on injection speed.

To dynamically adjust the batch size:

  • for the last batch, divide how many messages were accepted by how long the batch took, to calculate the messages per second speed.
  • multiply the messages per second speed by 10 to get the size of the next batch
  • if larger than 500, reduce to 500

How to observe back-pressure

If message acceptance is currently being throttled due to back-pressure, the size of the Simplemh processing queue in the hvmail_status status output will be above 90%.

Here is an example:

Simplemh processing queue:       98% used (  1960/  2000) (messages)
                                 99% used (    99/   100) (MB of memory)

For a template (individualize_messages: true), the Simplemh batch queue in the same output shows the back-pressure instead.

Logging API Calls

GreenArrow can write details about HTTP Submission API requests to the Apache error log. There are two logging modes available:

Log all requests: To log every API request (both successes and failures), set the file /var/hvmail/control/opt.send_api_debug_log to 1.

echo 1 > /var/hvmail/control/opt.send_api_debug_log

Log only failures: To log only API requests that result in errors, set the file /var/hvmail/control/opt.send_api_debug_log_failures to 1. This is useful for monitoring errors without the overhead of logging every successful request.

echo 1 > /var/hvmail/control/opt.send_api_debug_log_failures

A request is considered a failure if the top-level success field is 0, or if any individual message within a batch has success set to 0.

Both options may be enabled at the same time, though enabling opt.send_api_debug_log already includes failures.

Remove the files to disable logging to Apache’s error log:

rm -f /var/hvmail/control/opt.send_api_debug_log
rm -f /var/hvmail/control/opt.send_api_debug_log_failures

Apache error log is saved to /var/hvmail/apache/logs/error_log. Here is an example of what GreenArrow logs to Apache’s error log (JOSN objects formatted to improve readability):

[Tue Jun 29 08:08:19.707090 2021] [php7:notice] [pid 19557] [client 1.2.3.4:51269] 
http_send_api: 
input={
  "username": "[email protected]",
  "password": "test",
  "message": {
    "html": "html content goes <b>here</b>",
    "text": "text content goes here",
    "subject": "this is the subject",
    "to": [
      {
        "email": "[email protected]",
        "name": "John Doe"
      }
    ],
    "from_email": "[email protected]",
    "from_name": "Your Company",
    "mailclass": "trans",
    "return_path": "[email protected]"
  }
}
output={
  "success": 0,
  "error": "incorrect username/password"
}

  • input= is the JSON object sent to GreenArrow by the API client.
  • output= is the JSON object in the response from GreenArrow.

Copyright © 2012–2026 GreenArrow Email