Integrations

ScamShield AI connects to your existing tools to screen messages automatically. This section covers Gmail, Zoho Mail, the Chrome extension, custom webhooks, and the upcoming WhatsApp Business integration.

Gmail

What access we request

ScamShield AI requests a single, read-only Google scope:

https://www.googleapis.com/auth/gmail.readonly

There is no send, modify, or delete permission. While gmail.readonly *could* technically read message bodies, the application deliberately self-restricts: every Gmail API call uses format='metadata', which returns headers only (From, Subject, Date, Reply-To, and the SPF/authentication results). The message body is never requested or downloaded.

DPDP note: No email body is ever transferred or stored. What ScamShield AI analyses is the subject, sender, and Google's own pre-computed ~100-character snippet — processed in memory. The GmailIntegration record persists only your connected Gmail address, encrypted OAuth tokens, and sync cursors. High-risk detections are stored as metadata only (sender, subject, category, numeric score).

Connect flow

1. Authorize — from the portal, start the Gmail connection. ScamShield AI builds a Google consent URL with a signed, self-verifying state token (valid 10 minutes) and requests offline access.
2. Callback — after you approve, Google redirects back; ScamShield AI exchanges the code for tokens, records your Gmail address, and (best-effort) registers a Gmail push watch so new mail is scanned promptly. You land back on the dashboard with ?gmail_connected=true.
3. Status — the integration reports whether it's connected, whether it needs re-authorisation, and when the next scan is due (Gmail polls roughly every 180 seconds).
4. Scan — an on-demand scan reviews your 20 most recent messages: vernacular/keyword classification, the ML email model on subject + snippet, header analysis, URL-threat analysis on the snippet, and ensemble fusion. Threats scoring ≥ 60 are recorded and Gmail labels are applied.
5. Disconnect — revokes the token at Google, deletes the stored integration, and notifies you that the inbox is no longer protected.

Zoho Mail

ScamShield AI requests two read-only Zoho scopes:

ZohoMail.accounts.READ,ZohoMail.messages.READ

No write, send, or delete scope is requested. Like Gmail, the Zoho pipeline works from metadata and a summary — no message body is downloaded. Zoho is region-partitioned; the default configuration targets the India data centre.

Connect flow: authorize (returns a consent URL; responds with a "not configured" error if the Zoho client credentials aren't set) → callback (exchanges the code, stores your Zoho address, account ID, and encrypted tokens) → status → disconnect (deletes the stored integration; scanning stops immediately).

Chrome Extension

The ScamShield AI Chrome extension is a Gmail-only inbox scanner built on Manifest V3.

• Scope: the content script runs only on mail.google.com. It does not run on other sites and does not read your general browsing.
• Automatic scanning: when you open an email in Gmail, the extension injects a colour-coded risk badge above the message — a loading state first, then the verdict (green = legitimate, amber = caution, red = high risk with the scam category).
• What it sends: the sender, subject, and the first ~2,000 characters of the visible email body, to the ScamShield AI scan endpoint.
• Paste-token authentication: open the extension popup, click Connect Account (opens the extension-auth page in the portal), copy the issued token, and paste it into the popup. The token is stored locally in your browser and sent as the X-ScamShield-Token header. The popup shows your connection status, plan, and monthly scan usage — it does not display scan results (those appear as Gmail badges).
• Disconnect: the popup's Disconnect button revokes the token server-side and clears it locally.

Note: Because the extension sends a truncated body to the scan endpoint, that scan is handled by the Universal Scanner pipeline, which stores the submitted text. See DPDP Compliance for exactly what is and isn't retained.

Custom Webhook

Professional-plan companies can register outbound webhooks to receive fraud events in real time. You may register multiple endpoints per company.

Events

Three event types are emitted:

• scan.completed — a Universal Scanner scan finished.
• email.threat — an email threat alert was created.
• darkweb.alert — a dark-web alert was raised.

When you subscribe an endpoint to an empty event list, it receives all events.

Payload envelope

Every delivery is JSON with the same envelope: an event name, an ISO-8601 timestamp, and an event-specific data object.

{
  "event": "scan.completed",
  "timestamp": "2026-07-02T10:15:30.123456+00:00",
  "data": {
    "scan_id": "3f9c…uuid",
    "input_type": "text",
    "risk_score": 0.87,
    "verdict": "fraud",
    "fraud_category": "CAT-02",
    "explanation": "UPI payment fraud indicators detected",
    "scanned_at": "2026-07-02T10:15:29.900000+00:00"
  }
}

The data fields per event:

Note the two risk-score scales: scan.completed sends risk_score on a 0.0–1.0 scale, while email.threat sends it on a 0–100 scale. Handle each event's scale explicitly.

Verifying deliveries (signature)

Each request carries these headers:

• Content-Type: application/json
• User-Agent: ScamShield-AI/1.0
• X-ScamShield-Signature: sha256=<hex> — HMAC-SHA256 of the raw request body, keyed on your webhook secret. Recompute the HMAC on your side to verify authenticity.
• X-ScamShield-Event: <event_type>
• X-ScamShield-Delivery: <delivery_id>

Retry behaviour

Any non-2xx status, a timeout, or a connection error counts as a failure and triggers the next retry. Every attempt is recorded in a delivery log capturing the payload, status, attempt count, HTTP response code, a truncated response body, any error message, and the next scheduled retry time.

WhatsApp Business

Coming soon — pending MCA verification. The WhatsApp Business integration is not yet live. The portal shows it as "Coming Soon," available after business verification is complete.

The backend "scan-a-message" bot and webhook pipeline are code-complete and signature-secured, but they remain dormant until the required credentials are configured. Go-live is gated on MCA incorporation → Meta Business Verification → setting the WhatsApp environment variables. When dormant, the webhook safely rejects/​no-ops. When live, message bodies are processed in memory and never stored — only a hashed sender, a message-ID (for de-duplication), the message type, and the detected fraud category are retained.