## TL;DR
Send the welcome email to an address that exists at send time, through a healthy sending path. Check whether the workflow mailed a personal address incorrectly, mailed the corporate mailbox before it existed, or hit a sending limit or block, fix the ordering so mailbox creation precedes the welcome send or use the approved personal-email step, and resend with the correct joining details.

```text
provisioning welcome email failed to send: onboarding notification error for new hire
```

## Use this when
- The welcome or day-one instructions email errors in the workflow for one or more hires.
- The hire mailbox was created after the email step ran, or the HR email value is a personal address in the wrong field.
- Other workflow emails to managers send successfully at the same time.

## Not for this skill when
- The email sent but landed in spam at the hire personal provider. That is deliverability coaching, not a send failure.
- All outbound mail from the platform fails. Repair the platform mail configuration first.

## Steps
1. Open the workflow notification log and the hire record in HR for the affected hire and capture the full error detail, the operation that failed, and the identifiers involved, rather than working from the summary banner alone. Keep one hire as the test case for every change so cause and effect stay clear. Verify: the full error detail and one test hire are recorded
2. Read the send failure detail for the hire, noting the recipient address the workflow used, the sending identity, and the provider response, distinguishing a nonexistent recipient, a rejected sender, and a throttling response. Verify: the failing recipient and provider response are recorded
3. Fix the recipient source: confirm the field the workflow reads holds the intended address, personal email for pre-start messages or corporate email after the mailbox exists, and correct the HR record or the field mapping where they diverge. Verify: the hire downstream address check passes against the intended field
4. Apply the correction in the onboarding workflow and save it, then re-run provisioning for the single test hire only and read the fresh log entry end to end. If it still fails, treat the new detail as the current cause and do not stack further changes on top. Verify: the test hire provisions successfully or a new specific detail replaces the old one
5. Fix the ordering: sequence the welcome step after mailbox creation is confirmed when it targets the corporate address, or split the flow into a pre-start message to the personal address and a day-one message to the corporate mailbox, each with suitable content. Verify: the hire downstream sequence check passes in the workflow design
6. Resend the welcome message to the affected hire with the current joining details, start date, location, and first-day contacts, and confirm receipt by a reply or a delivery plus open signal the platform provides. Verify: the hire downstream checks pass with receipt confirmed

## Why it happens
Welcome emails fail at the intersection of timing and identity: the most natural recipient, the new corporate mailbox, does not exist until provisioning creates it, while the address that does exist, the personal email in HR, is often stored in a field the workflow does not read or should not use after start. Sending platforms report the result as a generic notification error that hides which side of the timing line the step fell on. Splitting pre-start and day-one messages by recipient reality and gating the corporate send on mailbox existence makes the flow match how onboarding actually unfolds.

## Variants and edge cases
### Sender blocked as spam by the platform
A sending domain missing its authentication records gets rejected by strict receivers. Publish the standard sender authentication records for the sending domain with the mail admin.

### Welcome email contains wrong start details
If the send succeeds with stale content, the workflow is reading an old hire record version. Refresh the run data from HR before resending.

### Manager copy fails while hire copy works
Treat each recipient leg separately; the manager address usually comes from the manager record, whose own data quality is the likely fault.

Compatibility: Applies to onboarding notifications from Okta Workflows, HR platforms, and ITSM flows using SMTP or mail APIs. Requires workflow admin access.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gHnJ5XtxIAjPvTB-vJZwUw