Using EmailEngine.md

Step 1. Register a new account

Register a new account with IMAP and SMTP settings (reference)

curl -XPOST "http://127.0.0.1:3000/v1/account" \
    -H "Authorization: Bearer f77cf263b70488c7a35bf1539fd544a81a88711ff74326ce9793022df08d91b9" \
    -H "Content-type: application/json" \
    -d '{
      "account": "example",
      "name": "Andris Reinman",
      "email": "andris@ekiri.ee",
      "imap": {
        "auth": {
          "user": "andris",
          "pass": "sercretpass"
        },
        "host": "turvaline.ekiri.ee",
        "port": 993,
        "secure": true
      },
      "smtp": {
        "auth": {
          "user": "andris",
          "pass": "secretpass"
        },
        "host": "turvaline.ekiri.ee",
        "port": 465,
        "secure": true
      }
    }'

Notes

1. Token (f77cf263b70488....) was generated in EmailEngine's dashboard on the Access Tokens page.
2. These are actual settings, except the password
3. Be aware that if you are using any other port for SMPT than 465, then set secure to false

Expected result

{
  "account": "example",
  "state": "new"
}

Step 1. Send an email

Send an email by submittin an email structure to EmailEngine's submit endpoint (reference)

curl -XPOST "http://127.0.0.1:3000/v1/account/example/submit" \
    -H "Authorization: Bearer f77cf263b70488c7a35bf1539fd544a81a88711ff74326ce9793022df08d91b9" \
    -H "Content-type: application/json" \
    -d '{
      "from": {
        "name": "Andris Reinman",
        "address": "andris@ekiri.ee"
      },
      "to": [
        {
          "name": "Ethereal",
          "address": "andris@ethereal.email"
        }
      ],
      "subject": "Test message",
      "text": "Hello from myself!",
      "html": "<p>Hello from myself!</p>"
    }'

Expected result

{
  "response": "Queued for delivery",
  "messageId": "<99f7f0ec-90a1-caaf-698b-18e096c7679e@ekiri.ee>",
  "sendAt": "2021-12-23T10:22:31.312Z",
  "queueId": "4646ac53857fd2b2"
}

Notes

1. Accepting message for delivery does not mean that the message was delivered. Listen for messageFailed and messageSent webhook notifications to see if EmailEngine was able to pass the message over to MTA or not

Webhook results

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

While retrying you can see the job entry in the Bull Ui page under submit queue. The faield job should reside in the "delayed" section

If you open that queue you should see the reason why the job is being retried

Received message

Once message is delivered it should look like this:

Troubleshooting

Some email servers might not accept emails even if the username and password are correct. Notably Gmail, Outlook and Yahoo. This happens when the email server detects that the sender might be a bot and suspects that the account might be used without permission. To overcome, use application specific passwords or OAuth2 as these limitations do not apply when using OAuth2.