Example webhooks
messageNew
A new message was added to the folder. Both new/received messages and messages moved from one folder another generate this event.
To distinguish new messages from copied messages, check if the path value is INBOX or, in case of Gmail/GSuite accounts, data.labels array includes \Inbox.
The following example has extra options turned on:
MIME-Headersheader is included in the response. Default would be not to include extra headers.- Content text is enabled and the max text size is set to 1024 bytes. Default would be to not include content text in the payload.
{
"account": "pangalink",
"date": "2022-01-17T11:44:46.934Z",
"path": "[Gmail]/All Mail",
"specialUse": "\\All",
"event": "messageNew",
"data": {
"id": "AAAAAQAANJc",
"uid": 13463,
"emailId": "1722202068227089305",
"threadId": "1722202068227089305",
"date": "2022-01-17T11:44:28.000Z",
"unseen": true,
"size": 35795,
"subject": "Test message 🤔",
"from": {
"name": "Andris Reinman",
"address": "andris.reinman@gmail.com"
},
"replyTo": {
"name": "Andris Reinman",
"address": "andris.reinman@gmail.com"
},
"sender": {
"name": "Andris Reinman",
"address": "andris.reinman@gmail.com"
},
"to": [
{
"name": "",
"address": "no-reply@pangalink.net"
}
],
"attachments": [
{
"id": "AAAAAQAANJcy",
"contentType": "image/png",
"encodedSize": 30436,
"filename": "grinning-face_1f600.png",
"embedded": false,
"inline": false,
"contentId": "<f_kyimd6xt0>"
}
],
"messageId": "<CAPacwgwFgoB=XWR=V9i2AjYgdhrEG6C5e6PtGGDYmVvm8inxJA@mail.gmail.com>",
"labels": [
"\\Important",
"\\Inbox"
],
"headers": {
"mime-version": [
"1.0"
]
},
"text": {
"id": "AAAAAQAANJeTkaMxLjGRozEuMpA",
"encodedSize": {
"plain": 88,
"html": 136
},
"plain": "This is a test message that should generate a *webhook*.\n\nIt also has an attachment.\n",
"html": "<div dir=\"ltr\">This is a test message that should generate a <i>webhook</i>.<div><br></div><div>It also has an attachment.</div></div>\n",
"hasMore": false
},
"seemsLikeNew": false
}
}seemsLikeNewindicates if EmailEngine has seen this message before or not. If you receive a new message, it's set totrue. If you move that message to Trash and then move it back to Inbox, the value will be reported asfalse. NB! false positives and negatives might occur asseemsLikeNewis a derived estimate.
messageDeleted
A message was deleted from a folder. This happens when a message was either deleted or moved to another folder.
{
"account": "pangalink",
"date": "2022-01-17T11:54:02.089Z",
"path": "[Gmail]/All Mail",
"specialUse": "\\All",
"event": "messageDeleted",
"data": {
"id": "AAAAAQAANJc",
"uid": 13463
}
}messageUpdated
This event is fired when a change is detected with a message. Most commonly, when the user marks a message as read or unread.
{
"account": "pangalink",
"date": "2022-01-17T11:56:13.146Z",
"path": "[Gmail]/All Mail",
"specialUse": "\\All",
"event": "messageUpdated",
"data": {
"id": "AAAAAQAANJY",
"uid": 13462,
"changes": {
"flags": {
"added": [
"\\Seen"
]
}
}
}
}messageSent
EmailEngine managed to deliver the email to the MTA server. In this case the webhooks should arrive pretty much immediatelly.
{
"account": "example",
"date": "2021-12-23T10:32:39.499Z",
"event": "messageSent",
"data": {
"messageId": "<a00576bd-f757-10c7-26b8-885d7bbd9e83@ekiri.ee>",
"response": "250 2.0.0 Ok: queued as 5755482356",
"envelope": {
"from": "andris@ekiri.ee",
"to": [
"andris@ethereal.email"
]
}
}
}messageFailed
EmailEngine retries sending multiple times, so receiving the webhook takes a long time (EmailEngine sends the failure webhook once it has given up retrying the message).
{
"account": "example",
"date": "2021-12-23T11:58:50.181Z",
"event": "messageFailed",
"data": {
"messageId": "<97ac5d9a-93c7-104b-8d26-6b25f8d644ec@ekiri.ee>",
"queueId": "610c2c93e608bd37",
"error": "Error: Invalid login: 535 5.7.8 Error: authentication failed: "
}
}messageBounce
A new bounce response message was found from the account. The bounce data includes messageId value but no id value, so you have to look up the bounced message using the Message-ID header value.
If multiple recipients for the same message bounce, you get a separate bounce event for each of these recipients.
{
"account": "pangalink",
"date": "2021-11-28T10:17:29.728Z",
"event": "messageBounce",
"data": {
"bounceMessage": "AAAAAQAABWw",
"recipient": "failed.recipient@example.com",
"action": "failed",
"response": {
"source": "smtp",
"message": "550 5.1.1 <failed.recipient@example.com>: Recipient address rejected: User unknown in relay recipient table",
"status": "5.1.1"
},
"mta": "mx.example.com",
"queueId": "BFC608226A",
"messageId": "<4dbe4a40f37e9c2ba5b25912bc7c8997@example.com>"
}
}Some fields might be missing from a bounce webhook depending on how EmailEngine can parse the information out from the bounce.
trackOpen
Email client loaded the open tracking beacon. This only works if the email client loads external images. There might be false positives, for example, when a web-based email client caches linked images.
{
"account": "example",
"date": "2022-03-24T08:28:32.992Z",
"event": "trackOpen",
"data": {
"messageId": "<2d4696ea-cb47-7af4-0bc3-81ea7a8008be@example.com>",
"remoteAddress": "1.2.3.4",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/99.0.4844.83 Safari/537.36"
}
}trackClick
A tracked link was clicked. False positives might occur when security software scans links in an incoming email.
{
"account": "example",
"date": "2022-03-24T08:27:24.572Z",
"event": "trackClick",
"data": {
"messageId": "<49b6cdb1-5d43-e100-0833-bd61867b7bb3@example.com>",
"url": "https://google.com/",
"remoteAddress": "1.2.3.4",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/99.0.4844.83 Safari/537.36"
}
}