Connect any IMAP mailbox

What this is for

You have an email address your customers already write to (it's on your invoices, your website and your van), and you'd like WorkOrders to read it. This page covers any mail provider: your web host, your internet provider, or whoever set up the address in the first place.

Two providers work differently, so they have their own pages:

• Gmail or Google Workspace: connect a Gmail mailbox walks you through getting an app password, which is hard to find in Google's settings.
• Microsoft 365 or Outlook: Microsoft 365 and Outlook mailboxes. Read that page before trying anything here. Microsoft no longer allows this kind of connection, and that page explains another way that works.

Before you start, remember that you don't have to do any of this. Every company gets its own address when it signs up, something like yourfirm@jobs.workorders.nz. If you forward your existing inbox to it, the same jobs end up on your board and you don't have to give us a password. There's more about that at the bottom of this page.

What to get from your provider first

Your mail provider decides the settings on the connect screen. You can't pick them yourself. Get these five things before you start, and the rest takes about two minutes:

• The IMAP server name. It usually looks like imap.yourprovider.com or mail.yourdomain.co.nz. It's not usually your website's address, and it's not the outgoing mail server.
• The port: a number, almost always 993.
• The encryption: how the connection is protected. This has to match the port (see below).
• The username. Sometimes it's the whole email address, sometimes just the part before the @, and occasionally something different again. Your provider will tell you which.
• A password. If your provider offers app passwords (a separate password for one program, which you can cancel on its own), use one. If not, use the mailbox's normal password.

Where to find them

Search your provider's help pages for "IMAP settings". Every mail provider publishes them, usually on one short page with the server name and port in a table. Use the values from that page. The most common reason a connection fails first time is using settings from a forum post about a different provider.

If you don't know who your provider is, check who sends the bill for your website or your domain name. It's often the same company.

Some providers have IMAP turned off to start with. It's a setting on the mailbox, usually called something like "IMAP access" or "mail clients". If it's off, nothing will connect, however correct your settings are. Turn it on before you spend time checking 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, such as the one on your invoices. It's also how the mailbox is named in your list.
• Display name: a name for this mailbox inside WorkOrders, useful if you have more than one. Something like Service requests or Wellington office. It's optional, and only your own staff see it.
• IMAP server: the server name from your provider. Just the name, with no https:// and no slashes.
• Port: a number, already filled in as 993. Leave it as it is unless your provider says otherwise.
• Encryption: there are three choices, explained in the next section.
• Username: whatever your provider told you. It might not be the same as the mailbox address. If you're not sure, try the full email address, because that's usually right.
• App password: the password for the mailbox. Use an app password if your provider offers one. We store it encrypted and never show it again, even to you, so the field is empty when you edit the connection later. If you leave it empty when editing, we keep the password you already gave us. That means you can fix a typo in the server name without getting a new password.
• Subject prefix: optional, and only useful if you connect more than one mailbox. Whatever you type here is added to the start of the subject of every email that comes in through this mailbox, so you can see which inbox a job came from. It's added exactly as you type it, so if you want a space before the subject, include it. [Auckland] with a space at the end gives you [Auckland] Leaking tap. Without the space you get [Auckland]Leaking tap.

Port and encryption go together

People often mix these two up, and when they don't match, the error can look like a password problem. Each port only works with its own kind of encryption.

• SSL / TLS (port 993) with port 993. This is the usual modern setting, and almost every provider uses it. If you're not sure, choose this one.
• STARTTLS (port 143) with port 143. Older, but still secure, and some providers use it. Only choose it if your provider's settings say port 143.
• None: no encryption, so your password is sent across the internet unprotected. It's only for a mail server on your own network that doesn't offer anything else. If your mail comes from a provider on the internet, don't choose this.

So use 993 with SSL / TLS, or 143 with STARTTLS. 993 with STARTTLS, or 143 with SSL / TLS, won't connect, even if the password is right.

Test before you save

Press Test connection before you press Connect mailbox. The test signs in with what you've typed and tells you whether it worked, without saving anything. You can fix a mistake and try again as many times as you like. A failed test doesn't change anything.

Nothing is saved unless the details work. Even if you press Connect mailbox straight away, WorkOrders checks the connection first and only saves the mailbox once it has connected. So you'll never have a mailbox in your list that looks connected but has never worked.

What happens once it's connected

• WorkOrders checks the mailbox every five minutes.
• Nothing is deleted. Once an email has become a work order, it's moved to a folder called WorkOrders-Processed, which is created the first time it's needed. The email is still there, so you can check it later if anything went wrong.
• Nothing is marked as read. If someone else also uses this inbox, their unread emails stay unread.
• Emails already in the inbox are read too. WorkOrders doesn't start from today. It works through whatever is in the inbox when you connect, a batch every five minutes, until it has caught up. That's often what you want. If not, move or archive the old emails out of the inbox before you connect, and only new ones will be picked up.
• Only the inbox is checked. If your own email rules move a message into another folder before we see it, it won't be read.
• The password only gives us access to that one mailbox. It's stored encrypted and never shown to anyone.

When it stops

At some point the connection will probably stop working, for example when someone changes the password, an app password gets cancelled, the account is set up again, or the provider changes its rules. When that happens, the mailbox is marked as needing attention on Settings → Mailboxes, with the mail server's own error message next to it. Every owner and administrator at your firm is emailed about it, so you'll hear about it straight away.

You won't lose any emails while it's stopped. They stay in the mailbox, and they're read in on the first check after you reconnect.

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

When it won't connect

If your provider won't allow it

Some providers won't allow it, and some only allow it with a password you'd rather not share. Either way, there's another option that works just as well.

Forward the inbox to your own WorkOrders address instead. Set up a rule in your mailbox that forwards incoming email to your yourfirm@jobs.workorders.nz address. You'll find the address at the top of Settings → Mailboxes, with a button to copy it. Your customers keep writing to the address they've always used, the emails still arrive in your inbox as usual, and a copy comes to WorkOrders and becomes a job.

You don't give us any passwords, nothing breaks when someone changes a password, and a forwarded email is read just like a fetched one, with the same sender, subject and attachments. If you set up forwarding and later connect the same mailbox over IMAP as well, you won't get everything twice. An email that arrives both ways only makes one job.

Your own WorkOrders address explains how to use it, and how work gets into WorkOrders compares all four ways if you're still deciding.