Tom Hundley
🤖 Ghostwritten by GPT 5.4 · Fact-checked & edited by Claude Opus 4.6
A mid-May bug in Soundwave exposed a sharp Microsoft Graph trap: $search="from:..." returned zero messages for senders that were demonstrably present in the mailbox. The fix was not tuning the query or widening the search window. The fix was switching sender matching from $search to $filter, then treating every empty result as suspicious until proven otherwise.
That sounds small, but it is not. In email automation, a zero-result query looks exactly like a true absence: no messages found, nothing to act on, move on. If a cleanup engine uses that answer to skip, preserve, or delete, a silent zero stops being a search annoyance and becomes a correctness problem with safety implications. A second issue compounded it: under parallel fan-out, throttled requests could also look like no matches unless the client explicitly distinguished retryable failures from genuinely empty responses.
This post covers the specific gotcha, the before-and-after query shape, and the reliability rule it forced into the engine: never let an empty API result silently drive a destructive action.
TL;DR: Microsoft Graph $search="from:..." and $filter on the sender address are not interchangeable; $search produced silent zero results while $filter returned the real messages.
The original goal was straightforward. Soundwave needed to target messages by sender as part of an email automation cleanup pass. Microsoft Graph offers two plausible ways to do that:
$search with a query like from:sender@example.com$filter against the sender address fieldOn paper, both seem reasonable. In practice, they are not equivalent.
The failure mode was especially dangerous because it did not present as a hard error. There was no exception, no malformed query response, and no explicit warning that the query semantics were off. The request completed and returned an empty set. For a human debugging session, that is annoying. For an automated system, that is a trap.
Here is the illustrative pattern that failed:
GET https://graph.microsoft.com/v1.0/users/mailbox@example.com/messages?$search="from:sender@example.com"
ConsistencyLevel: eventualIllustrative empty response:
{
"value": []
}The sender really did exist in the mailbox. Messages from that address were visible through other inspection paths. But the $search call still returned nothing.
The working version used a field-level filter instead:
GET https://graph.microsoft.com/v1.0/users/mailbox@example.com/messages?$filter=from/emailAddress/address eq 'sender@example.com'Illustrative response:
{
"value": [
{
"id": "message-id-1",
"subject": "Example message",
"from": {
"emailAddress": {
"address": "sender@example.com"
}
}
}
]
}That query shape returned the real messages and immediately changed the reliability profile of the workflow.
This is the first practical lesson: if the requirement is reliable sender matching, the choice between $search and $filter is not stylistic. They can behave differently enough that one is unsafe for correctness-sensitive workflows.
$search is attractive because it feels expressive — it reads like the mailbox search box. But mailbox search behavior can depend on indexing state, query interpretation, and provider-specific semantics that are not the same thing as exact field matching.
That matters when the downstream action is consequential. A cleanup engine is not asking a fuzzy question like "show likely relevant mail." It is asking an exact question: "does this sender exist in this target set, yes or no?"
Those are different problem classes. Search is optimized for retrieval convenience. Filter is the better fit for deterministic selection.
TL;DR: A silent zero-result response is dangerous because it is observationally identical to "nothing exists," which can cause automation to make the wrong decision without raising an error.
The real lesson was not just that one Graph query shape misbehaved. It was that empty results were being granted too much authority.
In many systems, empty is treated as safe. No rows found. No files matched. No messages returned. Continue. But in production automation, empty can be ambiguous:
If the system collapses all of those into a single meaning, correctness drifts quietly.
For email automation, the failure modes are subtle:
| Empty result interpretation | What the system might do | Why that is dangerous |
|---|---|---|
| "Sender does not exist" | Skip a verification step | Real messages may be ignored |
| "No matching mail to protect" | Proceed with a cleanup wave | Messages that should be preserved may be touched |
| "No work needed" | Mark the mailbox as complete | The engine records a false state |
| "No issue detected" | Suppress retries or alerts | A transient provider problem becomes invisible |
The bug itself may look tiny. The blast radius comes from what the rest of the system assumes about the result.
A useful reliability rule emerged from this incident: zero is a claim, not a fact. It needs context.
Instead of treating an empty result as truth, treat it as a state that may require validation. In practice, that means asking:
When the answer to the last question is yes, the empty result should not be trusted on its own.
TL;DR: Under parallel fan-out, throttling can make an empty outcome look real, so clients must separate retryable provider pressure from truly empty query results.
The second lesson arrived alongside the first. Even after fixing sender targeting, parallel mailbox work introduced another ambiguity: requests under load could fail or degrade in ways that looked operationally similar to "no messages found."
That matters because fan-out is common in email automation. Systems often parallelize mailbox scans, sender checks, or folder passes to keep runtimes acceptable. But concurrency increases the odds of hitting provider limits.
Microsoft Graph documents throttling behavior and recommends honoring retry guidance when limits are reached. The key engineering lesson is not the existence of throttling itself. It is that, in a busy worker system, a throttled branch can be misclassified unless the client explicitly inspects the response and routes it through retry logic. Microsoft advises using the Retry-After header when present and implementing exponential backoff for rate-limited requests.
A robust client should distinguish at least these states:
| State | Meaning | Correct handling |
|---|---|---|
| Non-empty success | Matches found | Continue normally |
| Empty success | No matches returned | Treat as provisional if action is destructive |
| Throttled (HTTP 429) | Provider requested slowdown | Retry with backoff and preserve intent |
| Other transient failure | Temporary issue | Retry according to policy |
| Hard failure | Invalid request or auth issue | Stop and surface an error |
The important change was not just "add retries." It was "do not collapse throttled and empty into the same downstream meaning."
That led to a few practical rules:
This is one of those engineering details that sounds obvious after the fact. It rarely feels obvious when the first symptom is simply that some branches return no work.
TL;DR: The durable fix combined a query change with a state-machine change: use $filter for exact sender matching, and require validation before a zero can influence cleanup behavior.
The fix had two parts.
First, sender-targeting moved from $search to $filter using the sender address field directly. That made the query better aligned with the business question. The system was no longer asking a search engine to infer relevance. It was asking for exact matches on a known property.
Second, the engine stopped treating empty results as self-authenticating. A zero could still be legitimate, but it no longer automatically drove downstream decisions.
An illustrative pattern in pseudocode:
async function findMessagesBySender(graphClient, mailbox, sender) {
const response = await graphClient.getMessages({
mailbox,
filter: `from/emailAddress/address eq '${sender}'`
});
if (response.throttled) {
throw new RetryableThrottleError(response.retryAfter);
}
return response.items;
}
async function resolveSenderPresence(graphClient, mailbox, sender) {
const items = await retryWithBackoff(() =>
findMessagesBySender(graphClient, mailbox, sender)
);
return {
sender,
mailbox,
count: items.length,
trustedEmpty: items.length === 0
};
}The example is intentionally simple, but the design point is important: "empty" should only become "trusted empty" after the request path has passed through the same reliability checks as any other consequential read.
After the change, the workflow became more conservative in a productive way:
$filterThat is a useful pattern beyond Microsoft Graph. Any provider with search semantics, indexing layers, or rate limits can generate false confidence if the client mistakes a clean-looking response for a trustworthy one.
TL;DR: In any cleanup or deletion workflow, an empty API response should be treated as untrusted input until query semantics, retries, and provider behavior have been validated.
This is the broader engineering takeaway.
Destructive systems usually get careful review around authorization, audit trails, and rollback. They often get less scrutiny around absence. But absence is just another input, and sometimes it is the least trustworthy one.
A practical defensive checklist for this class of bug:
Microsoft documents $filter and $search as distinct query capabilities, and Graph also documents throttling behavior. The engineering mistake is assuming those capabilities are interchangeable in safety-sensitive flows. They are not.
If a provider can manufacture a false zero through query semantics or rate limiting, then empty is not neutral. It is hazardous until validated.
That is the right default for mailbox cleanup, record reconciliation, and any workflow where "nothing found" can trigger deletion, skipping, or a false completion state.
$search and $filter solve different problems. $search is designed around mailbox retrieval semantics and can depend on indexing state, tokenization, and provider-side query interpretation that is not equivalent to exact field matching. $filter targets a specific property directly using OData syntax, which makes it the safer choice when the system needs deterministic sender matching. Microsoft's own documentation notes that $search uses KQL (Keyword Query Language) semantics for messages, which introduces interpretation layers that $filter avoids.
No. $search can still be useful for exploratory retrieval or user-facing experiences where approximate relevance is acceptable. The problem is using it as the truth source for binary decisions such as whether a sender exists or whether a cleanup step is safe to execute. The risk scales with the consequence of a wrong answer.
Treat them as provisional until the request path has been validated. That usually means confirming the query method is exact enough, checking for throttling or transient failures, retrying with backoff when appropriate, and only then allowing a zero result to influence deletion or exclusion logic. The key distinction is between "empty after a validated read" and "empty after an ambiguous read."
In a fan-out worker, some branches may hit rate limits (HTTP 429) while others succeed. If the client collapses those branches into a generic empty outcome instead of preserving the throttled state, the system can incorrectly conclude that no messages matched when the provider was really asking the client to slow down and retry. The fix is to inspect response status codes before interpreting the body.
Use $filter when the question is exact and the result affects correctness or safety. Reserve $search for discovery-style tasks where approximate retrieval is acceptable and an empty result does not trigger irreversible behavior.
$search="from:..." can produce silent zero results even when the sender exists in the mailbox.$search and $filter is a reliability decision, not a style preference.$filter, bounded concurrency, and explicit handling for retryable provider states.The narrow lesson here is about one Microsoft Graph query trap. The broader lesson is about automation design: systems fail as often on ambiguous absence as they do on obvious errors.
Discover more content: