Connecting a mailbox

Connect a Gmail or Outlook mailbox and its incoming email becomes available to GET /emails/get-email. Connecting uses OAuth, so the mailbox owner grants access in their own browser and you never see their password.

The provider in every path below is gmail or outlook.

Your backend calls oauth/start and oauth/result with your API key. The user’s browser only ever follows redirects. Your key never reaches it.

1. Start the flow from your backend.

   curl

   curl -G https://api.clearance.rest/emails/gmail/oauth/start \
     -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
     --data-urlencode "return_url=https://app.example.com/settings/mailboxes" \
     --data-urlencode "client_state=user-42"

   Node.js

   const { authorize_url } = await clearanceRest.emails.oauthStart({
     provider: 'gmail',
     returnUrl: 'https://app.example.com/settings/mailboxes',
     clientState: 'user-42',
   });

   PHP

   $authorizeUrl = $client->emails->oauthStart(
       'gmail',
       'https://app.example.com/settings/mailboxes',
       'user-42',
   )['authorize_url'];

   return_url is required and must be an absolute http(s) URL. If your project restricts allowed return origins, it must be on one of them, or the call returns 400. client_state is an opaque value of your choosing that comes back unchanged at the end, so you can tell which user the result belongs to.

2. Send the user’s browser to authorize_url.

   They sign in to Google or Microsoft and grant access. The provider then redirects to clearance.rest, which redirects the browser to your return_url with two query parameters:

   https://app.example.com/settings/mailboxes?result_token=…&client_state=user-42

   The redirect happens on success and on failure, and never carries the outcome itself. That is what the next step is for.

3. Read the outcome from your backend.

   curl -G https://api.clearance.rest/emails/gmail/oauth/result \
     -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
     --data-urlencode "token=$RESULT_TOKEN"

   { "success": true, "email": "user@gmail.com", "client_state": "user-42" }

   A failed connection is still HTTP 200, with success: false and the reason in error. The token is single use: it is consumed by the first read, a second read returns 404, and it expires after about 10 minutes.

Using the mailbox

Once connected, mail sent to that address is available to get-email:

curl -G https://api.clearance.rest/emails/get-email \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  --data-urlencode "email_account=user@gmail.com" \
  --data-urlencode "code_regex=\d{6}"

An address can be connected to only one project. Connecting one that already belongs to another project fails, and oauth/result reports the reason.

List and disconnect

curl https://api.clearance.rest/emails/gmail/accounts \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY"

curl -X POST https://api.clearance.rest/emails/gmail/accounts/disconnect \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "email": "user@gmail.com" }'

The list shows only your project’s mailboxes and never returns tokens. Each has a last_error that holds the most recent sync problem, if any. disconnect stops the provider-side watch (ignoring the failure if access was already revoked) and removes the connection. It returns 404 if that mailbox is not connected to your project.

The connection’s watch or subscription is renewed automatically; you do not need to refresh it.