⚠️ Beta — under active testing. This endpoint is not yet 100% publicly available. Access is limited to certain accounts, and the behavior and contract may change without notice. Reach out to the Mailivery team before integrating against it in production.

Onboards a Microsoft 365 / Outlook mailbox entirely through the Microsoft Graph API. Previously, inbox (IMAP) and sending (SMTP) access were each authorized separately — granted through OAuth permissions rather than stored credentials. This flow unifies both into a single Microsoft Graph authorization, so there is no separate IMAP or SMTP step.

The request should be sent as an HTTP POST to https://app.mailivery.io/api/v1/campaigns/ms-graph. Upon successful validation, the API returns a Microsoft OAuth consent URL. The campaign is created only after the mailbox owner authorizes access and Microsoft redirects back to Mailivery's callback.

Feature gate: the caller must be on the Microsoft Graph-only allowlist (canUseMicrosoftGraphOnly()). Callers who are not on the allowlist receive 403 MS_GRAPH_FEATURE_DISABLED.

Onboarding flow

1. POST this endpoint → receive data.url.
2. Send the mailbox owner to data.url → Microsoft consent screen.
3. The user authorizes → Microsoft redirects to Mailivery's callback → the campaign is created.

The resulting campaign has imap_type = "ms-graph" and smtp_type = "outlook" (free Microsoft domain) or "office 365" (corporate domain). Note that smtp_type is intentionally not ms-graph.

After the user completes OAuth — what your system must do

Once the mailbox owner finishes Microsoft consent, Mailivery creates the campaign in pending status and sends a webhook to your configured webhook URL. A pending campaign is not warming up yet — warm-up starts only after you confirm the connection on your side.

Your webhook handler should:

1. Confirm that this mailbox was actually expected. Compare the email in the webhook payload against your own records to make sure a real user in your system intended to connect this mailbox. This prevents accidental or unauthorized campaigns from going live.
2. If expected → start warm-up. Call the Start Warm-Up (for new campaigns) or Resume Warm-Up (for previously paused campaigns) endpoint to move the campaign from pending into active warm-up.
3. If not expected → ignore or delete. Either call the delete-campaign endpoint, or simply leave the campaign in pending — it will not send or consume resources while pending.