Email connections

Deeplinq treats personal mailbox access as a user-owned connection. Your organization registers its OAuth application, then each end user completes the provider consent flow through the engine.

Supported providers:

• Gmail;
• Outlook through Microsoft Graph.

Both providers expose the same governed tool vocabulary:

Prerequisites

• set PUBLIC_URL to the externally reachable HTTPS engine URL;
• create an OAuth application with Google Cloud or Microsoft Entra;
• keep the client secret available to the organization administrator;
• choose one or more HTTPS return URL prefixes in the partner application.

Deeplinq computes a fixed callback from PUBLIC_URL. Register the redirect_uri returned by the integration API in the provider console.

Ownership boundary

A connection belongs to the user who authorized it. Organization administrators may inspect connection metadata and revoke a connection, but they cannot invoke mailbox tools on behalf of another user.

Register an OAuth application

An organization administrator registers a named integration. Multiple apps per provider are supported for environments or brands; names are unique per organization and provider.

Gmail:

curl -H "Authorization: Bearer $ORG_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/integrations" -d '{
  "provider":"gmail",
  "name":"Production",
  "client_id":"<google-client-id>",
  "client_secret":"<google-client-secret>",
  "scopes":[
    "openid",
    "email",
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/gmail.send"
  ],
  "return_url_prefixes":["https://app.example.com/settings/connections"]
}'

Outlook requires its complete seven-scope catalog:

[
  "openid",
  "profile",
  "email",
  "offline_access",
  "User.Read",
  "Mail.Read",
  "Mail.Send"
]

The client secret is sealed and never returned. PATCH /v1/integrations/{id} can rename, activate/deactivate, change scopes or return prefixes, and rotate the client secret.

Start authorization

Your trusted backend requests an authorization URL for the signed-in user:

curl -H "Authorization: Bearer $DEEPLINQ_API_KEY" \
  -H "X-End-User-Id: user-42" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/connections/authorize" -d '{
  "provider":"outlook",
  "integration_id":"<integration-id>",
  "return_url":"https://app.example.com/settings/connections/complete"
}'

Redirect the browser to the returned URL. The engine owns OAuth state, PKCE, the provider callback, token exchange, refresh, sealing, and return URL validation.

The partner application never receives a Google or Microsoft access token.

When exactly one active integration exists for a provider, integration_id may be omitted. With multiple active integrations it is required; Deeplinq returns 409 instead of guessing.

List and revoke connections

GET    /v1/connections?limit=50&cursor=<opaque>
GET    /v1/connections/{connection_id}
DELETE /v1/connections/{connection_id}

The owner sees connection metadata, not tokens. An organization administrator can inspect and revoke connection metadata across the organization through the admin console, but cannot invoke tools as that user.

Invoke a tool

After authorization, the connection owner can inspect its tool catalog and invoke a supported operation:

GET /v1/connections/{connection_id}/tools
POST /v1/connections/{connection_id}/invoke

{
  "tool": "email.search",
  "args": {
    "query": "from:billing@example.com has:attachment",
    "max_results": 10
  }
}

The portable query grammar supports bare terms, quoted phrases, from:, to:, cc:, subject:, body:, after:, before:, and has:attachment. Provider-native Gmail or Exchange operators are rejected.

Limits and delivery safety

• search uses opaque provider-bound cursors;
• read bodies are bounded and may be truncated;
• send allows at most 25 combined to and cc recipients;
• send allows at most 5 attachments and 3 MiB decoded attachment data;
• attachment downloads are membership-checked and capped at 3 MiB;
• oversized tool results are rejected, never silently truncated;
• ambiguous Gmail send retries fail as tool_uncertain;
• Outlook send does not retry ambiguous delivery, preventing silent duplicates.

Agent grants can expose read tools with auto policy and gate email.send with requires_approval.