-
Notifications
You must be signed in to change notification settings - Fork 0
docs: add connected account authorisation guide #44
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,220 @@ | ||
| --- | ||
| title: "Connect Google and Microsoft accounts" | ||
| description: "Prepare your organisation, import accounts, and authorise Google Workspace or Microsoft 365 mailboxes for sending." | ||
| keywords: | ||
| [ | ||
| "Google Workspace", | ||
| "Microsoft 365", | ||
| "Gmail OAuth", | ||
| "Outlook OAuth", | ||
| "bulk account authorisation", | ||
| "sending accounts", | ||
| ] | ||
| --- | ||
|
|
||
| Use this guide to connect Gmail, Google Workspace, Outlook, or Microsoft 365 accounts that Sendmux will use for sending. For a large account pool, import the account list first, then authorise each pending account from its row. | ||
|
|
||
| <Info> | ||
| You need permission to manage sending accounts in Sendmux and sign-in access | ||
| to every account you connect. If your organisation blocks third-party apps, | ||
| ask a Google Workspace or Microsoft Entra administrator to complete the | ||
| relevant preparation step below. | ||
| </Info> | ||
|
|
||
| ## Permissions Sendmux requests | ||
|
|
||
| Sendmux requests only the permissions needed to identify the account, keep the connection active, and send email. | ||
|
|
||
| | Provider | Sending permission | What it allows | | ||
| | --- | --- | --- | | ||
| | Google | `gmail.send` | Send email on behalf of the connected account. | | ||
| | Microsoft | Microsoft Graph delegated `Mail.Send` | Send email as the signed-in account. | | ||
|
|
||
| The connection also requests basic identity scopes so Sendmux can confirm which account completed the flow. Microsoft includes `offline_access` so the account can remain connected without an interactive sign-in for every send. | ||
|
|
||
| Connected accounts always send from the mailbox address that completed authorisation. You can set a sender display name and reply-to address, but a different **From Email** address requires a separately authorised account. | ||
|
|
||
| <Warning> | ||
| Sendmux does not need permission to read, change, or delete mailbox content. | ||
| Cancel the flow and contact Sendmux support if a provider prompt asks for | ||
| `Mail.Read`, `Mail.ReadWrite`, IMAP access, or permission to read and | ||
| permanently delete Gmail messages. | ||
| </Warning> | ||
|
|
||
| ## Prepare Google Workspace | ||
|
|
||
| Most organisations can skip this section. Complete it only when a Workspace policy blocks third-party apps or requires an administrator to configure them first. | ||
|
|
||
| <Steps> | ||
| <Step title="Open Google app access controls"> | ||
| In the Google Admin console, open **Security** > **Access and data control** > **API controls**, then select **Manage App Access**. | ||
| </Step> | ||
| <Step title="Configure Sendmux"> | ||
| Select **Configure new app**, search for `Sendmux`, and choose the Sendmux | ||
| OAuth app. Select the organisational units whose accounts will connect. | ||
| </Step> | ||
| <Step title="Limit access to the required Google data"> | ||
| Choose **Specific Google data**. Allow the Google sign-in scopes and the | ||
| Gmail scope described as **Send email on your behalf**. Finish and review | ||
| the configuration before continuing. | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| Google says changes can take up to 24 hours, though they often apply sooner. See <a href="https://knowledge.workspace.google.com/admin/apps/control-which-apps-access-google-workspace-data" rel="nofollow noopener noreferrer" target="_blank">Google's app access guide</a> for current administrator roles and controls. | ||
|
|
||
| <Note> | ||
| Administrator configuration allows the Sendmux app to request the approved | ||
| scopes. It does not connect every mailbox or give Sendmux domain-wide access. | ||
| Each account owner still completes the Sendmux authorisation flow. | ||
| </Note> | ||
|
|
||
| ## Prepare Microsoft 365 | ||
|
|
||
| Most Microsoft 365 organisations allow the delegated `Mail.Send` permission without a separate administrator step. If your tenant blocks user consent, approve Sendmux once before connecting the account pool. | ||
|
|
||
| <Steps> | ||
| <Step title="Open Microsoft account setup in Sendmux"> | ||
| Open **Accounts**, select **Add Account**, then choose **Outlook / Microsoft | ||
| 365**. | ||
| </Step> | ||
| <Step title="Open the administrator flow"> | ||
| Expand **Organisation requires admin approval?** and select **Open Admin | ||
| Consent Page**. | ||
| </Step> | ||
| <Step title="Review and approve"> | ||
| An authorised Microsoft Entra administrator signs in and reviews the | ||
| delegated permissions. The sending permission must be Microsoft Graph | ||
| `Mail.Send`. Approve only if the prompt matches the permissions described | ||
| on this page. | ||
| </Step> | ||
| <Step title="Return to the account list"> | ||
| Close the administrator tab after approval. Each account can now complete | ||
| its own **Authorise** flow. | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| Tenant-wide consent allows users in the organisation to connect Sendmux. It does not connect their mailboxes automatically. See <a href="https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent" rel="nofollow noopener noreferrer" target="_blank">Microsoft's tenant-wide consent guide</a> for current administrator roles and consent controls. | ||
|
|
||
| ## Connect one account | ||
|
|
||
| <Steps> | ||
| <Step title="Choose the account type"> | ||
| Open **Accounts**, select **Add Account**, then choose **Gmail** or **Outlook | ||
| / Microsoft 365**. For Microsoft, keep **Global (Commercial)** selected. | ||
| </Step> | ||
| <Step title="Start the provider flow"> | ||
| Select **Connect Account**. Sign in to the exact account you intend to add. | ||
| </Step> | ||
| <Step title="Review the permission"> | ||
| Confirm the account address and the sending-only permission, then approve | ||
| the connection. New Google Workspace accounts may first show Google's | ||
| welcome page. Complete that page, then restart the connection from Sendmux. | ||
| </Step> | ||
| <Step title="Confirm the result"> | ||
| Sendmux returns to **Accounts**. The account should show **Active**. If the | ||
| provider rejected or cancelled the flow, use **Authorise** or | ||
| **Re-authorise** beside the account to try again. | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| ## Connect a large account pool | ||
|
|
||
| Importing creates the account records in one operation. Provider sign-in still happens once per account because each mailbox receives its own revocable OAuth credential. | ||
|
|
||
| <Steps> | ||
| <Step title="Prepare the import file"> | ||
| Open **Accounts** > **Accounts** > **Import Accounts**, then select | ||
| **Download template**. Keep the header row unchanged. | ||
|
|
||
| Fill at least these columns for each connected account: | ||
|
|
||
| | Column | Value | | ||
| | --- | --- | | ||
| | `name` | A unique account name. | | ||
| | `type` | `gmail_api` or `outlook_api`. | | ||
| | `oauth_user_email` | The account that must complete authorisation. | | ||
|
|
||
| You can also set its delivery group, sender display name, reply-to details, | ||
| quotas, and routing weight in the same file. Sendmux ignores `from_email` | ||
| for connected accounts and uses `oauth_user_email` as the sender address. | ||
| </Step> | ||
| <Step title="Import the accounts"> | ||
| Upload the file, review accepted and rejected rows, then select **Import**. | ||
| New Google and Microsoft accounts appear as **Pending** because imported | ||
| files never contain connected-account credentials. | ||
| </Step> | ||
| <Step title="Work through pending accounts"> | ||
| Filter the account list by **Pending**. Select **Authorise** beside the first | ||
| account, verify the email address at Google or Microsoft, and complete the | ||
| provider flow. Repeat for the remaining accounts. | ||
| </Step> | ||
| <Step title="Check the pool"> | ||
| Remove the **Pending** filter and confirm every connected account is | ||
| **Active**. Review any **Error** row and use **Re-authorise** after correcting | ||
| the provider-side issue. | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| <Tip> | ||
| Prepare Google or Microsoft administrator consent before starting a large | ||
| batch. This removes organisation-policy interruptions, while keeping each | ||
| mailbox connection separate and revocable. | ||
| </Tip> | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| <AccordionGroup> | ||
| <Accordion title="An imported account stays Pending"> | ||
| Pending is expected until that account completes OAuth. Select | ||
| **Authorise** beside the account. If the action is not visible, confirm that | ||
| your Sendmux role can manage sending accounts, then refresh the page. | ||
| </Accordion> | ||
|
|
||
| <Accordion title="Google says the app is unverified or asks to read and delete mail"> | ||
| Do not continue through **Advanced**. The expected Gmail permission is | ||
| **Send email on your behalf**. Cancel the flow and contact Sendmux support | ||
| with the team, account address, and time of the attempt. | ||
| </Accordion> | ||
|
|
||
| <Accordion title="Microsoft says an administrator must approve the app"> | ||
| Use **Add Account** > **Outlook / Microsoft 365** > **Organisation requires | ||
| admin approval?** > **Open Admin Consent Page**. After an authorised Entra | ||
| administrator approves delegated `Mail.Send`, restart **Authorise** for the | ||
| affected account. | ||
| </Accordion> | ||
|
|
||
| <Accordion title="The wrong Google or Microsoft account appears"> | ||
| Cancel the provider flow. Return to the matching account row and select | ||
| **Authorise** again. Check the address shown by the provider before you | ||
| approve access, especially when several accounts are signed in in the same | ||
| browser. | ||
| </Accordion> | ||
|
|
||
| <Accordion title="Sendmux reports too many authorisation attempts"> | ||
| Stop repeating the flow. Refresh **Accounts** and retry once from the | ||
| account's own **Authorise** or **Re-authorise** action. If the message | ||
| returns, contact Sendmux support with the team, account address, and | ||
| timestamp. This message is not a sending-account capacity limit. | ||
| </Accordion> | ||
| </AccordionGroup> | ||
|
|
||
| ## Related guides | ||
|
|
||
| <Columns cols={2}> | ||
| <Card title="Sending accounts" icon="mail" href="/guides/sending-accounts"> | ||
| Import, configure, monitor, and route sending accounts. | ||
| </Card> | ||
| <Card title="Delivery groups" icon="route" href="/guides/delivery-groups"> | ||
| Route sending keys through a selected account pool. | ||
| </Card> | ||
| <Card | ||
| title="Cold email outreach" | ||
| icon="bullseye" | ||
| href="/use-cases/cold-email-outreach" | ||
| > | ||
| Build a GTM sending pool with per-account caps. | ||
| </Card> | ||
| <Card title="Teams and access" icon="users" href="/guides/teams-access"> | ||
| Give operators the role they need to manage accounts. | ||
| </Card> | ||
| </Columns> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This OpenAPI spec edit changes the committed source used to generate the Postman collections, but the commit does not include any
postman/*.postman_collection.jsonupdates. In CI, the drift gate regenerates collections fromopenapi-app.jsonand compares them withpostman/, so spec changes need the generated snapshots committed in the same change to avoid drift failures and stale Run in Postman artifacts.AGENTS.md reference: AGENTS.md:L17-L19
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
False positive — npm run postman:check regenerated all three collections into a temporary directory and they byte-match the committed postman snapshots; these schema-property description-only changes are not emitted by the current transformer. Docs CI passed the same drift gate.