nextmail.analytics
Every method in this namespace: its signature, its parameters, what it returns and an example.
Methods
The numbers behind the Analytics page: how mail arrives in the mailbox, and what became of the mail the workspace sent.
analytics.mailbox()
Read how mail arrives
def mailbox( *, from_: datetime | str | None = None, to: datetime | str | None = None, offset_minutes: int | None = None, grain: TrackingGrain | None = None, address: str | None = None, api_key: str | None = None, timeout: float | None = None,) -> MailboxInsightsResourceReturns how mail arrives, as the Analytics page of the app shows it, for a window that is the last 30 days unless from_= and to= say otherwise: how many conversations arrived and when, per grain bucket in days and per hour of the day in hours, the addresses they arrived at, the senders who wrote most, how many conversations wait on a reply for 1, 3 or 7 days or more, and the folders.
days is sparse: a bucket in which nothing arrived has no entry, so a chart must fill the gaps. offset_minutes= shifts the boundaries so days and hours break where the reader's do, and series holds the per bucket counts of the top addresses and senders so each can be charted.
A key limited to particular addresses counts only the mail that arrived at them, and address= narrows everything to one address. An address the key does not reach counts nothing rather than failing.
Parameters
from_datetime | strThe start of the window, as a
datetimeor an ISO 8601 string. Defaults to 30 days beforeto. The SDK sends it as thefromquery parameter.todatetime | strThe end of the window, as a
datetimeor an ISO 8601 string. Defaults to now.offset_minutesintMinutes east of UTC, from -840 to 840, defaulting to 0. Pass
time.localtime().tm_gmtoff // 60for the local zone.grainTrackingGrainBucket width:
'minute','hour'or'day', defaulting to'day'.addressstrCount only the mail delivered to this address.
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
MailboxInsightsResource, a dict with object set to 'mailbox_insights', from, to, grain, offsetMinutes, scanned, days, hours, addresses, senders, senderCount, waiting, unattributed, folders and series.
Example
import time from nextmail import nextmail insights = nextmail.analytics.mailbox(offset_minutes=time.localtime().tm_gmtoff // 60) print(f'{insights["scanned"]} conversations from {insights["senderCount"]} senders') for sender in insights['senders']: print(sender['email'], sender['count'])Notes
Read only, so the SDK retries it after a network failure or a retryable status, like any other read.
A
from_later thantoraises a 422invalid_parameter.
Also available in
analytics.sending()
Read what became of sent mail
def sending( *, days: int | None = None, minutes: int | None = None, offset_minutes: int | None = None, grain: TrackingGrain | None = None, address: str | None = None, since: datetime | str | None = None, until: datetime | str | None = None, recipient: str | None = None, tag: str | None = None, api_key: str | None = None, timeout: float | None = None,) -> SendingAnalyticsResourceReturns the numbers behind the Analytics page of the app: what the workspace sent inside a window and what became of it. totals adds up the sends, recipients and test sends and how many were delivered, failed, bounced, complained about, uncertain or still pending, days cuts sent, delivered, failed, bounced and complained to grain buckets, and statuses, sources, streams, senders and suppressed break the window down.
The window is days=, 30 by default and at most 365, or minutes=, which wins when both are passed. It ends at until=, now by default, and starts at since= when that is passed, or else at the beginning of its oldest bucket. Both come back as since and until. offset_minutes= shifts the bucket boundaries so days break where the reader's do.
A key limited to particular addresses counts only the mail sent from them, and address= narrows everything to one address. recipient= and tag= narrow it further, to the mail that went to one address or carried one tag.
Parameters
daysintWindow length in days, from 1 to 365, defaulting to 30.
minutesintWindow length in minutes, which wins over
days.offset_minutesintMinutes east of UTC, from -840 to 840, defaulting to 0. Pass
time.localtime().tm_gmtoff // 60for the local zone.grainTrackingGrainBucket width:
'minute','hour'or'day', defaulting to'day'.addressstrCount only the mail sent from this address.
sincedatetime | strStart of the window, as a
datetimeor an ISO 8601 string, which wins overdays=andminutes=. A window spans at most 365 days.untildatetime | strEnd of the window, not included, defaulting to now.
since=afteruntil=is a 422invalid_parameter.recipientstrCount only the mail that went to this address, and only its delivery to that address.
tagstrCount only the mail sent with this tag:
namefor any value, orname:valuefor one value.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
SendingAnalyticsResource, a dict with object set to 'sending_analytics', since, until, grain, offsetMinutes, totals, days, statuses, sources, streams, senders and suppressed. totals holds sends, testSends, recipients, delivered, failed, bounced, complained, uncertain and pending.
Example
from nextmail import nextmail analytics = nextmail.analytics.sending(days=7)totals = analytics['totals'] print(f'{totals["delivered"]} of {totals["sends"]} delivered, {totals["bounced"]} bounced')Notes
Read only, so the SDK retries it after a network failure or a retryable status, like any other read.