Guides

Connect a mailbox

A Mailbox is an email address your Team sends from. Connecting one takes a few seconds: pick the way that fits the address, paste a password or sign in.

Which way to use

Your addressUseAn administrator needed?
Gmail (gmail.com, googlemail.com)An app passwordNever
Google WorkspaceAn app passwordUsually not
Microsoft 365, Outlook.comSign in on Microsoft's pageOften, once
Google Workspace, no password to pasteSign in with GoogleYes, once per Workspace
Any other hostIMAP and SMTP, with the host's password or app passwordNo

Start with the first row that fits. In the dashboard, open Accounts, then Mailboxes, then Connect. An AI agent can do all of it for you except the sign-ins: see Let an agent do it.

Curviate checks the headers of new mail to find replies, and keeps only the threads Curviate started.

Gmail and Google Workspace: an app password

An app password is a 16-character password Google creates for one app. It works for private Gmail and for most Workspaces without any administrator, and it is the only Google way that also warms the Mailbox up.

  1. Turn on 2-Step Verification for the Google account, if it is not on. Google creates app passwords only for accounts that have it.
  2. Open myaccount.google.com/apppasswords, name the password "Curviate" and create it. Copy the 16 characters.
  3. In the Curviate dashboard, choose Connect, then Google, enter the address and paste the app password.

Curviate logs in once to check the password, lists the folders and sends nothing. Gmail saves its own copy of every sent email.

MessageWhat to do
That is your Google password. Create an app password instead.Go back to step 2: the app password is not the password you sign in with.
Google refused the app password.Create a new app password and paste it again. Check the address is the account the password belongs to.
The app passwords page says the setting is not available.Your account uses only a security key to sign in, or has Advanced Protection: Google offers no app passwords there. Ask your administrator, or use another address.
Google would not let Curviate log in over IMAP.A Workspace administrator can switch IMAP access off. Ask the administrator to switch it on, or see Google Workspace administrators.

Microsoft 365 and Outlook.com: sign in on Microsoft's page

There is no password to paste. Choose Connect, then Microsoft, and sign in on Microsoft's own page. Curviate asks for three things and nothing more: to sign you in and read your name and address, to send mail as you, and to read your mail (to find replies, from the headers of new mail). It keeps a token, never your password.

A personal Outlook.com account connects at once. A company account often does not: its Microsoft 365 administrator has to approve Curviate once for the company, which is a normal step, not an error. Curviate then says "Your Microsoft 365 administrator needs to approve Curviate once." and shows a link for the administrator.

  1. Send the administrator link to your Microsoft 365 administrator. It opens Microsoft's own approval page for your company's domain, and it is not a secret: it is safe to forward.
  2. The administrator signs in, reads the list of permissions and approves.
  3. Choose Connect again and sign in. After the approval, it takes one step.

If the administrator later removes Curviate's access, or a password change or a Conditional Access policy signs the Mailbox out, it moves to reconnect_needed and tells you which: sign in again, and send the administrator link if it says the administrator removed access.

Google Workspace administrators

This section is for the administrator of a Google Workspace. People in your Workspace can already connect with an app password without you. If you trust Curviate, they can instead sign in with Google, with nothing to paste. You trust Curviate's app once for the whole Workspace.

What the people in your Workspace then grant Curviate, and nothing more:

  • Sign in and read their email address.
  • Send email as them (gmail.send).
  • Read their email, to find replies (gmail.readonly).

Curviate never asks to modify, delete or manage mail. Private Gmail never signs in this way: it uses an app password.

Curviate's client ID (not a secret):

Curviate's client ID is not published yet: Google sign-in is not available yet. Connect with an app password.

To trust Curviate, sign in to the Google Admin console as an administrator with the Service Settings privilege, and:

  1. Open Security, then Access and data control, then API controls.
  2. Choose Manage App Access, then Configure new app.
  3. Search for the client ID above and select Curviate.
  4. Choose the organizational units that may use it: the top level, for everyone.
  5. Set the access to Trusted, and confirm.

After that, a person in the Workspace chooses Connect, then Google, then "Your administrator trusts Curviate? Sign in with Google". Until you have trusted Curviate, they see "Google did not let Curviate in. Your Google Workspace administrator needs to trust Curviate once." with a link to this section, and can connect with an app password instead.

