Connect any IMAP mailbox

What this is for

You have an email address your customers already write to — on the invoices, on the website, on the van — and you would like WorkOrders to read it. This page is the general procedure, for any mail provider at all: your web host, your internet provider, whoever set up the address in the first place.

Two providers have pages of their own, because they are special cases rather than harder cases:

• Gmail or Google Workspace — connect a Gmail mailbox walks through the app password, which Google buries.
• Microsoft 365 or Outlook — Microsoft 365 and Outlook mailboxes. Read that one before you try anything on this page: Microsoft no longer allows this kind of connection at all, and there is a different route that works.

And before you start, know that you do not have to do any of this. Every company gets its own address at signup — something like yourfirm@jobs.workorders.nz — and forwarding your existing inbox to it gets the same jobs onto the same board with no password stored anywhere. More on that at the bottom of this page.

What to get from your provider first

Everything on the connect screen is something your mail provider decides, not something you choose. Collect these five before you open it, and the rest takes about two minutes:

• The IMAP server name. Nearly always something of the shape imap.yourprovider.com or mail.yourdomain.co.nz. It is not usually your website's address, and it is not the outgoing server.
• The port — a number. Almost always 993.
• The encryption — how the connection is protected. This goes hand in hand with the port; see below.
• The username. Sometimes the whole email address, sometimes just the part in front of the @, and occasionally something that looks nothing like either. Your provider will say which.
• A password. If your provider offers app passwords — a separate password issued to one program, which you can revoke on its own — use one. If it does not, the mailbox's ordinary password is what goes in.

Where to find them

Search your provider's own help pages for "IMAP settings". Every mail host publishes them, they are usually on one short page with the server name and port in a table, and they are the authority — a value copied from a forum post about a different provider is the most common reason this does not work first time.

If you have no idea who your provider is, look at whoever sends the bill for your website or your domain. It is very often the same company.

Some providers ship with IMAP switched off. It is a setting on the mailbox, usually somewhere called "IMAP access" or "mail clients", and if it is off, no combination of correct-looking settings will connect. Turn it on before you spend an afternoon on the password.

The connect screen, field by field

In WorkOrders, go to Settings → Mailboxes and choose Connect IMAP. You need to be an owner or an administrator to see it.

• Mailbox address — the address customers send requests to. This is the one on the invoices, and it is what the mailbox will be called on your list.
• Display name — what this mailbox is called inside WorkOrders, for when you have more than one. Something like Service requests or Wellington office. Optional, and only ever seen by your own staff.
• IMAP server — the server name from your provider. No https://, no slashes; just the name.
• Port — a number, already filled in as 993. Leave it alone unless your provider says otherwise.
• Encryption — three choices, covered in their own section below.
• Username — whatever your provider told you, which may or may not be the same as the mailbox address. If you are guessing, guess the full email address; that is right more often than not.
• App password — the password for the mailbox. Use an app-specific one where the provider offers one. It is stored encrypted and never shown to anyone again, including you, which is why the field comes up blank when you edit a connection later. Leaving it blank on an edit means "keep the password you already have", so you can correct a typo in the server name without going and issuing a new one.
• Subject prefix — optional, and only useful once you are running more than one mailbox. Whatever you type is added to the front of every subject line that comes in through this mailbox, so you can tell at a glance which inbox a job arrived at. It is added exactly as typed: if you want a space between it and the subject, put the space in. [Auckland] with the trailing space gives you [Auckland] Leaking tap; without it you get [Auckland]Leaking tap.

Port and encryption go together

This is the pair people mix up, and mixing them up produces an error that looks like a password problem. The two numbers are not interchangeable — a server listening for one kind of connection will not answer the other.

• SSL / TLS (port 993) with port 993. This is the normal, modern combination and what almost every provider wants. If you are unsure, this is the guess to make.
• STARTTLS (port 143) with port 143. Older, still perfectly secure, and used by some hosts. Use it only if your provider's page names port 143.
• None — no protection at all, with the password crossing the internet in the clear. It exists for a mail server on your own network that offers nothing else. If your provider is a company on the internet, this is not your answer.

So: 993 with SSL / TLS, or 143 with STARTTLS. 993 with STARTTLS, or 143 with SSL / TLS, will not connect no matter how right the password is.

Test before you save

Press Test connection before you press Connect mailbox. The test signs in with what you have typed and reports back without saving anything at all, so you can fix a typo and try again as many times as you like. A failed test costs nothing and leaves nothing behind.

Nothing is saved unless the credentials work. Even if you go straight for Connect mailbox, the connection is proved first and the mailbox is only written down once it has succeeded. A mailbox cannot exist here in a state we have never connected to — which is deliberate, because the alternative is a mailbox sitting in the list looking connected while failing silently every five minutes, and the first you hear of it is a customer asking why nobody came.

What happens once it is connected

• The mailbox is checked every five minutes.
• Mail is read, never deleted. Once a message has become a work order it is moved into a folder called WorkOrders-Processed, created for you the first time it is needed. Nothing is thrown away, so anything we got wrong can be looked at afterwards — the email is still there.
• Nothing is marked read. If a person also watches this inbox, their unread count is exactly as they left it.
• Mail already in the inbox is read in too. There is no start-from-today line: whatever is sitting there when you connect is worked through, a batch at a time every five minutes, until it has caught up. That is often exactly what you want. If it is not, move or archive the old mail out of the inbox before you connect, and only what arrives afterwards will be picked up.
• Only the inbox is watched. Mail your own rules file into another folder before we see it is not read.
• The password gives us access to that one mailbox and nothing else. It is stored encrypted and never shown back to anyone.

When it stops

Sooner or later it will: a password is changed, an app password is revoked in a tidy-up, the account is rebuilt, the provider changes its rules. When that happens the mailbox is marked as needing attention on Settings → Mailboxes, with the server's own words shown next to it, and everyone in the firm who is an owner or an administrator is emailed about it. You do not have to be the one who notices.

Nothing is lost while it is stopped. The messages stay in the mailbox untouched, and they are read in on the first check after you reconnect.

To fix it, press Reconnect next to the mailbox, put the new password in, and save. Everything else is remembered.

When it will not connect

If your provider will not do this

Some will not, and some will only with a password you would rather not hand over. That is not the end of the road, and the alternative is not a lesser one.

Forward the inbox to your own WorkOrders address instead. Set a rule in the mailbox that sends incoming mail on to your yourfirm@jobs.workorders.nz address — it is on Settings → Mailboxes, at the top, with a button to copy it. Your customers keep writing to the address they have always used, it keeps arriving in your inbox as it always has, and a copy comes here and becomes a job.

No credentials are stored anywhere, nothing breaks when somebody changes a password, and a forwarded message is read exactly the same way as a fetched one — same sender, same subject, same attachments. And if you set up forwarding and later connect the same mailbox over IMAP as well, you will not get two of everything: the same message arriving by two routes only ever makes one job.

Your own WorkOrders address covers what to do with it, and how work gets into WorkOrders compares all four routes if you are still choosing.