How work gets into WorkOrders

Four ways, one board

A work order is a work order however it arrived. Whether somebody emailed you, whether it came out of another system, or whether a customer typed it in themselves, what lands on the board is the same thing: a job with a customer, an address, and the original request kept alongside it.

There are four ways in. You do not have to choose only one — most firms end up using two — but it is worth knowing what each is for before you start telling people where to write.

1. Your own WorkOrders address

Every company gets an address the moment it is created, something like yourfirm@jobs.workorders.nz. It exists before you have finished setting anything else up, it cannot be switched off, and anyone who emails it gets a job on your board.

Nothing to set up at all. No password, no mailbox credentials, no changes to your domain. You will find it on Settings → Mailboxes, at the top, with a button to copy it.

The cost is that it is a new address, and your customers do not know it yet. That is fine if you are putting it on a website contact form, on a maintenance agreement, or on the van — and it is very nearly free if you point your existing inbox at it, which is the option most firms end up on. See your own WorkOrders address for what to do with it.

2. A mailbox you already have

If requests already arrive at an address your customers have written to for years — the one on the invoices — you can leave that exactly as it is and have WorkOrders read the mailbox instead. Any mailbox that speaks IMAP will do, which in practice means all of them: Gmail, Microsoft 365, Outlook, whatever your host gives you.

The mailbox is checked every five minutes. Mail is read, never deleted, and never marked as read, so anyone else watching that inbox sees it exactly as they left it.

The cost is credentials. You need a username and password for the mailbox — on Gmail and Microsoft 365, an app password rather than the everyday one — and a password can be revoked, expire, or be tidied away by somebody who did not know what it was for. When that happens the connection stops, and it has to be reconnected by hand. Read connecting a Gmail mailbox for the whole procedure; it is the fiddliest of the four, and it is the one with a page of its own for that reason.

3. Another system raising jobs over HTTP

If the work starts somewhere else — a building management system, a property manager's own software, a maintenance schedule you already run — that system can raise the job directly rather than sending an email about it. It posts to /api/v1/integration/work-orders using a key you create under Settings → API keys, and what arrives is an ordinary work order.

This one needs somebody who writes software, so it is not a choice you make on your own — it is a choice you make when the other system's people ask what to integrate with. See raising jobs from another system for creating a key and what to hand your integrator, and the developer reference for the full request format and how to try it without signing anything.

4. A customer raising a request in the portal

Your customers can see their own jobs in a portal — the page they reach from the link in their status emails. You can also let them start one there, with a short form describing what needs doing and where.

This is off until you turn it on, on Settings → Your company. It is off by default on purpose: switching it on puts a form in front of every customer you have, and plenty of firms would rather every request came through a person who knows the customer.

It is not open to the public. To use the form, a customer has to be signed in to the portal, and signing in means clicking a link emailed to an address you already hold a customer record for. The link at the bottom of a status email shows one job to whoever has it; the request form needs the stronger thing. A request raised this way arrives marked as coming from the portal, with the customer already filled in — it is read off their record rather than typed into the form, so nobody can raise a request in somebody else's name.

So which one?

For most firms the honest answer is both of the first two, without connecting anything: keep the address your customers know, and set a rule in that mailbox to forward everything to your WorkOrders address. You get the new system without asking a single customer to change what they type, and without giving anyone a password.

• Starting fresh, or happy to hand out a new address? Use your WorkOrders address on its own. It is the only option with nothing to break.
• Want to keep the address customers know, with no credentials? Forward that inbox to your WorkOrders address.
• Want the mail filed as it is processed, or cannot add a forwarding rule? Connect the mailbox over IMAP.
• Work arriving from another system? The API, alongside any of the above.

Two ways in does not mean two jobs

This is the question everybody asks next, so: the same email arriving by two routes only ever makes one job. If you forward your inbox to your WorkOrders address and connect that same inbox over IMAP, we recognise the second copy and do not raise a second work order for it.

Every email carries an identifier its sender's mail program gave it, and we remember the ones we have seen for your company. Two copies of one message share that identifier; two genuinely separate emails never do. Which means you can run both routes at once — during a changeover, say — without anybody having to close duplicates all week.

If something you expected has not turned up at all, or has turned up twice, that is its own page: an email did not become a job covers what is deliberately never made into one, and how long to wait before worrying.