Connect a Gmail mailbox

Do you actually need this?

You need this page if requests already arrive at a Gmail address your customers know — the address on the van, on the invoices, on the website. Connecting it means WorkOrders reads that inbox and turns what lands there into work orders, without anyone changing the address they have always used.

If that is not your situation, you can skip the whole thing. Every company gets its own address the moment it signs up — something like yourfirm@jobs.workorders.nz, shown on Settings → Mailboxes — and anything sent there becomes a work order with no setup at all.

There is also a middle option worth knowing about, because it is genuinely easier than what follows: set up a forward in Gmail to that jobs.workorders.nz address and leave it at that. Gmail keeps delivering to your inbox as it always has, and a copy comes to us. It is not a second-class route — a forwarded message is read exactly the same way — and if you later connect the mailbox properly as well, you will not end up with two of everything: we recognise the same message arriving twice and only ever raise one job from it.

Connecting over IMAP is worth the extra ten minutes when you want the mail filed as it is processed, or when you would rather not have a forwarding rule somebody can turn off by accident.

Before you start: turn on 2-Step Verification

This is the step everyone gets stuck at, so do it first. Google will not show you the app-password screen at all until 2-Step Verification is switched on for the account. Not greyed out — simply not there. If you go looking for app passwords first, you will conclude the feature does not exist.

1. Sign in to the Google account that owns the mailbox, and open myaccount.google.com/security.
2. Find 2-Step Verification and follow it through.
3. You will need a phone to receive a code or approve a prompt. Once it says it is on, come back.

If the mailbox belongs to a shared account that several people sign into, decide now whose phone the second step goes to. It is not a decision you want to be making again at seven in the morning.

Create an app password

An app password is a 16-character password that works for one thing and nothing else. It cannot be used to sign in to Gmail in a browser, it cannot change the account's settings, and you can revoke it on its own without touching the real password — which means nobody has to go around re-typing the account password on every phone in the firm.

This is safer than giving us the everyday password, not riskier. You may have seen Google warn about "less secure apps" and wonder whether this is one of them. It is not. App passwords are Google's own supported mechanism for exactly this situation — a program that connects to a mailbox and is not a web browser — and the "less secure" warning is about handing over the account password itself, which is the thing an app password lets you avoid.

1. Go to myaccount.google.com/apppasswords. You will be asked to confirm your password.
2. Give it a name you will recognise in a year — WorkOrders does the job. The name is only a label; it does not change what the password can do.
3. Google shows you 16 characters, usually in four groups of four. Copy them now. This is the only time it is ever shown, and there is no way to read it back — if you lose it you simply delete that entry and make another.

The spaces do not matter. abcd efgh ijkl mnop and abcdefghijklmnop are the same password, so paste it however it comes.

If you are on Google Workspace

A Workspace account — a Gmail on your own domain, rather than @gmail.com — is under an administrator's control, and an administrator can switch app passwords off for the whole organisation. If that has been done, the app-passwords page will simply tell you the setting is not available for your account, even with 2-Step Verification on. It is not something you can fix from your own settings.

You have two ways forward: ask whoever administers your Google account to allow app passwords, or use the forwarding approach described at the top of this page, which needs nothing from an administrator at all.

Fill in the connect screen

In WorkOrders, go to Settings → Mailboxes and choose Connect IMAP. You need to be an owner or an administrator to see it. Then fill it in like this:

• Mailbox address — the Gmail address your customers write to.
• Display name — what this mailbox is called inside WorkOrders, for when there is more than one. Something like Service requests.
• IMAP server — imap.gmail.com
• Port — 993
• Encryption — SSL / TLS (port 993)
• Username — the full Gmail address again, including the part after the @. Not just the bit in front of it.
• App password — the 16 characters from the step above. Not the password you sign in to Gmail with.
• Subject prefix — optional. Whatever you type here is added to the front of every subject line from this mailbox, exactly as typed, so you can tell at a glance which inbox a job came from when you are running more than one. Include the trailing space if you want one: [Auckland] .

Now press Test connection before you press Connect mailbox. The test signs in and reports back without saving anything, so you can correct a typo and try again as often as you like at no cost.

Nothing is saved unless the credentials work. A mailbox cannot exist here in a state we have never successfully connected to — which is deliberate, because the alternative is a mailbox that sits 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 after that

• 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, which is 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.
• The app password gives us access to that one mailbox and nothing else. It is stored encrypted, and it is never shown back to anyone — including you, which is why the field is left blank when you come back to edit the connection.

When it stops working

Sooner or later it will: somebody deletes the app password during a tidy-up, or turns 2-Step Verification off, or the account gets rebuilt. When that happens the mailbox is marked as needing attention on the Settings → Mailboxes screen, with the server's own words shown next to it, and everyone in the firm who is an owner or an administrator gets an email saying so. You do not have to notice it yourself.

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

To fix it: delete the old app password in your Google account, create a fresh one the same way as above, then press Reconnect next to the mailbox and paste the new 16 characters in. Everything else is remembered.

When it will not connect