EmailEngine

Getting started

1. Set up webhook target

Open the Settings tab and set an URL for webhooks. Whenever something happens with any of the tracked email accounts you get a notification to this URL.

For example if flags are updated for a message you'd get a notification that looks like this:

{
    "account": "example",
    "path": "[Google Mail]/All Mail",
    "event": "messageUpdated",
    "data": {
        "id": "AAAAAQAAAeE",
        "uid": 350861,
        "changes": {
            "flags": {
                "added": [
                    "\\Seen"
                ]
            }
        }
    }
}

2. Register an email account with EmailEngine

You need IMAP and SMTP settings and also provide some kind of an identification string value for this account. You can use the same IDs as your main system or generate some unique ones. This value is later needed to identify this account and to perform operations on it.

$ curl -XPOST "localhost:3000/v1/account" -H "content-type: application/json" -d '{
    "account": "example",
    "name": "My Example Account",
    "imap": {
        "host": "imap.gmail.com",
        "port": 993,
        "secure": true,
        "auth": {
            "user": "myuser@gmail.com",
            "pass": "verysecret"
        }
    },
    "smtp": {
        "host": "smtp.gmail.com",
        "port": 465,
        "secure": true,
        "auth": {
            "user": "myuser@gmail.com",
            "pass": "verysecret"
        }
    }
}'

3. That's about it

Now whenever something happens you get a notification. If this is not enought then you can perform normal operations with the IMAP account as well. See the API docs page for details.

Bonus! List some messages

EmailEngine returns paged results, newer messages first. So to get the first page or in other words the newest messages in a mailbox folder you can do it like this (notice the "example" id string that we set earlier in the request URL):

$ curl -XGET "localhost:3000/v1/account/example/messages?path=INBOX"

In the response you should see a listing of messages.

{
  "page": 0,
  "pages": 10,
  "messages": [
    {
      "id": "AAAAAQAAAeE",
      "uid": 481,
      "date": "2019-10-07T06:05:23.000Z",
      "size": 4334,
      "subject": "Test message",
      "from": {
        "name": "Peter Põder",
        "address": "Peter.Poder@example.com"
      },
      "to": [
        {
          "name": "",
          "address": "andris@emailengine.app"
        }
      ],
      "messageId": "<0ebdd7b084794911b03986c827128f1b@example.com>",
      "text": {
        "id": "AAAAAQAAAeGTkaExkaEykA",
        "encodedSize": {
          "plain": 17,
          "html": 2135
        }
      }
    },
    ...
  ]
}

Webhooks

Webhook URL

Enter valid URL for the webhook

EmailEngine makes a POST request against this URL for every detected change in user's account. This includes new messages, deleted messages and flag changes. Leave empty to disable notifications.

Include text content in new email webhooks By default only message metadata without HTML or plaintext values is included in the webhook to keep notification payload size at minimum. If enabled then text values are also added to the webhook.

Maximum text size

Enter valid number

To keep webhook size with text values in check you can define maximum text size limit. Longer texts are cropped to fit that size. This limit is applied per text-type, so if the limit is 1000 bytes and email has both plaintext and html content, then you get 1000 bytes of plaintext and 1000 bytes of HTML.

Events to listen

Enter valid events

Comma separated list of event names (case sensitive). Use * for all events.
Available events:

Headers to include

Enter valid headers

Comma separated list of header names. Use * for all headers or leave empty to not include headers in the webhook.

Authentication

Auth Server URL

Enter valid URL for Auth Server

You can configure accounts to resolve authentication info from an authentication server instead of setting fixed credentials. Whenever EmailEngine needs to authenticate such account it makes a GET request against this URL with 2 additional query arguments - account as the account ID and proto which is either "imap" or "smtp". Recommended when using OAuth accounts.

OAuth2 (Gmail only)

You OAuth2 project must have the following scope enabled: "https://mail.google.com/".
Setting these values allows you to use the OAuth2 tab in the "Add account" form.

Client Id

Enter valid client id

OAuth2 client id.

Client Secret

Enter valid client id

OAuth2 client secret.

Callback URL

Enter valid URL for the callback

Redirect URL for OAuth2. Must point to your EmailEngine installation and end with /oauth

IMAP logs

In case there are issues syncing some specific accounts you can turn on IMAP logging. This stores all IMAP traffic except user credentials and message content for selected accounts. You can then download these logs for inspection.

Store IMAP logs for all accounts Not recommended if EmailEngine tracks large number of accounts

Store IMAP logs for the following accounts Enter one account ID per line

Reconnect logged accounts Mark this checkbox if you want to make sure that logged accounts are reconnected and authenticated (one time action, checkbox state is not stored). Established connections are kept alive as long as possible so enabling logging for existing users without forced reconnect may not give any useful info.

Maximum lines of logs to store

Enter valid number between 0 and 1000000

Logs are stored in Redis which in other words means RAM, so it might not be a good idea to store too much data in it

Update settings

You can download stored logs here for accounts that have logging enabled. Logging can be enabled either for all or specific accounts in the Settings tab.

Account ID

Enter valid account ID

Download logs