Traffic
Every operation in this group: what it accepts, what it returns and the errors it can answer with.
Operations
What happened to every message at the edge of the workspace, one entry for each message and recipient at each step: the mail that arrived for your addresses and where it went, and the mail you sent and what the receiving server said. It is the Traffic tab of a domain in the app, kept for 30 days. Reading outbound entries needs emails:read and inbound ones threads:read.
GET/traffic
List traffic
Every step a message took in or out of the workspace, newest first. Inbound, each recipient of a message that arrived gets one entry saying where it went: filed in the inbox, spam, routed to a webhook, forwarded without a copy kept, refused with a bounce back to the sender, or dropped without one, and reason says why mail was refused or dropped. Outbound, each recipient of a message you sent or forwarded gets an entry for each answer from the receiving server: delivered, deferred while it keeps trying, bounced, complained, suppressed when it was never tried, rejected when it was refused before it left, and failed for a forward that could not be relayed. A deferred recipient is followed by a delivery or a bounce for the same message.
An entry never changes once it is written, and the same step always keeps the same id, so reading a page again is safe. Entries are kept for 30 days. The sender and the server's reply are stored encrypted and cannot be searched; filter by address, recipient, outcome, direction, domainId and the time instead.
A key with emails:read and no threads:read sees outbound entries alone, and one with threads:read alone sees inbound ones. A key or an app narrowed to particular addresses or domains sees the entries of the addresses it reaches and, for a whole domain it holds, every entry of that domain, including mail for addresses that do not exist.
Requires the emails:read scope, or threads:read in its place.
Query parameters
domainIdstringKeeps one domain, by the id
GET /domainsreturns. A domain of another workspace, or one a narrowed key does not reach, is a 404.directionstringinboundfor mail that arrived,outboundfor mail the workspace sent or forwarded. Left out, both, as far as the scopes reach.One of"inbound""outbound"outcomestringOne outcome or several separated by commas, such as
bounced,deferred:delivered,deferred,bounced,suppressed,complained,rejected,failed,forwarded,filed,spam,routed,refused,dropped,report. A name outside that list is a 422invalid_parameter.addressstringKeeps one of your addresses: the one the mail arrived for, or the one it was sent from. Case does not matter.
Up to 320 charactersrecipientstringKeeps one recipient, matched whole and without regard to case: the person you wrote to on an outbound entry, the address in the envelope on an inbound one.
Up to 320 characterssincestringKeeps entries at or after this ISO 8601 instant.
Formatdate-timeuntilstringKeeps entries before this ISO 8601 instant. It must be later than
since.Formatdate-timelimitintegerRows per page, 1 to 100.
At least 1At most 100Default25cursorstringThe previous page's
nextCursor, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400invalid_cursor.
Returns
A page of traffic, newest first.
Errors
- 404
not_found: thedomainIdnames no domain this key reaches.- 422
invalid_parameterfor an outcome, a direction or a time it cannot read.
The errors every operation can return400401403429500Error catalog
Also available in
- TypeScript
traffic.list()traffic.listAll()traffic.iterate()- Python
traffic.list()traffic.list_all()traffic.iterate()- Ruby
traffic.listtraffic.list_alltraffic.iterate- PHP
traffic->listtraffic->listAlltraffic->iterate- Go
Traffic.ListTraffic.ListAllTraffic.Iterate- Java
traffic().listtraffic().listAlltraffic().iterate- C#
Traffic.ListAsyncTraffic.ListAllAsyncTraffic.IterateAsync- CLI
nextmail traffic list- MCP
listTraffic
Objects
TrafficEventobject
objectstringRequired- One of
"traffic_event" idstringRequiredThe same step of the same message always has this id.
directionstringRequired- One of
"inbound""outbound" outcomestringRequiredInbound:
filed,spam,routed,forwarded,refused,dropped, orreportfor a DMARC report that was read. Outbound:delivered,deferred,bounced,complained,suppressed,rejected,forwardedandfailed.One of"delivered""deferred""bounced""suppressed""complained""rejected""failed""forwarded""filed""spam""routed""refused""dropped""report"reasonstringRequiredWhy mail was refused or dropped:
unknown_recipientfor an address that does not exist,address_limitsfor the limits of the address,blocked_sender,rulefor one of your rules,group_policyfor who may write to a group,unreadablefor a message that could not be read,too_largefor a forward over the size it can relay, andreport_refusedfor a DMARC report that was unreadable, about another domain, or over the limit the domain keeps.Can be nullOne of"unknown_recipient""address_limits""blocked_sender""rule""group_policy""unreadable""too_large""report_refused"categorystringRequiredHow the receiving side classed a bounce, a complaint or a delay, such as
Permanent/Generalorabuse.Can be nullstatusstringRequiredThe status code from the reply, enhanced (
5.1.1) when it carries one, otherwise the SMTP code (550).Can be nulldetailstringRequiredThe reply of the receiving server, or what went wrong, as written.
Can be nullsenderstringRequiredThe envelope sender of inbound mail, or your address on outbound mail.
Can be nullrecipientstringRequiredWho the step was for: the person you wrote to, or the address in the envelope of mail that arrived.
addressstringRequiredYour address the mail arrived for or was sent from, after aliases are resolved.
addressIdstringRequiredIts id, when the address exists.
Can be nulldomainstringRequiredYour domain the step belongs to.
domainIdstringRequired- Can be null
emailIdstringRequiredThe sent email, as
GET /emails/{id}reads it, or the message filed in the mailbox.Can be nullthreadIdstringRequiredThe thread the message belongs to.
Can be nullmessageIdstringRequiredThe Message-ID header.
Can be nullproviderMessageIdstringRequiredThe id the sending or receiving service gave the message, for a support request.
Can be nullsendingIpstringRequiredThe IP address the message left from.
Can be nullremoteMtastringRequiredThe IP address of the receiving server.
Can be nullreportingMtastringRequiredThe server that wrote the report.
Can be nullprocessingMsintegerRequiredHow long delivery took, from accepting the message to the answer, in milliseconds.
Can be nullverdictsobjectRequiredThe checks run on inbound mail as it arrived. Null on outbound entries.
Can be nullspfstringRequiredThe SPF verdict for the sender, such as
passorfail.Can be nulldkimstringRequiredThe DKIM verdict for its signature.
Can be nulldmarcstringRequiredThe DMARC verdict for the From domain.
Can be nullspamstringRequiredThe spam verdict of the scan.
Can be nullvirusstringRequiredThe virus verdict of the scan.
Can be nullarcstringRequiredThe ARC verdict for the chain of servers that forwarded the message on its way here:
passwhen every seal checks out,failwhen one does not,nonewhen it carried no ARC headers,temperrorwhen a seal could not be checked yet, and null for an entry written before ARC was checked.Can be null
sizeintegerRequiredThe size of the message in bytes.
Can be nullcreatedAtstringRequiredWhen the step happened.
Formatdate-time
TrafficEventListobject
objectstring- One of
"list" dataTrafficEvent[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Can be null
Google Workspace