Issue 67 App Only Email Sending

Why app-only mailboxes could not send email (issue #67)

A mailbox set to app-only authentication could receive mail perfectly well but could not send a single message. Reported in issue #67 by jbournestreamsystems, who also diagnosed it correctly and supplied a patch.

This page explains what was going wrong, in plain English, because the underlying cause is one small piece of Microsoft jargon that hides a genuinely important distinction.

The general setup guide is Mailbox authentication.

---

1. First, what /me and /users/... actually mean

When FreeITSM wants Microsoft to do something with a mailbox, it sends a web request to an address. That address has to say which mailbox you mean. There are two ways to say it:

You write	It means
/me/sendMail	"send from the mailbox belonging to whoever is holding this pass"
/users/support@yourcompany.com/sendMail	"send from this specific named mailbox"

/me is a convenience. It saves you naming the mailbox, because Microsoft can work it out from who signed in.

The catch is that it only works if somebody actually signed in.

Think of it as the difference between two kinds of building pass:

• A personal staff pass has your photo on it. If you hand it to reception and say "put this in my pigeonhole", they know exactly which pigeonhole, because the pass says who you are. That's /me.
• A contractor's master key has no name on it. It opens the doors, but it isn't anybody. Hand that to reception and say "put this in my pigeonhole" and the question is meaningless — you don't have one. You have to say "put this in the pigeonhole marked Support". That's /users/support@....

So /me is not a shorthand you can always use. It is only meaningful when the credentials belong to a person.

---

2. The two FreeITSM modes map exactly onto those two passes

	Delegated	App-only
How it authenticates	A human signs in through a Microsoft sign-in page	FreeITSM authenticates as itself, using a client ID and secret
Is there a "who"?	Yes — the token carries the signed-in person	No. Nobody signed in. There is no person anywhere in this
So /me means	That person's mailbox — works fine	Nothing at all

This is why the failure only ever appeared on app-only installs. If your mailbox is delegated, /me has always been correct and still is.

---

3. What was actually failing

Every place FreeITSM sends a message posted to the same hardcoded address:

https://graph.microsoft.com/v1.0/me/sendMail

On a delegated mailbox that resolves fine. On an app-only mailbox Microsoft refuses it outright, with an error that is admirably clear once you know the above:

/me request is only valid with delegated authentication flow. (HTTP 400)

Reading mail was never affected, because the code that reads a mailbox had already been taught the difference and names the mailbox properly. Only sending had been missed. That is why the symptom is so odd: tickets arrive by email, but nothing ever goes back out.

It affected every outgoing route, not just the workflow action in the bug report:

• workflow Send email actions
• ticket acknowledgement templates (new ticket, assigned, closed)
• SLA breach and warning alerts
• self-service portal account verification emails
• password reset emails

---

4. Two further faults underneath it

Correcting the address alone would have produced a fix that tested green and then failed intermittently in production. Two more problems were sitting behind it.

4a. The token was always fetched the delegated way

A token is the temporary pass; it expires after about an hour and has to be renewed. The two modes renew differently:

• Delegated is issued a refresh_token — a "renew this without making the human sign in again" voucher.
• App-only is never issued one. It doesn't need one. It just asks for a brand new token using the client secret, any time it likes.

The send path only ever knew the delegated method. Given an app-only mailbox it looked for a refresh voucher, found none, gave up and reported "authentication has expired" — which is doubly unhelpful, because nothing had expired and the message points you at the wrong problem entirely.

This was hidden by a coincidence: the mail-checking job stores a fresh token every time it collects mail. So as long as mail was being polled regularly, sending borrowed a token that happened to still be valid. Turn polling off, or send more than an hour after the last check, and it broke again — with a different error than the one you'd just fixed.

4b. "Can this mailbox send?" was asking the wrong question

Three places decided whether a mailbox was usable by checking whether it had a stored token.

That is a reasonable test for delegated, where a token only exists once somebody has signed in. It is the wrong test for app-only, which has no stored token until the first time it mints one — but can mint one whenever it wants.

The result: a brand-new, perfectly configured app-only mailbox was reported as "No email mailbox is configured" on password resets and portal emails. It would start working later, on its own, once mail had been collected once — which is exactly the kind of intermittent behaviour that makes a bug hard to pin down.

---

5. The fix

5.1 📁 The files involved

Colour key: ⚙️ shared logic · 🔌 API · 🖥️ module code · 📄 docs

🎨	File	What changed
⚙️	includes/mailbox_graph.php	the decision lives here. Added mailboxIsAppOnly() and mailboxCanSend(); mailboxResolveGraphBase() refactored onto the former
⚙️	includes/template_email.php	added templateGraphContext(); templateSendViaGraph() now takes the base path as a required third argument
⚙️	includes/self_service_email.php	portal verification email; ssGetSendingMailbox() now uses mailboxCanSend()
⚙️	includes/sla_notifications.php	SLA breach and warning emails
🖥️	workflow/includes/engine.php	the send_email action — the route in the bug report
🔌	api/auth/request_password_reset.php	password reset; also loses its private duplicate of the token refresher
📄	CHANGELOG.local.md, this wiki	logged as #1080

Two files were already correct and were deliberately left alone: api/knowledge/send_share_email.php and api/change-management/send_share_email.php both named the mailbox properly.

5.2 The shared helpers

The rule going forward is that auth mode changes three things, and nothing should re-derive any of them by hand:

Helper	Answers
mailboxIsAppOnly($mailbox)	Is this app-only? (Microsoft and auth_mode = app_only)
mailboxResolveGraphBase($mailbox)	/me or /users/<address>
mailboxCanSend($mailbox)	Can this mailbox send right now? — per §4b
templateGraphContext($conn, $mailbox)	the token and the address together, as one result

templateGraphContext() returning both halves at once is the important part. The token source and the endpoint are two answers to the same question, and issue #67 happened precisely because one was updated for app-only and the other wasn't. Handing them out as a pair makes them hard to get half-right.

---

6. Why this differs from the patch in the bug report

The reported patch was correct about the cause and fixed the visible symptom. It added a new mailboxAddress argument to the send function, passing the target mailbox address, or an empty string when there wasn't one.

This implementation differs in three ways, none of which is a criticism of the diagnosis — it was spot on, and it's what made the fix quick.

1. It reuses the existing decision rather than adding another one. FreeITSM already had mailboxResolveGraphBase(), which turns a mailbox into /me or /users/<address>, and the ticket-reply path already used it. Adding a second, separate way to work out the same thing would have meant two places to keep in step — and the bug itself was caused by exactly that kind of drift. So the send path takes the resolved base path from the existing helper instead of re-deriving it from an address.

2. It fixes the token and the eligibility test as well. The patch addressed the endpoint. As set out in §4, correcting only the endpoint leaves a mailbox that sends correctly until its borrowed token expires, then fails with an unrelated-sounding error. Both were fixed together because they are the same bug wearing two hats.

3. The new argument is required, with no default. Defaulting it to /me would have been the safer-looking choice, and it is the one to avoid: a default of /me recreates the exact silent wrong-endpoint behaviour being fixed. Any send path that forgets to pass it should fail loudly during development rather than quietly send from the wrong mailbox. There are five callers and they are all in this repository, so there is nothing to break.

---

7. How it was verified

Both halves were run against real Microsoft infrastructure on a live app-only mailbox, not simulated:

Workflow run	When	Result
139	before the fix	failed — /me request is only valid with delegated authentication flow (HTTP 400)
140, 141	after the fix	success — email delivered

Plus a 19-check logic test covering both modes, including two negative controls (the old logic has to fail the same assertions, or the test is proving nothing) and a check that templateSendViaGraph() really has no /me default left.

The most important of those checks is the least obvious one: delegated must still resolve to /me. A fix that simply sent everyone to /users/<address> would have looked like it worked on the reporter's install and broken every delegated install in existence.

---

---

8. A postscript: the same error message, a different bug

Switching the test mailbox back to delegated produced the identical error again:

/me request is only valid with delegated authentication flow. (HTTP 400)

Which looks precisely like the fix not working. It wasn't.

Changing a mailbox's auth mode cleared the recorded identity but left the stored token in place. The mailbox was now delegated, so the delegated path ran, found a token, and used it - except it was the app-only token minted during the test. Graph refuses an app-only token at /me, and says so in exactly the same words.

Two lessons worth keeping:

• The same message can have two causes. Here it was "the code asked the wrong question" the first time and "the credential is the wrong kind" the second. Reading the message alone would have sent you round in circles.
• Clearing an identity is not the same as clearing a credential. The mailbox went on looking authenticated, so nothing ever prompted for a fresh sign-in.

Fixed as #1081: changing the auth mode or the target address now clears token_data alongside the identity, and a token of the wrong kind is refused outright if one somehow survives. Nobody switches modes often, which is why it had gone unnoticed - we did it twice in an hour.

---

Related pages

• Mailbox authentication — setting up either mode, and the troubleshooting table
• Workflows — the send_email action
• Tickets — the module these mailboxes feed