Mail events
Events for mailboxes, messages, sends, tracking and suppressions, with the message object and sample payloads.
These events track an account's mailboxes and messages, your sends through the outbox, open and click tracking, and suppressions. For the envelope fields see Events.
The message object
message.created, message.updated, message.deleted and message.classified carry data.message, the message as indexed, and data.mailboxes, the mailboxes it is in. It is the same message summary that /reference/mail returns.
| Field | Description |
|---|---|
id | Workwae message id. |
threadId | The provider's thread id, or null. |
internetMessageId | RFC 5322 Message-ID, or null. |
mailboxIds | Ids of the mailboxes the message is in. |
subject, from, to, cc, snippet | Headers and a text preview. from and subject can be null. |
receivedAt, sentAt | Timestamps, or null. |
isRead, isFlagged, isDraft, hasAttachments | Flags. |
categories | Microsoft categories; Gmail inbox tabs (personal, social, promotions, updates, forums). |
direction | outbound when the message is in a mailbox with role sent or its From is the account's own address or one of its identities (so drafts are outbound); else inbound. |
outboxId, reference | The outbox entry this message is a copy of, and the reference it was queued with, when it was sent through the API (the sent copy, and the received copy of a message sent to the account itself); else null. Kept after outbox retention deletes the entry. |
importance | high, normal or low. null for a message indexed before Workwae read priorities, until the provider reports it again. Gmail and IMAP read normal when no priority header is present. |
Each entry of data.mailboxes has the mailbox's id, name and role; the role tells inbound mail from sent mail and drafts.
To keep the samples short, only the first message sample shows the full object.
Mailboxes
data.mailbox is the mailbox (folder or label) with its id, name, path, parentId, role, kind, totalCount and unreadCount.
Messages
Opens and clicks
message.opened and message.clicked carry the same fields. They fire only for sends with tracking on; see Tracking.
| Field | Description |
|---|---|
outboxId, reference | The tracked send. |
messageId | The account's sent copy, once its sync has indexed and linked it; null until then. |
url | Clicks: where the link led. null for opens and for the honeypot link. |
actor | human, proxy, prefetch, scanner or unknown. |
reasons | Stable codes for what decided the actor, such as ua_google_image_proxy, cidr_apple_mpp, honeypot, sec_fetch_user. |
isMachine | true when actor is proxy, prefetch or scanner. |
sequence, secondsAfterSend, secondsSincePrevious | The hit's number among the send's opens and clicks (from 1) and its timing. |
client, device, os, browser, location fields | Signals derived from the request. |
The raw request headers are only on the tracking list API, not in the event.
Sends
Every send event carries outboxId, the outbox entry, and the reference it was queued with. See Sending.