metrics.md

title: "metrics" description: "Counts and rates. The machinemail metrics commands: arguments, flags, examples and the API routes they call." canonical: "https://machinemail.dev/docs/cli/commands/metrics"

metrics

Counts and rates. The machinemail metrics commands: arguments, flags, examples and the API routes they call.

Source: https://machinemail.dev/docs/cli/commands/metrics

Counts and rates.

Command Summary
metrics events Query events
metrics rates Query rates
metrics usage Query usage

Every command also takes the global flags.

metrics events

Query events.

Counts of events per event type over time, in buckets of --period seconds (default one day), over the last 24 hours unless --start and --end say otherwise. message.received includes its sub-types (spam, blocked, unauthenticated, quarantined). At most 100,000 events are counted per query.

Requires the metrics_read permission.

machinemail metrics events [flags]

Flags

Field Type Description
--inbox <inbox-id> string Only this inbox.
--pod <pod-id> string Only this pod.
-e, --event-types <value> string[] Event types to count: message.received, message.received.spam, message.received.blocked, message.received.unauthenticated, message.received.quarantined, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified (the default is all of them). message.received counts every inbound message, including the message.received.* sub-types, which are also reported under their own keys. Other values give a series of zeros. Repeat the flag for several values.
--start <time> string Start of the range. Default: 24 hours before --end. Default: 24 hours before --end.
--end <time> string End of the range. Default: now; a later time is clamped to now. Default: now.
--limit <n> integer Return at most this many points per series.
--descending boolean Newest point first.
--period <n> integer Bucket size in seconds, 1 to 86400. Default 86400 (one bucket per UTC day). The range may hold at most 1000 buckets. Default: 86400.

Examples

machinemail metrics events
machinemail metrics events --inbox agent@machinemail.dev

API

metrics rates

Query rates.

Rolling bounce and complaint rates. At each --period grid point: the bounced (or complained) messages over the preceding --window, divided by the messages sent over the same window, with the send count alongside. Defaults: the last 24 hours, --period 3600, --window 86400.

Requires the metrics_read permission.

machinemail metrics rates [flags]

Flags

Field Type Description
--inbox <inbox-id> string Only this inbox.
--pod <pod-id> string Only this pod.
--rate-types <value> string[] Rate types: bounce, complaint. Default: both. Another value is a 400. Repeat the flag for several values. Default: both.
--start <time> string Start of the range. Default: 24 hours before --end. Default: 24 hours before --end.
--end <time> string End of the range. Default: now; a later time is clamped to now. Default: now.
--limit <n> integer Return at most this many points per series.
--descending boolean Newest point first.
--period <n> integer How often a point is sampled, in seconds, 60 to 86400. Default 3600. The range may hold at most 1000 points. Default: 3600.
--window <n> integer How far back each point looks, in seconds: a whole multiple of --period, at most 2592000 (30 days). Default 86400 when that is a multiple of --period, otherwise --period. Default: 86400 when that is a multiple of --period.

Examples

machinemail metrics rates
machinemail metrics rates --inbox agent@machinemail.dev

API

metrics usage

Query usage.

Current usage in the scope. Usage history is not kept yet: each series has a single point, at --end, with the value now.

Requires the metrics_read permission.

machinemail metrics usage [flags]

Flags

Field Type Description
--inbox <inbox-id> string Only this inbox.
--pod <pod-id> string Only this pod.
--usage-types <value> string[] Usage types: storage_bytes, message_count, thread_count, inbox_count, pod_count, domain_count. Default: all. Another value is a 400. Repeat the flag for several values. Default: all.
--start <time> string Start of the range. Default: 24 hours before --end. Default: 24 hours before --end.
--end <time> string End of the range. Default: now; a later time is clamped to now. Default: now.
--limit <n> integer Return at most this many points per series.
--descending boolean Newest point first.
--period <n> integer Accepted for AgentMail compatibility; usage has no history, so there is one point whatever the period.

Examples

machinemail metrics usage
machinemail metrics usage --inbox agent@machinemail.dev

API