Connect a Gmail mailbox

Do you need this?

You need this page if requests already arrive at a Gmail address your customers know, like the address on the van, on the invoices or on the website. Connecting it means WorkOrders reads that inbox and turns what arrives there into work orders, and nobody has to change the address they've always used.

If that's not you, you can skip all of this. Every company gets its own address when it signs up, something like yourfirm@jobs.workorders.nz, shown on Settings → Mailboxes. Anything sent there becomes a work order with no setup at all.

There's also a simpler option: 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 WorkOrders. A forwarded message is handled exactly like any other. If you later connect the mailbox as well, you won't get two of everything, because WorkOrders recognises the same message arriving twice and only makes one job from it.

Connecting over IMAP takes about ten minutes longer. It's worth it if you want processed mail moved into its own folder, or if you'd rather not rely on a forwarding rule that someone could turn off by accident.

Before you start: turn on 2-Step Verification

This is where everyone gets stuck, so do it first. Google won't show you the app password screen at all until 2-Step Verification is switched on for the account. It isn't greyed out. It's just not there, so if you go looking for app passwords first, you'll think the feature doesn't 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 the steps.
3. You'll need a phone to receive a code or approve a prompt. Once it says it's on, come back here.

If several people sign in to the mailbox's account, decide now whose phone gets the codes. You don't want to be sorting that out at seven in the morning.

Create an app password

An app password is a 16-character password that you give to one program. It can't be used to sign in to Gmail in a browser, and it can't change the account's settings. You can also delete it on its own without changing the account's real password, so nobody has to re-enter that password on every phone in the firm.

It's safer than giving us your everyday password. You may have seen Google warn about "less secure apps" and wondered whether this is one. It isn't. App passwords are Google's own way of letting a program other than a web browser connect to a mailbox. The "less secure" warning is about handing over the account password itself, and an app password means you don't have to.

1. Go to myaccount.google.com/apppasswords. You'll be asked to confirm your password.
2. Give it a name you'll recognise in a year, like WorkOrders. The name is only a label and doesn't change what the password can do.
3. Google shows you 16 characters, usually in four groups of four. Copy them now. Google only shows it once, and you can't look it up again later. If you lose it, delete that entry and make another.

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

If you're on Google Workspace

A Workspace account (Gmail on your own domain, rather than @gmail.com) is controlled by an administrator, and an administrator can switch app passwords off for the whole organisation. If they have, the app passwords page will tell you the setting isn't available for your account, even with 2-Step Verification on. You can't fix that from your own settings.

You can either ask whoever looks after your Google account to allow app passwords, or use the forwarding option at the top of this page, which doesn't need 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, in case you have 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 @.
• 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, exactly as typed, to the start of every subject line from this mailbox. It helps you tell which inbox a job came from if you have more than one. Include a space at the end if you want one: [Auckland] .

Press Test connection before you press Connect mailbox. The test signs in and tells you how it went without saving anything, so you can fix a typo and try again as often as you like.

Nothing is saved unless the details work. So you'll never have a mailbox in the list that looks connected but has never actually worked.

What happens after that

• WorkOrders checks the mailbox every five minutes.
• Mail is never deleted. Once a message has become a work order, it's moved into a folder called WorkOrders-Processed, which is created for you the first time it's needed. The email is still there, so if anything goes wrong it can be checked later.
• Nothing is marked as read. If someone else also reads this inbox, their unread count stays as they left it.
• The app password only gives WorkOrders access to that one mailbox. It's stored encrypted and never shown to anyone again, including you. That's why the field is blank when you come back to edit the connection.

When it stops working

Sooner or later it will. Someone deletes the app password while tidying 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 error from the mail server shown next to it. Every owner and administrator in the firm also gets an email about it, so you don't have to spot it yourself.

Nothing is lost while it's stopped. The messages stay in the Gmail inbox, and WorkOrders reads them on the first check after you reconnect.

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

When it won't connect