IMAP API

IMAP API is a self hosted server application for accessing IMAP accounts over REST API. IMAP API connects to user's IMAP account, translates API requests to IMAP and also sends webhooks for changes like new or deleted emails.

IMAP API stores only the minimal amount of data required to keep mailbox state in sync. Email contents are not sent to any external provider and are not stored.

Accounts Connecting Connected Failed Login Failed Connection  
0 0 0 0 0

IMAP API allows you to:

  • List folders and messages in a user's email account – IMAP API provides an easy to use paging and sorts newer messages first
  • Track changes in user's email account – IMAP API uses webhooks to notify your application
  • Send out emails on behalf of the user – IMAP API sets all required headers and message flags when replying or forwarding a message and also uploads the message to the Sent Mail folder

API documentation for IMAP API is available as Swagger docs

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 IMAP API

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

IMAP API 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@imapapi.com"
        }
      ],
      "messageId": "<0ebdd7b084794911b03986c827128f1b@example.com>",
      "text": {
        "id": "AAAAAQAAAeGTkaExkaEykA",
        "encodedSize": {
          "plain": 17,
          "html": 2135
        }
      }
    },
    ...
  ]
}
Webhooks
Enter valid URL for the webhook
Required. IMAP API makes a POST request against this URL for every detected change in user's account. This includes new messages, deleted messages and flag changes.
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.
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.
Enter valid events
Comma separated list of event names (case sensitive). Use * for all events.
Available events:
Enter valid headers
Comma separated list of header names. Use * for all headers or leave empty to not include headers in the webhook.
Authentication
Enter valid URL for Auth Server
You can configure accounts to resolve authentication info from an authentication server instead of setting fixed credentials. Whenever IMAP API 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". Using auth server is always required for OAuth accounts.
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.

Not recommended if IMAP API tracks large number of accounts
Enter one account ID per line
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.
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

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.

Enter valid account ID