Field notes · microsoft-365
Microsoft 365 onboarding: licenses, mailbox timing, Teams
Directory sync runs every 30 minutes and a new mailbox is not instant. How I sequence sync, licensing, and mailbox checks so day-one access actually works.
The account exists and the request that created it was clean. Now comes the half of onboarding that runs on someone else’s clock. Microsoft 365 onboarding is not a sequence of commands; it is a sequence of waits. Every failure I have had in it came from treating an eventually-consistent system as if it were instant.
My first version was one synchronous script: create the account, assign the license, send the welcome email, done in a minute. The welcome email bounced. It bounced because I had sent mail to a mailbox that would not exist for several more minutes, from a script that had already declared victory. I learned the whole lesson of this post from that bounce: in the cloud half of onboarding, “I ran the command” and “the thing exists” are different events, minutes apart.
Key takeaways
- Every Microsoft 365 onboarding step waits on the one before it, and none of the waits are instant.
- Directory sync is the first and longest gate: the default delta cycle runs every 30 minutes.
- Assign licenses by group membership, so licensing becomes a side effect of the provisioning you already do.
- Never sleep and hope. Poll for the thing you need and proceed only on a positive result.
- Split provisioning into stages that each verify their inputs exist, instead of one synchronous run.
Why does Microsoft 365 onboarding fail on timing?
Because four systems hand off to each other and each handoff has lag. Directory sync is the scheduled replication that copies your on-prem accounts up to the cloud directory, and it is the first handoff: the account must sync before a license can be assigned. The license must land before the mailbox provisions. The mailbox must provision before anything can be mailed to it or delegated on it. Group memberships ripple into Teams on their own schedule.
None of those delays is a bug, and none is under your control. Microsoft’s sync scheduler documentation puts the default delta sync at every 30 minutes, and mailbox provisioning after licensing takes minutes more. A script that ignores those windows works in the demo, where you wait, and fails on real hires, where you don’t.
What is the right order of operations?
Five stages, each gated on evidence that the previous one finished. The table is the system; the rest of this post is how to check each gate.
| Stage | Waits on | How you know it’s done |
|---|---|---|
| Directory sync | Account creation (the provisioning script) | The user resolves in the cloud directory |
| License assignment | Sync | License shows on the cloud user |
| Mailbox provisioning | License | The mailbox resolves, not just the user |
| Welcome steps (mail, delegations) | Mailbox | Test message accepted; delegation applies |
| Teams and group ripple | Group memberships | Person appears in the team roster |
How do you trigger and wait for the sync?
Trigger a delta sync so the new account doesn’t wait out the full half-hour window, then poll the cloud directory until the user actually appears. The trigger is polite; the poll is the gate.
# Nudge the sync rather than waiting out the 30-minute window.
Invoke-Command -ComputerName $syncServer -ScriptBlock {
Start-ADSyncSyncCycle -PolicyType Delta
}
# Gate on the user existing in the cloud, not on time passing.
$deadline = (Get-Date).AddMinutes(20)
do {
Start-Sleep -Seconds 60
$cloudUser = Get-MgUser -Filter "userPrincipalName eq '$upn'" -ErrorAction SilentlyContinue
} until ($cloudUser -or (Get-Date) -gt $deadline)
if (-not $cloudUser) { throw "User $upn never appeared in the cloud directory." }The shape of that loop matters more than the cmdlets in it. It exits only when the user is positively found, and if the probe itself fails or the user never shows, it ends in a loud error rather than a quiet success. My first loop exited when the lookup “stopped failing,” and a transient auth error made it proceed with nothing. Poll for presence, never for the absence of an error.
Should licenses come from a script or a group?
From a group. Group-based licensing means a license is attached to a group and everyone in that group receives it automatically, which means the provisioning script already does the licensing when it does the group adds. One less API call, one less thing to make idempotent, and the license map lives next to the department-to-groups map where I already maintain access.
The script-based alternative works, and I ran it for a while. What moved me off it? Drift. A license assigned by script is a fact nobody re-checks, while a license assigned by group is recomputed from membership every time. When someone changes departments, the group change fixes the license too. The same “move the checklist into data” argument from the onboarding post applies; the group is the data.
When can you actually send the welcome email?
When the mailbox answers for itself, and not before. A licensed user and a provisioned mailbox are separate facts minutes apart, so the welcome stage opens with its own gate: poll until the mailbox object resolves, then proceed with the welcome message, the manager’s delegation, and whatever else touches mail.
# A user with a license is not yet a mailbox. Gate on the mailbox itself.
$deadline = (Get-Date).AddMinutes(30)
do {
Start-Sleep -Seconds 60
$mbx = Get-EXOMailbox -Identity $upn -ErrorAction SilentlyContinue
} until ($mbx -or (Get-Date) -gt $deadline)
if (-not $mbx) { throw "Mailbox for $upn did not provision in time." }This is the gate whose absence bounced my first welcome email. The fix was not a longer sleep. Sleeps encode a guess about someone else’s infrastructure, and the guess goes stale. The poll encodes the actual question: does the mailbox exist yet?
What broke, and what I would change
Teams membership taught me to stop promising times. The person lands in the right team via group membership, but in my experience the ripple from a group change to a visible roster takes anywhere from minutes to hours, and I never found a knob that makes it prompt. So I stopped telling managers “Teams will be ready at 9:00” and started saying “by end of day one.” Setting the expectation honestly cost less than chasing the lag ever did.
Structurally, I would split the stages sooner. My onboarding now runs as two passes. The directory pass is the provisioning script plus the sync nudge. The cloud pass starts by verifying its inputs exist, and it ends by reporting what it confirmed, not just what it attempted. When a run dies in the middle, and eventually one will, each pass is idempotent and safe to re-run. The bounced welcome email was embarrassing exactly once. The design change is why. The same lesson runs the other way through this lifecycle, too: offboarding revokes sessions explicitly instead of waiting for a disabled account to ripple through the same lag.
FAQ
Why does a new user’s mailbox take so long to appear?
Because three waits stack: directory sync (default delta cycle every 30 minutes), license application after sync, and mailbox provisioning after licensing. A new hire’s mailbox commonly trails account creation by most of an hour unless you trigger the sync and gate each following step.
Should you assign Microsoft 365 licenses with a script or a group?
Use group-based licensing. The provisioning script already manages group membership, so licensing becomes a side effect of the access work, and membership recomputes the license when people move roles. Script-assigned licenses drift because nothing ever re-evaluates them.
How long should an onboarding script wait for sync or a mailbox?
Do not pick a wait; pick a check. Poll for the specific object you need (the cloud user, then the mailbox) roughly once a minute against a generous deadline, proceed only on a positive find, and fail loudly at the deadline. Fixed sleeps are guesses that go stale.
Can you onboard into Microsoft 365 in one synchronous run?
Not reliably. The cloud half is eventually consistent, so a single run either sleeps through the delays (slow and still a guess) or outruns them (my bounced welcome email). Two idempotent passes, directory then cloud, each verifying its inputs, is the version that survives real hires.