Webhooks

These are the available events that EmailEngine sends webhooks for.

messageNew

A new message was added to a folder. This event is generated by incoming emails, uploaded emails, and emails moved or copied from one folder to another. IMAP does not distinguish "incoming" emails from messages that are added to a folder by other means.

NB! Content text webhook setting is enabled for this example, so there are data.text.plain and data.text.html fields set. The default would be to not include content text in the payload. To enable text processing, you can set it in the UI with Configuration → Webhooks → Text content → "Include text content in new email webhooks" or by setting notifyText to true with the Settings API.

{
  "serviceUrl": "https://emailengine-dev.apps.srv.dev",
  "account": "postalsys",
  "date": "2023-03-14T11:13:10.609Z",
  "path": "[Gmail]/All Mail",
  "specialUse": "\\All",
  "event": "messageNew",
  "data": {
    "id": "AAAAAQABDFI",
    "uid": 68690,
    "path": "[Gmail]/All Mail",
    "emailId": "1760341395373354319",
    "threadId": "1760341395373354319",
    "date": "2023-03-14T11:12:45.000Z",
    "flags": [],
    "labels": [
      "\\Important",
      "\\Inbox"
    ],
    "unseen": true,
    "size": 8271,
    "subject": "Impressed by the new features of EmailEngine!",
    "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": "andris@postalsys.com"
      }
    ],
    "messageId": "<CAPacwgwKMETwvftKuQyieSKmp1C+NJcZtqjZ2pSALZkjB-CCbQ@mail.gmail.com>",
    "text": {
      "id": "AAAAAQABDFKTkaExkaEykA",
      "encodedSize": {
        "plain": 1535,
        "html": 1630
      },
      "plain": "Dear Postal Systems OÜ,\n\nI hope this email finds you well. I am writing to express my excitement and\nadmiration for the new features of EmailEngine. As a regular user of email\nservices, I have found it difficult to manage my multiple email accounts on\ndifferent apps. However, EmailEngine has proved to be a game-changer in\nthis regard.\n\nI am amazed by how EmailEngine allows other apps to access regular email\naccounts, making the process of managing emails much easier and efficient.\nThe user-friendly interface and advanced security features make it a\nreliable choice for anyone who wants to manage their emails in a\nhassle-free manner.\n\nOne of the most impressive features of EmailEngine is its compatibility\nwith different email service providers. It seamlessly integrates with\nGmail, Outlook, Yahoo, and many other popular email services, allowing\nusers to manage their emails in one place without having to switch between\ndifferent apps.\n\nFurthermore, the customizable API and SDKs of EmailEngine make it possible\nfor developers to integrate it into their apps, enabling their users to\naccess their email accounts without leaving the app. This feature is not\nonly convenient but also saves time and enhances the user experience.\n\nOverall, I am thoroughly impressed by the new features of EmailEngine, and\nI believe it is a significant step towards making email management more\naccessible and efficient. Thank you for providing such a valuable service\nto users like me.\n\nBest regards,\nAndris\n",
      "html": "<div dir=\"ltr\">Dear Postal Systems OÜ,<br><br>I hope this email finds you well. I am writing to express my excitement and admiration for the new features of EmailEngine. As a regular user of email services, I have found it difficult to manage my multiple email accounts on different apps. However, EmailEngine has proved to be a game-changer in this regard.<br><br>I am amazed by how EmailEngine allows other apps to access regular email accounts, making the process of managing emails much easier and efficient. The user-friendly interface and advanced security features make it a reliable choice for anyone who wants to manage their emails in a hassle-free manner.<br><br>One of the most impressive features of EmailEngine is its compatibility with different email service providers. It seamlessly integrates with Gmail, Outlook, Yahoo, and many other popular email services, allowing users to manage their emails in one place without having to switch between different apps.<br><br>Furthermore, the customizable API and SDKs of EmailEngine make it possible for developers to integrate it into their apps, enabling their users to access their email accounts without leaving the app. This feature is not only convenient but also saves time and enhances the user experience.<br><br>Overall, I am thoroughly impressed by the new features of EmailEngine, and I believe it is a significant step towards making email management more accessible and efficient. Thank you for providing such a valuable service to users like me.<br><br>Best regards,<br>Andris<br></div>\n",
      "hasMore": false
    },
    "category": "primary",
    "isAutoReply": false,
    "seemsLikeNew": true,
    "messageSpecialUse": "\\Inbox",
    "summary": {
      "id": "chatcmpl-6twsSdxRdTVq8uWPfbsdWSgQViJI3",
      "tokens": 512,
      "summary": "Andris is impressed with the new features of EmailEngine and finds it easier to manage his multiple email accounts on different apps with EmailEngine. He appreciates its user-friendly interface, advanced security features, compatibility with different email service providers, customizable API and SDKs, and its ability to allow other apps to access regular email accounts.",
      "sentiment": "positive"
    }
  },
  "_route": {
    "id": "AAABhpMgNhsAAAAE"
  }
}

Field definitions

• _route is present if the webhook was sent via a webhook router.
• data.category is present for Gmail Inbox emails if Resolve Gmail categories option is enabled in the Service → Labs configuration section. The value indicates the Gmail category tab of the incoming email. See below ↓ for more details.
• data.seemsLikeNew is a probabilistic indicator if EmailEngine has seen this email before or not. This is correct around 99%.
• specialUse indicates the special use folder the email was found from. NB! For most Gmail account emails, this is \All, so check the messageSpecialUse property for better indication
• data.messageSpecialUse indicates the special use folder this email belongs to. For most emails, this is the same as specialUse property, but for Gmail accounts, where emails mostly reside in the \All folder, it is different.
• data.isAutoReply indicates if the email is an auto-reply email (out-of-office, bounce, etc)
• data.summary is the summary info provided by ChatGPT if OpenAI integration is enabled in the Service → Labs configuration section.

Gmail tab category

Gmail sorts incoming emails into different categories like promotions, social, and primary and displays emails under these category tabs. For IMAP, all these emails still look like regular INBOX folder emails. EmailEngine can resolve the category of incoming emails and include this information in the payload of the messageNew webhook.

Category resolving is not enabled by default. To enable it, navigate to Configuration -> Service, and then to the Labs section. Mark the "Resolve Gmail categories" checkbox, and save the settings.

Now, whenever an email lands in the Inbox of an email account that EmailEngine tracks, the messageNew webhook for that email will include a property called category, and the value is one of the following: social, promotions, updates, forums, and primary.

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 immediately.

{
  "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: "
  }
}

messageComplaint

EmailEngine found an ARF formatted FBL report from the Inbox folder. If such an email is found, then EmailEngine parses it and posts parsed information as the messageComplaint webhook.

{
  "serviceUrl": "http://127.0.0.1:3000",
  "account": "example",
  "date": "2022-09-27T12:33:42.635Z",
  "event": "messageComplaint",
  "data": {
    "complaintMessage": "AAAAAQAABvE",
    "arf": {
      "source": "Hotmail",
      "feedbackType": "abuse",
      "abuseType": "complaint",
      "originalRcptTo": [
        "recipient@hotmail.co.uk"
      ],
      "sourceIp": "1.2.3.4",
      "arrivalDate": "2021-10-22T13:04:36.017Z"
    },
    "headers": {
      "messageId": "<67d3846d-b819-9c54-5053-a81fdc432425@example.com>",
      "from": "user@example.com",
      "to": [
        "recipient@hotmail.co.uk"
      ],
      "subject": "Hello world",
      "date": "2021-10-22T16:04:33.000Z"
    }
  }
}

NB! included fields depend on the reporting server. Sometimes important information like the source email Message-ID value might be missing.

messageDeliveryError

EmailEngine retries sending multiple times. For every failing try a messageDeliveryError is sent.

{
  "serviceUrl": "http://127.0.0.1:3000",
  "account": "example",
  "date": "2022-09-14T15:07:35.832Z",
  "event": "messageDeliveryError",
  "data": {
    "queueId": "1833c8a88a86109a1bf",
    "envelope": {
      "from": "andris@ekiri.ee",
      "to": [
        "andris@ethereal.email"
      ]
    },
    "messageId": "<29e26263-7125-ff56-4f80-83a5cf737d5e@ekiri.ee>",
    "error": "400 Message Not Accepted",
    "errorCode": "EPROTOCOL",
    "smtpResponseCode": 400,
    "job": {
      "attemptsMade": 1,
      "attempts": 10,
      "nextAttempt": "2022-09-14T15:07:45.465Z"
    }
  }
}

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"
  }
}

listUnsubscribe

A recipient clicked on the unsubscribe link, or the email client posted the one-click unsubscribe request.

{
  "account": "example",
  "date": "2022-03-24T08:27:24.572Z",
  "event": "listUnsubscribe",
  "data": {
    "recipient": "recipient@example.com",
    "messageId": "<49b6cdb1-5d43-e100-0833-bd61867b7bb3@example.com>",
    "listId": "my-customers-list",
    "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"
  }
}

You can set custom headers for webhook requests with the webhooksCustomHeaders setting, or from the webhook setting page in EmailEngine's admin dashboard.

In addition to custom headers, EmailEngine also includes some additional debugging headers, as shown below.

EmailEngine makes up to 10 webhook delivery attempts before it considers a webhook payload undeliverable.

EmailEngine makes retry attempts with an exponential backoff strategy. The delay is 5000ms, and the formula to calculate the delay between attempts is the following:

2 ^ (attempts - 1) * delay milliseconds

Webhook jobs can be found from the notify queue (Tools → Arena → notify).

You can find failed webhooks that are yet to be retried from the Delayed job queue section and undeliverable webhooks from the Failed section. By default, EmailEngine does not store failed jobs. You can set the number of Completed/Failed jobs to keep in the Configuration → Service → Queue Settings configuration section.