Set up email for your organization¶

The Email Connector in Tenant Admin sets the mail provider and sign-in choices available to your workspace. Each person then connects their own mailbox in WorkOS. Organization setup does not sign everyone in, create mail accounts or confirm that a message has reached its recipient.

Availability: The settings page has a connected read-and-save implementation. Confirm that Tenant Admin and your chosen mail provider are available in your environment. These draft steps describe the intended setup; a settings confirmation does not establish a working mailbox connection.

Decide who will manage the setup¶

A tenant administrator manages these settings. Ask the person responsible for your organization's email service to confirm the provider and permitted sign-in methods. For a custom service, obtain its incoming and outgoing server details and, when needed, its registered OAuth application details. OAuth lets someone grant mailbox access through their provider's sign-in page.

Zerohive operators must configure managed Microsoft 365 or Google Workspace applications before those choices can be saved successfully. Confirm that your selected provider is ready in your environment. Provider licensing, consent, account restrictions and network access may still affect individual connections.

For managers, this separates three responsibilities: the administrator chooses workspace policy, the email service owner supplies and authorizes provider access, and each person connects their mailbox. Plan provider changes with those owners because existing connections may need attention afterward.

Open the settings and choose a provider¶

1. Open Tenant Admin for the intended workspace.
2. Select Settings, then Email Connector.
3. If setup is new, use Mail provider to choose Microsoft 365, Google Workspace or Custom mail server. The intended setup shows the remaining settings after this choice.
4. Check that the provider matches the service hosting your organization's mail. Do not select a different provider just to get past an error.

The page also has an Open shared work memory link. That is a separate workspace guidance destination; it is not a required step for setting up mail.

Use a managed provider¶

For Microsoft 365, Managed by Zerohive server and OAuth application details are read-only in the intended setup. OAuth 2.0 is required and is the default sign-in method. Review the provider and choose Save Changes.

Google Workspace also uses a managed preset and requires OAuth 2.0 as its default. Its policy can additionally allow password or app-password sign-in. A permitted option does not guarantee that the provider or a particular account accepts it. Confirm the available choices with your administrator; the Google-specific setup controls remain unverified for this guide.

Managed application identifiers, addresses and permissions come from the configured preset. You do not enter your own application secret for either managed provider. A protected-secret indicator describes configured secret state; it is not a successful mailbox sign-in or a live secret-validity check.

Configure a custom mail service¶

Use the values supplied by your email service owner. Do not copy sample values from a preview.

1. Choose Custom mail server.
2. Under Sign-In Options, select at least one allowed method. Set Default sign-in method to one of the allowed choices.
3. Enter the incoming mail server, port and Connection security.
4. Enter the outgoing mail server, port and Connection security. Both servers are required for a custom setup, even if your immediate task is only reading or sending.
5. Choose the secure connection mode required by each server: TLS on connect or STARTTLS. Neither means that encryption is optional.
6. If OAuth 2.0 is allowed, complete the applicable OAuth Application details described below.
7. Review the settings and select Save Changes.

Incoming mail uses IMAP to read the provider's mailbox. Outgoing mail uses SMTP to submit messages. Valid server details and encrypted transport are required; successful setup still does not prove that a particular mailbox account can use them.

Supply OAuth application details¶

A custom OAuth application belongs to your organization. Obtain its application ID, HTTPS authorization address, HTTPS token address and exact provider permission names. The authorization address is where people approve access; the token address is used to obtain or renew that access.

Choose the application type that was registered with the provider. A confidential application requires a client secret. A public application does not accept a client secret. These are application types, not choices about making your mailbox public.

For a confidential application, enter the secret during initial setup or when replacing it. A previously saved secret stays hidden. Leaving the field blank means keeping the existing secret while the setup still uses a confidential custom application. It does not create a missing secret. A change to the provider or application type can make the old secret inapplicable.

When OAuth is not allowed, OAuth application details do not apply. Review the relevant fields after changing providers or sign-in methods, and resolve any validation error before saving.

Understand the save result¶

Select Save Changes once and wait while the page saves. When it receives a successful settings result, the page updates the form and saved-date label from the returned settings. A newly entered client secret is cleared from the form; the saved-secret indicator explains whether a secret is configured. This does not test whether the provider will accept it.

A successful save records workspace mail policy and settings. It does not send a test email, sign in a mailbox, revoke old provider access, or certify incoming and outgoing delivery. After setup, follow Connect your mailbox and verify the relevant read or send operation.

Treat the last-saved time as the time the settings changed, not the most recent successful provider check. Reopen the settings to reconcile a save whose result was lost. A hidden or unavailable saved secret cannot be compared by reading it back.

Coordinate changes with other administrators. Saving an older form can overwrite someone else's completed change. Reload current settings and compare the intended changes before saving again.

Changing providers replaces the selected preset when saved. Do not assume that all existing mailbox connections have been migrated, revalidated or disconnected. Review the affected users' connections and resolve failures before relying on email-dependent work.

Use assistance for organization settings¶

An authorized organization administrator can use the supported assistant integration to review the saved mail provider, permitted sign-in methods, server details and whether a client secret has been saved. This is separate from reading a person's mailbox. Administrator access is checked against current account, session, workspace membership, subscription coverage and applied plan entitlement; a previous successful read does not guarantee continued access.

If the assistant cannot verify workspace access, ask an authorized administrator to review subscription access and the actual workspace restriction. Keep the original settings or handoff reference. A restriction or unavailable check does not prove the mail provider failed or the previous settings were undone; do not switch providers or replace a secret simply to get past it.

The assistant's configuration summary does not test provider connectivity or prove that a user's mailbox works. A saved-secret indicator cannot tell you whether the provider will accept that secret. Continue with the person's connection and the actual reading or sending operation when checking readiness.

Changes belong in a protected settings form. Enter a required client secret there, never in a conversation. Settings reads and saves are connected, while a working assistant-to-form journey has not been verified. Follow the settings steps here when this page is available in your environment; an invitation from the assistant does not itself populate or save a form.

A settings save and its confirmation back to the assistant are separate events. If the return is lost, expires or is rejected after another administrator changes the configuration, first reopen the current settings. Recover the original step through support before repeating a secret replacement or saving an older form. A failed return does not prove the saved settings were undone.

Recover when setup cannot be saved¶

The intended custom-error screen keeps entered values visible and highlights an invalid token address. Correct the highlighted field before saving again. A previously saved secret stays hidden.

For support, provide the workspace, provider, approximate time, operation and visible error. Use approved channels and keep passwords, client secrets, tokens and sign-in return links out of ordinary support messages.