How to connect an IMAP inbox to VICIdial

VICIdial can read an external mailbox over IMAP and turn each new message into work for an Agent. IMAP is one of two protocols VICIdial supports for inbound email, the other being POP3, and it is the one most providers recommend today. Connecting it comes down to setting the protocol and giving VICIdial the right server and login.

The protocol lives on the Email Account, the object that represents your real mailbox. So this is a small but important part of building that account, not a separate screen.

What IMAP needs

On the Email Account form, set the protocol to IMAP, then fill the connection details to match your provider:

• Email Account Protocol: IMAP.
• Email Account Server: the IMAP server hostname your provider gives you.
• Email Account User: the login for the mailbox, usually the part of the address before the @ symbol.
• Email Account Password: the password for that mailbox, set when the account was created.
• Email Reply-to Address: the address replies from your agents will appear to come from.

One nice thing about IMAP: it does not need the extra authorization-mode setting that POP3 does. POP3 has a BEST option that tries a few login schemes in turn, and that field only matters when the protocol is POP3. With IMAP you skip that decision entirely.

How the connection runs

Once the account is active, VICIdial uses your protocol choice to log into the server on the check schedule, read new mail, and hand each message to the Email Group you named. From there the group routes it to a person.

flowchart LR
  A["Email Account set to IMAP"] --> B["Connect to IMAP server"]
  B --> C["Authenticate with user and password"]
  C --> D["Read new messages"]
  D --> E["Hand to In-Group"]
  E --> F["Route to agent"]
  F --> G["Agent works the lead"]

If the connection fails, the cause is almost always one of three things: a wrong server hostname, a wrong username or password, or a provider that has temporarily locked the mailbox after too many login attempts. Slow down the check rate if you suspect a lock, and double-check the hostname against what your provider lists for IMAP specifically, since IMAP and POP3 often use different servers. The username is usually the part of the address before the @ symbol rather than the full address, which is an easy thing to get wrong on the first try.

The check rate is worth a second thought as well. Faster is not always better. A mailbox that gets checked every few minutes feels responsive, but pushing it too hard is exactly what triggers a provider lock. A modest interval keeps mail moving without putting the account at risk, and you can always tighten it once you trust the connection.

Once mail is flowing, the rest is routing. The Email Group decides which Agent receives a message, how the work sits against a Campaign, and what a finished Disposition does to the Lead. The protocol just gets the mail in the door; the group does everything after.

Not sure where the protocol fits in the bigger setup? Read how to add an inbound Email Account for the full field list. The inbound email and chat guide shows how email sits alongside calls and how an Ingroup hands work out. Standing up the parser and the perl modules IMAP needs is the fiddly part, so if you would rather it just work, our pricing page covers managed VICIdial hosting with the email stack already in place.