To take it back, set Curviate to Blocked or remove it from Manage App Access. A Mailbox that signed in this way then moves to reconnect_needed with "Your Google Workspace administrator restricted Curviate's access."

A Mailbox connected by Google sign-in sends and checks for replies through Google's own API. It warms up only once someone adds an app password beside it: on its page, choose Add an app password for warm-up.

Any other host: IMAP and SMTP

For an address on any other host, enter the address and Curviate finds the settings: first a list of known hosts, then the host's own published settings, then the public database of mail settings, then DNS, then a guess. It shows every setting it found, and nothing is sent anywhere until you confirm them. Enter them by hand when it cannot find any.

Use the host's password, or an app password where your host offers one.

  • Receiving is IMAP on port 993 over TLS, or port 143 with STARTTLS. Sending is port 465 over TLS, or port 587 with STARTTLS.
  • Never cleartext, and the host's certificate is always checked. A host that does not offer STARTTLS is refused (MAILBOX_TLS_FAILED), never downgraded.
  • The check logs in, lists the folders and sends nothing. Curviate checks once whether the host saves a copy of sent email in its own Sent folder.

Let an agent do it

An agent creates the request and the Mailbox; you complete only what has to be yours: a sign-in on Google's or Microsoft's page, or an administrator's approval. The same Connect request that connects a LinkedIn Account connects a Mailbox.

  1. Find the settings with GET /v1/mailboxes/discover?address=ann@acme.example, or curviate mailbox discover ann@acme.example. It returns the connection and the IMAP and SMTP settings, and holds no secret.
  2. Start the request with POST /v1/auth/connect-requests and {"mailbox": {"connection": "google_app_password", "address": "ann@acme.example"}}, or curviate mailbox connect <address> --connection <connection>. The response has the request's link, mailbox_id (null until a connect completes) and admin_consent_url: Microsoft's approval page for a company address, this section for a Google sign-in, else null. Forward it to the administrator.
  3. Submit an app password or IMAP password sealed, in the same body: "credentials": {"password": "..."}. For IMAP also pass the imap and smtp settings that discover returned, which is your confirmation of them. Curviate checks the login before it answers and stores nothing when it fails.
  4. Read the outcome with GET /v1/auth/connect-requests/{id} until status leaves pending. A refusal comes with its code, and the request can be tried again up to three times.

In the CLI, give the password on standard input with --password-stdin (on connect, and on reconnect <id>), from a file you delete afterwards or from a pipe:

curviate mailbox connect anna@gmail.com --connection google_app_password --password-stdin < app-password.txt

--password-stdin reads one secret from standard input, never echoes it, and puts it only in the request body: it is never a flag value, an argument, a URL or a log line. The password is never returned, echoed or named in any response, error or event, and Curviate zeroes it after the check.

MCP never takes a password. create_mailbox_connect_request and discover_mailbox_settings return the link and admin_consent_url; no MCP tool accepts a credential, so a password never enters a chat or a model's context. For an app password or IMAP, the person pastes it in the dashboard, or a script sends it over REST or the CLI. A Microsoft or Google sign-in is always the person's.

When it does not connect

CodeMeaningWhat to do
MAILBOX_APP_PASSWORD_REQUIREDA Google password, or a private Gmail address on a sign-in.Create an app password and use that.
MAILBOX_CREDENTIAL_REJECTEDThe host refused the password.Create a new password or app password.
MAILBOX_ADMIN_APPROVAL_REQUIREDYour administrator has not approved or trusted Curviate.Send the admin_consent_url, then connect again. The request stays open.
MAILBOX_ADDRESS_MISMATCHYou signed in as another address. Nothing changed.Sign in as the address you entered.
MAILBOX_TLS_FAILEDThe host does not offer a secure connection.Use the host's secure settings. Curviate does not fall back to cleartext.
MAILBOX_LIMIT_REACHEDYour Team holds all the Mailboxes its seats allow.Add a seat for 100 more, or remove one.

A request expires after 15 minutes, and its third failed attempt ends it: start a new one.

After it connects

Set Sends for: the one LinkedIn Account a person's Mailbox sends for, or Shared for a Mailbox any Account may send from. A Mailbox that sends for nothing sends nothing. A new Mailbox ramps up to its daily cap (30 by default, 50 at most) over about two weeks, which the dashboard shows as "ramping up to 30 a day". Removing a Mailbox deletes its stored credentials in the same step.