1// Package webhook has data types used for webhooks about incoming and outgoing deliveries.
3// See package webapi for details about the webapi and webhooks.
5// Types [Incoming] and [Outgoing] represent the JSON bodies sent in the webhooks.
6// New fields may be added in the future, unrecognized fields should be ignored
7// when parsing for forward compatibility.
14// OutgoingEvent is an activity for an outgoing delivery. Either generated by the
15// queue, or through an incoming DSN (delivery status notification) message.
16type OutgoingEvent string
18// note: outgoing hook events are in ../queue/hooks.go, ../mox-/config.go, ../queue.go and ../webapi/gendoc.sh. keep in sync.
20// todo: in future have more events: for spam complaints, perhaps mdn's.
23 // Message was accepted by a next-hop server. This does not necessarily mean the
24 // message has been delivered in the mailbox of the user.
25 EventDelivered OutgoingEvent = "delivered"
27 // Outbound delivery was suppressed because the recipient address is on the
28 // suppression list of the account, or a simplified/base variant of the address is.
29 EventSuppressed OutgoingEvent = "suppressed"
31 // A delivery attempt failed but delivery will be retried again later.
32 EventDelayed OutgoingEvent = "delayed"
34 // Delivery of the message failed and will not be tried again. Also see the
35 // "Suppressing" field of [Outgoing].
36 EventFailed OutgoingEvent = "failed"
38 // Message was relayed into a system that does not generate DSNs. Should only
39 // happen when explicitly requested.
40 EventRelayed OutgoingEvent = "relayed"
42 // Message was accepted and is being delivered to multiple recipients (e.g. the
43 // address was an alias/list), which may generate more DSNs.
44 EventExpanded OutgoingEvent = "expanded"
46 // Message was removed from the queue, e.g. canceled by admin/user.
47 EventCanceled OutgoingEvent = "canceled"
49 // An incoming message was received that was either a DSN with an unknown event
50 // type ("action"), or an incoming non-DSN-message was received for the unique
51 // per-outgoing-message address used for sending.
52 EventUnrecognized OutgoingEvent = "unrecognized"
55// Outgoing is the payload sent to webhook URLs for events about outgoing deliveries.
57 Version int // Format of hook, currently 0.
58 Event OutgoingEvent // Type of outgoing delivery event.
59 DSN bool // If this event was triggered by a delivery status notification message (DSN).
60 Suppressing bool // If true, this failure caused the address to be added to the suppression list.
61 QueueMsgID int64 // ID of message in queue.
62 FromID string // As used in MAIL FROM, can be empty, for incoming messages.
63 MessageID string // From Message-Id header, as set by submitter or us, with enclosing <>.
64 Subject string // Of original message.
65 WebhookQueued time.Time // When webhook was first queued for delivery.
66 SMTPCode int // Optional, for errors only, e.g. 451, 550. See package smtp for definitions.
67 SMTPEnhancedCode string // Optional, for errors only, e.g. 5.1.1.
68 Error string // Error message while delivering, or from DSN from remote, if any.
69 Extra map[string]string // Extra fields set for message during submit, through webapi call or through X-Mox-Extra-* headers during SMTP submission.
72// Incoming is the data sent to a webhook for incoming deliveries over SMTP.
74 Version int // Format of hook, currently 0.
76 // Message "From" header, typically has one address.
81 BCC []NameAddress // Often empty, even if you were a BCC recipient.
83 // Optional Reply-To header, typically absent or with one address.
88 // Of Message-Id header, typically of the form "<random@hostname>", includes <>.
91 // Optional, the message-id this message is a reply to. Includes <>.
94 // Optional, zero or more message-ids this message is a reply/forward/related to.
95 // The last entry is the most recent/immediate message this is a reply to. Earlier
96 // entries are the parents in a thread. Values include <>.
99 // Time in "Date" message header, can be different from time received.
102 // Contents of text/plain and/or text/html part (if any), with "\n" line-endings,
103 // converted from "\r\n". Values are truncated to 1MB (1024*1024 bytes). Use webapi
104 // MessagePartGet to retrieve the full part data.
107 // No files, can be large.
109 Structure Structure // Parsed form of MIME message.
110 Meta IncomingMeta // Details about message in storage, and SMTP transaction details.
113type IncomingMeta struct {
114 MsgID int64 // ID of message in storage, and to use in webapi calls like MessageGet.
115 MailFrom string // Address used during SMTP "MAIL FROM" command.
116 MailFromValidated bool // Whether SMTP MAIL FROM address was SPF-validated.
117 MsgFromValidated bool // Whether address in message "From"-header was DMARC(-like) validated.
118 RcptTo string // SMTP RCPT TO address used in SMTP.
119 DKIMVerifiedDomains []string // Verified domains from DKIM-signature in message. Can be different domain than used in addresses.
120 RemoteIP string // Where the message was delivered from.
121 Received time.Time // When message was received, may be different from the Date header.
122 MailboxName string // Mailbox where message was delivered to, based on configured rules. Defaults to "Inbox".
124 // Whether this message was automated and should not receive automated replies.
125 // E.g. out of office or mailing list messages.
129type NameAddress struct {
130 Name string // Optional, human-readable "display name" of the addressee.
131 Address string // Required, email address.
134type Structure struct {
135 ContentType string // Lower case, e.g. text/plain.
136 ContentTypeParams map[string]string // Lower case keys, original case values, e.g. {"charset": "UTF-8"}.
137 ContentID string // Can be empty. Otherwise, should be a value wrapped in <>'s. For use in HTML, referenced as URI `cid:...`.
138 ContentDisposition string // Lower-case value, e.g. "attachment", "inline" or empty when absent. Without the key/value header parameters.
139 Filename string // Filename for this part, based on "filename" parameter from Content-Disposition, or "name" from Content-Type after decoding.
140 DecodedSize int64 // Size of content after decoding content-transfer-encoding. For text and HTML parts, this can be larger than the data returned since this size includes \r\n line endings.
141 Parts []Structure // Subparts of a multipart message, possibly recursive.