Disk Queue Summary API
Overview
This API is used to query a summary of the contents of the GreenArrow Disk Queue.
Get the status of a send
GET /ga/api/v3/eng/disk_queue_summary
Parameters
group_by
string, default: virtualmta_injected
Specify the primary way to group messages in this report.
We offer two primary ways to group messages in the Disk Queue Summary report. GreenArrow doesn’t have a specific
queue for each IP address, instead it consists of one retry queue which we call the Disk Queue. In this queue structure,
each recipient will have an “injected VirtualMTA” – this is the MTA requested when the message was injected. This might be
a specific IP address, a Relay Server, a Routing Rule, or the Default VirtualMTA. Each recipient also has a “most recent VirtualMTA”,
this being the VirtualMTA that was used in the most recent delivery attempt.
If you, for example, have a Routing Rule per customer, and you want to see what email exists in the Disk Queue for that
customer, you’d want to look at the virtualmta_injected report. If, however, you want to see what IP address email is not
getting delivered quickly on, you’d want to look at the virtualmta_most_recent report for that IP.
|
virtualmta_injected
|
The VirtualMTA used during injection of the messages in the queue.
This is usually specified by either the Studio VirtualMTA setting,
the Mail Class VirtualMTA setting, or the X-GreenArrow-MtaID message header.
When paired with the throttle-based group_variant options, it makes sense
to have the same throttle and domain groupings across all of your IP addresses.
Otherwise, you may see some odd results as different combinations of throttle/domains
are grouped together.
|
|
virtualmta_most_recent
|
The VirtualMTA used for the most recent delivery attempt.
This includes all messages that had or would have had their most recent delivery attempt on this IP.
The size of a virtualmta_most_recent queue can reduce not because it is delivering successfully itself,
but because the messages get automatically retried through other IPs that are delivering, if allowed
by your configuration. For example, if you have a Routing Rule that splits deliveries between two IP
addresses, the first IP is having temporary delivery errors, and the second IP is successfully delivering –
in this case, the size of the virtualmta_most_recent queue on the first IP will reduce as messages get
delivered through the second IP when they come up for new delivery attempts.
|
|
group_variant
string, default: none
Specify the secondary way to group messages in this report.
|
none
|
No secondary grouping. Messages will only be grouped by group_by.
|
|
recipient_domain
|
Group messages by the recipient’s domain name.
|
|
all_throttles
|
Group messages by the throttling rule used for the most recent delivery attempt of this message.
Messages delivered using the default throttling rule (i.e. domains that aren’t explicitly matched on the outgoing IP or its throttling template)
will be included individually.
|
|
all_throttles_other
|
Group messages by the throttling rule used for the most recent delivery attempt of this message.
Messages delivered using the default throttling rule (i.e. domains that aren’t explicitly matched on the outgoing IP or its throttling template)
will be grouped together as OTHER.
|
|
only_explicit_throttles
|
Group messages by the throttling rule used for the most recent delivery attempt of this message.
Messages delivered using the default throttling rule (i.e. domains that aren’t explicitly matched on the outgoing IP or its throttling template)
will be excluded from this report.
|
|
not_explicit_throttles
|
Group messages by the throttling rule used for the most recent delivery attempt of this message.
Only messages delivered using the default throttling rule (i.e. domains that aren’t explicitly matched on the outgoing IP or its throttling template)
will be included in this report.
|
|
sort_by
string, default: num_messages_desc
Specify the order in which this report will be returned.
|
num_messages_desc
|
The number of messages (descending order).
|
|
num_messages_asc
|
The number of messages (ascending order).
|
|
avg_age_desc
|
Average age of messages (descending order).
|
|
avg_age_asc
|
Average age of messages (ascending order).
|
|
max_age_desc
|
Age of oldest message (descending order).
|
|
max_age_asc
|
Age of oldest message (ascending order).
|
|
limit
integer, default: 100
|
The maximum number of rows to include in this report. The report is sorted by descending number of messages.
|
Response
request
hash
The request used to generate the attached report. If a field was defaulted, the default value
will be included in this response.
group_by
string
|
Described above.
|
group_variant
string
|
Described above.
|
sort_by
string
|
Described above.
|
limit
integer
|
Described above.
|
|
report
array
mta
hash
The VirtualMTA used either for injection or delivery (depending on group_by). If this value is null,
that indicates that no VirtualMTA was selected at the time of injection and the default VirtualMTA was used.
This hash may represent an IP Address, Routing Rule, Relay Server, or Default VirtualMTA.
For group_by=virtualmta_most_recent, if this value is null, this means that the VirtualMTA
used for the most recent delivery attempt is not known. This can happen immediately after upgrading
to a version that includes this feature. This can also happen if a delivery attempt was aborted
in some way before the VirtualMTA was determined. In these cases, the UI will present these entries
as (not specified).
id
integer
|
The primary key of the VirtualMTA. This will be null for the Default VirtualMTA.
|
name
string
|
The name of the VirtualMTA. This will be Default VirtualMTA for the Default VirtualMTA.
This will be blank if the IP address has been deleted.
|
ip
string
|
The IP address of this VirtualMTA. This is only present if the VirtualMTA is an IP Address.
This will be blank if the IP address has been deleted.
|
|
domain
hash
This key is only present when group_variant=recipient_domain.
recipient_domain
string
|
The recipient domain.
|
|
throttle
hash
This key is only present for the throttle-based values of group_variant.
throttle_id
integer
|
The primary key of the throttle.
If this value is null, that indicates that no explicit throttling rule matched the recipient
domain and the default throttling rule was used. In this case, domains will contain either
the recipient domain or the string OTHER.
|
domains
string
|
The first three domains, wildcards, or mx: rules in the throttling rule, possibly with an
ellipsis ... appended if there are more not shown.
If group_variant=all_throttles_other, this may be OTHER. In that case, throttle_id=null.
If the IP address or throttling rule represented by this throttle key has been deleted,
throttle_id will remain its original value but domains will be the string (deleted).
|
|
stats
hash
num_messages
integer
|
The number of messages represented by this row of the report.
|
average_message_age
integer
|
The average message age (in seconds) for messages represented by this row of the report.
|
oldest_message_age
integer
|
The oldest message age (in seconds) for messages represented by this row of the report.
|
|
|
summary
hash
total_recipients_in_queue
integer
|
The total number of recipients awaiting delivery in the GreenArrow disk queue.
|
total_messages_in_queue
integer
|
The total number of messages awaiting delivery in the GreenArrow disk queue. This number may
be different than total_recipients_in_queue if a message is queued to deliver to multiple
recipients.
|
|
Example
GET /ga/api/v3/eng/disk_queue_summary
{
"success": true,
"data": {
"request": {
"group_by": "virtualmta_injected",
"group_variant": "none",
"limit": 100
},
"report": [
{
"mta": {
"id": 2,
"name": "ipaddr-haproxy",
"ip": "1.2.3.4"
},
"stats": {
"num_messages": 105040,
"average_message_age": 36280,
"oldest_message_age": 84448
}
},
{
"mta": null,
"stats": {
"num_messages": 17164,
"average_message_age": 84684,
"oldest_message_age": 84701
}
}
]
},
"error_code": null,
"error_messages": null
}
