blog·6 min read

A separate email address per supplier

Every supplier mails its invoices to its own address. That way the app knows who is sending before it opens the PDF. How we built it, and what we had to lock down along the way.

The suppliers mail their invoices to the accounting department. Can the
app pull them out of a mailbox itself, without anyone forwarding them?

At a drinks wholesaler with a liquor store, purchase invoices arrive by email. Someone forwards them to the app, or drags them into an upload window. That works, but it is a manual step every single time, and a step nobody takes when things get busy.

So we built a mailbox for it. Not one address where everything lands, but a separate address per supplier. It is live, on a test domain we run ourselves. The client stays anonymous and there are no amounts, prices or margins here.

Why an address per supplier

Reading an invoice starts with one question: whose is this? Normally you work that out from the PDF itself, which means your reader has to succeed before you know whether you can trust it.

With a separate address per supplier, the origin is a fact before you open the file. If the address does not match what the reader pulls out of the PDF, that is a signal and not a detail.

An address is also something you can retire. If it starts floating around in an address book, you create a new address for that supplier and deactivate the old one. The trusted senders come along, so nobody has to approve anything again.

What the address looks like

The address is the supplier's name, a hyphen and eight random characters. Next to those there is one general address for anything that fits nowhere.

Those eight characters come from an alphabet without the zero, the letter o, the one, the l and the i. The reason: the address sometimes gets typed in by hand by someone at the supplier. Mixing up a zero and an o produces mail that quietly disappears into the catch-all, and then you spend an hour looking for nothing.

The mail server sits on its own subdomain, with a catch-all into a single mailbox, so no mailbox has to be created for each new address. The mail server puts the original recipient in a header, and that header is what the app reads; without it you would not know who the message was addressed to after a catch-all.

Reading the mailbox without touching it

An app that reads mail can lose mail. So we made the mailbox side so small that little can happen.

It is a small IMAP client of our own over TLS, without a library. Only nine commands can reach the server: ask for capabilities, log in, list folders, create a folder, open a folder, search, fetch a message, move a message and log out. If a command is not on that list, it does not go in.

Fetching uses the variant that does not mark the message as read. The app cannot delete, expunge, set flags or send mail, and a test makes sure those commands appear nowhere in the code. After processing, the message moves to the Processed folder, or to Unknown if it was not addressed to an invoice address. Nothing is ever thrown away.

Only the production environment is allowed to actually connect. On the development box the app reads from a folder of sample messages. Two readers on the same mailbox would move each other's mail.

Five gates per message

Every message goes through the same five checks, in this order:

  1. The address. Only mail to a known invoice address counts; the rest leaves no trace in the app.
  2. Seen before? A message ID that has already been processed is only moved. A supplier who sends the same mail twice does not produce a second invoice.
  3. The attachments, by content. An attachment is a PDF or an invoice XML because it looks like one, not because its name ends in .pdf. Images and the body of the mail are skipped quietly, a zip is not unpacked, and there is a maximum per mail and per attachment.
  4. The sender. An unknown sender holds the attachment aside until someone trusts it once. This is a filter, not a security measure: a sender can be faked. On shared mail providers we trust the address and not the domain.
  5. The content. The supplier the reader pulls out of the PDF has to match the address the mail came in on. After that the file goes through the same upload a person uses, with the checks for duplicates and the to-the-cent check.

Anything held aside keeps the file, so someone can still read it in with one click in the app. None of this goes to the accounting; the app reads and stores.

The mistake we did not see coming

The first setup read the mailbox in the same background worker as the rest of the work. That was fine until a nightly sync failed. The next run therefore fetched every price line again, 46 minutes straight, and during those 46 minutes the mailbox was not read.

That is exactly the wrong moment to go quiet. The fix is a worker of its own with its own queue, separate from anything that talks to the accounting. There was one more trap in that: the message bus of our framework delivers a message to every queue that matches it, so a task message matching both queues arrived twice. A message belongs to exactly one queue; we had to make that explicit.

And a lesson from the first real mail: it worked, but an employee who saw nothing after three minutes uploaded the invoice by hand. The app politely said "already present", so nothing went wrong. Even so, we moved the round from every five minutes to every minute, with the line "reads every minute, last read at" on screen.

What we would take to the next one

Make the origin a fact, not a guess. An address per sender costs nothing and removes a whole class of doubt.

Never put a slow catch-up job in the same queue as something that has to be quick. This is not a mail problem, it is a queue problem.

Show that it is alive. One line saying "last read at" prevents manual work nobody needed to do.

Common mistakes

One address for all suppliers. Then your reader has to succeed before you know who is sending, and you cannot retire an address.

Ambiguous characters in an address people type by hand. A zero or a lowercase l costs you a search party.

Marking messages as read or deleting them while reading. Use the variant that changes nothing and move to a folder; then you can always go back.

Treating the sender as security. A sender can be faked. Use it to park noise, not to prove anything.

Letting dev and production read the same mailbox. Two readers move each other's mail, and it is not reproducible.

Processing mail invisibly. Then someone does it by hand as well.

What an integration on Exact Online can do is on connecting Exact Online. How we read invoices to the cent once they arrive is in reading PDF invoices to the cent. If you want this for your own stream of invoices, have a look at custom software.

MK
Maarten Keizer

Founder of Invoker. Over twenty years in hosting, system administration and web development; builds the Claude hosting himself and tests everything on our own servers first.

about maarten