Gmail Connector¶

Connect and sync Gmail accounts to access email data, enable push notifications, and manage email synchronization.

Base URL¶

BASE_URL = "https://api.fermi.dev/public/v1"

All endpoints are relative to this base URL.

Authentication¶

All endpoints require authentication. Use a service actor token:

Authorization: Bearer <service-actor-token>

Required Scopes:

connectors:read - For read endpoints
connectors:write - For write endpoints
connectors:sync - For synchronization endpoints

Connect Gmail Account¶

POST /connect/integrations/connect-session

Create a connection session to initiate Gmail OAuth flow.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "integration": "google-mail"
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/connect/integrations/connect-session" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "integration": "google-mail"
  }'

Response:

{
  "sessionToken": "session-token-abc123"
}

Use the sessionToken to complete OAuth. The response includes sessionToken only (no connectUrl).

List Gmail Connections¶

GET /connect/integrations/connections?providerConfigKey=google-mail

List all Gmail connections for the authenticated user.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Required	Description
`providerConfigKey`	string	Yes	Must be `google-mail`

cURL Example:

curl --request GET \
  --url "${BASE_URL}/connect/integrations/connections?providerConfigKey=google-mail" \
  --header "Authorization: Bearer <token>"

Response:

{
  "connections": [
    {
      "id": 517,
      "connection_id": "5c096330-fc54-4144-bfec-6bd344da9586",
      "provider_config_key": "google-mail",
      "created_at": "2025-01-15T10:30:00Z",
      "metadata": {
        "emailSyncConfig": {
          "enabled": true,
          "syncStatus": "completed",
          "totalEmailsSynced": 1500
        }
      }
    }
  ],
  "total": 1
}

Get Connection Details¶

GET /connect/integrations/connections/{connectionId}?providerConfigKey=google-mail

Get detailed information about a specific Gmail connection.

Headers:

Authorization: Bearer <token>

cURL Example:

curl --request GET \
  --url "${BASE_URL}/connect/integrations/connections/5c096330-fc54-4144-bfec-6bd344da9586?providerConfigKey=google-mail" \
  --header "Authorization: Bearer <token>"

Response:

{
  "id": 517,
  "connection_id": "5c096330-fc54-4144-bfec-6bd344da9586",
  "provider_config_key": "google-mail",
  "created_at": "2025-01-15T10:30:00Z",
  "metadata": {
    "emailSyncConfig": {
      "id": "sync-123",
      "accountConnectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
      "accountEmail": "[email protected]",
      "enabled": true,
      "syncStatus": "completed",
      "totalEmailsSynced": 1500,
      "lastSyncedAt": "2025-01-15T12:00:00Z",
      "maxEmails": 2000,
      "description": "Work email account"
    },
    "watchState": {
      "isWatchEnabled": true,
      "watchExpiration": "2025-01-22T10:30:00Z",
      "watchRenewedAt": "2025-01-15T10:30:00Z",
      "historyId": "12345"
    }
  }
}

Get User Info¶

GET /connect/integrations/user-info?connectionId={connectionId}&providerConfigKey=google-mail

Get user information for a Gmail connection.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Required	Description
`connectionId`	string	Yes	Connection ID
`providerConfigKey`	string	Yes	Must be `google-mail`

cURL Example:

curl --request GET \
  --url "${BASE_URL}/connect/integrations/user-info?connectionId=5c096330-fc54-4144-bfec-6bd344da9586&providerConfigKey=google-mail" \
  --header "Authorization: Bearer <token>"

Response:

{
  "email": "[email protected]",
  "name": "John Doe",
  "picture": "https://lh3.googleusercontent.com/..."
}

Get Gmail Profile¶

GET /connect/integrations/gmail-profile?connectionId={connectionId}

Get Gmail account profile information including email and thread counts.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Required	Description
`connectionId`	string	Yes	Connection ID

cURL Example:

curl --request GET \
  --url "${BASE_URL}/connect/integrations/gmail-profile?connectionId=5c096330-fc54-4144-bfec-6bd344da9586" \
  --header "Authorization: Bearer <token>"

Response:

{
  "success": true,
  "profile": {
    "emailAddress": "[email protected]",
    "messagesTotal": 15234,
    "threadsTotal": 8234,
    "historyId": "12345"
  }
}

Configure Email Sync¶

POST /connect/integrations/connection-metadata

Configure email synchronization settings for a Gmail connection.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerConfigKey": "google-mail",
  "metadata": {
    "emailSyncConfig": {
      "id": "sync-123",
      "accountConnectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
      "accountEmail": "[email protected]",
      "enabled": true,
      "maxEmails": 2000,
      "description": "Work email account for business communications",
      "syncStatus": "never",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  }
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/connect/integrations/connection-metadata" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
    "providerConfigKey": "google-mail",
    "metadata": {
      "emailSyncConfig": {
        "enabled": true,
        "maxEmails": 2000,
        "description": "Work email account"
      }
    }
  }'

Response:

{
  "success": true,
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerConfigKey": "google-mail",
  "metadata": {
    "emailSyncConfig": {
      "enabled": true,
      "maxEmails": 2000
    }
  }
}

Enable Push Notifications (Auto-Sync)¶

POST /gmail/watch/enable

Enable Gmail push notifications for real-time email synchronization.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586"
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/gmail/watch/enable" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586"
  }'

Response:

{
  "success": true,
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "emailAddress": "[email protected]",
  "historyId": "12345",
  "expiration": "2025-01-22T10:30:00Z",
  "message": "Watch enabled"
}

Disable Push Notifications¶

POST /gmail/watch/disable

Disable Gmail push notifications for a connection.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586"
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/gmail/watch/disable" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586"
  }'

Response:

{
  "success": true,
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "emailAddress": "[email protected]",
  "message": "Gmail push notifications disabled successfully"
}

Start Email Sync¶

POST /sync/enqueue

Start initial email synchronization for a Gmail connection.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerKey": "google-mail"
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/sync/enqueue" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
    "providerKey": "google-mail"
  }'

Response:

{
  "success": true,
  "enqueuedCount": 1,
  "jobs": [
    {
      "jobId": "8f2c1a4e-9d3b-4c12-a7e6-1b0f3d9e2a11",
      "type": "email"
    }
  ]
}

If email sync is not configured, the API returns { "success": true, "message": "No email config", "enqueuedCount": 0 }. If a sync is already queued or in progress: { "success": true, "message": "Sync already in progress", "enqueuedCount": 0 }.

Disconnect Gmail Account¶

DELETE /connect/integrations/connection/{connectionId}?integration=google-mail

Disconnect a Gmail account and remove the connection. This DELETE currently returns 502 on the public path.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Required	Description
`integration`	string	Yes	Must be `google-mail`

cURL Example:

curl --request DELETE \
  --url "${BASE_URL}/connect/integrations/connection/5c096330-fc54-4144-bfec-6bd344da9586?integration=google-mail" \
  --header "Authorization: Bearer <token>"

Response:

{
  "success": true,
  "alertingLifecycle": {
    "alerting_stopped": true
  }
}

Endpoints Summary¶

Method	Endpoint	Description
POST	`/connect/integrations/connect-session`	Create connection session
GET	`/connect/integrations/connections`	List Gmail connections
GET	`/connect/integrations/connections/{connectionId}`	Get connection details
GET	`/connect/integrations/user-info`	Get user information
GET	`/connect/integrations/gmail-profile`	Get Gmail profile
POST	`/connect/integrations/connection-metadata`	Configure sync settings
POST	`/gmail/watch/enable`	Enable push notifications
POST	`/gmail/watch/disable`	Disable push notifications
POST	`/sync/enqueue`	Start email sync
DELETE	`/connect/integrations/connection/{connectionId}`	Disconnect account

Gmail push callbacks arrive at POST /webhooks/gmail-push. Google calls that URL; partners do not POST it with an API key (live 401).

Sync Configuration¶

The email sync configuration supports the following options:

Field	Type	Description
`enabled`	boolean	Enable/disable email sync
`maxEmails`	number	Maximum number of emails to sync (default: 2000)
`description`	string	Description for LLM context (optional)
`syncStatus`	string	Sync status: `never`, `in_progress`, `completed`, `failed`
`totalEmailsSynced`	number	Total emails synced
`lastSyncedAt`	string	ISO timestamp of last sync

Features¶

OAuth Authentication - Secure Gmail account connection via OAuth 2.0
Email Synchronization - Sync emails from Inbox and Sent folders
Push Notifications - Real-time email updates via Gmail Watch API
Sync Configuration - Customize sync settings (max emails, description)
Multiple Accounts - Connect and manage multiple Gmail accounts
Profile Information - Access Gmail profile data (email count, thread count)

Next Steps¶

Data Connectors Overview - Return to data connectors overview
API Reference Overview - Return to API reference index
Scopes and Permissions - Learn about connector scopes
Code Examples - Examples (coming soon)