Integrating Guard.ch into your own tools

The surface is deliberately small. The browser extensions do not call an API; they build a single launcher link. The Gmail and Outlook add-ins call a single endpoint, the whole-email analysis. This page documents exactly that surface, the same one those extensions run on.

Choose the path by who consumes the result. When a person should look at a suspicious page, hand off a link; the investigation opens in their browser. When software should act on a verdict, send the email and read the JSON.

The two integration paths

• The launcher link, for people. Your tool opens a guard.ch/start link; the investigation starts live in the person's own signed-in Guard.ch. The browser extensions use exactly this mechanism.
• The email verdict, for pipelines. Your client sends the raw message to one HTTPS endpoint and receives the parsed email, the live authentication checks and the AI verdict in a single synchronous response. The Gmail and Outlook add-ins use exactly this endpoint.

Before you start

Launcher link

guard.ch/start, opened like any URL; no keys, no SDK

Email endpoint

POST https://api.guard.ch/v8/guard/email/analyze

Formats

.eml or .msg, up to 25 MB per message

Sign-in

Only the email endpoint needs one; device pairing provides it

Plan

Both paths are included in every paid Guard.ch plan

No SDK or library is required. Any language or platform that can open a URL and send an HTTPS request is enough.

Building a launcher link

The launcher lives at guard.ch/start. Opening it with a target hands over to the person's own browser: they sign in if needed, and on a paid plan the investigation starts and lands on the live view. Your tool holds no account, no token and no other Guard.ch state; the link is the entire integration.

Three query parameters, and only the first is required:

• url The target. Our extensions wrap it in a small hex scheme: the prefix ENCODED- followed by the address as uppercase hex bytes, so the suspicious URL travels as an opaque token instead of a nested link. A plain URL-encoded value works as well.
• location The exit location for the investigation, as a country (us) or a specific city (us-dal). Omitted, Guard.ch chooses automatically.
• workspace Your workspace's SSO slug. With it, a visitor who is not signed in yet is routed through your company's single sign-on instead of the generic sign-in form. It is a routing hint, never a credential: a wrong value simply falls back to the normal login.

A link without a language prefix redirects to the English launcher with the query preserved; build guard.ch/de/start if your team works in German.

Submitting an email for analysis

The data path is one endpoint: POST /v8/guard/email/analyze on api.guard.ch. Send the raw message as multipart form data: field email with a single .eml or .msg file of up to 25 MB, plus an optional text field locale (en or de) for the verdict language. The request carries your session token as Authorization: Bearer and the header X-Product: guard.

Guard.ch parses the message, verifies its authentication (SPF, DKIM, DMARC) live against DNS, looks up the sender domain's reputation, and lets the AI agent read the content and research anything doubtful on the open web. Everything returns in one synchronous response with two parts:

• verdict The read itself: a posture of safe, caution, risk or couldn't verify, with a headline, a plain-language summary, the facts and signals it rests on, advice you can show the recipient verbatim, and the sources the research used.
• email The parsed context: sender and envelope, the live authentication results, every link with mismatch and punycode flags, and the attachments.

You do not need the pristine original. Our own add-ins cannot reach the true MIME either: they rebuild a minimal .eml from the fields they can read (the envelope headers and the HTML body) and let Guard.ch verify authentication live on the server. A reconstruction like that is a first-class input, not a degraded one.

Signing the client in

The analysis endpoint is login-required, so your client needs a Guard.ch session of its own. Embedded surfaces usually cannot complete a browser login, which is what device pairing is for; it is how our Outlook add-in signs in:

1. Your client calls POST /v7/auth/pair/start and receives a short pairing code plus a private polling secret.
2. Your client opens or shows the link guard.ch/pair?code=…; the person signs in there as usual, in any browser (magic link, passkey, Google or password).
3. Your client polls POST /v7/auth/pair/poll with the code and the secret, and receives its own fresh session token the moment the code is claimed.

Codes are single-use and expire after ten minutes, and the polling secret never leaves your client, so the short code alone can never yield a token. Store the session token like a password and reuse it: pairing happens once, not per call.

Our Gmail add-on signs in differently, by silently exchanging its Google identity token. That route is specific to Google Workspace add-ons; for your own clients, pairing is the intended path.

Deploying to a fleet

To give every employee the interactive path without building anything, deploy the browser extensions: they are the launcher link with a right-click menu, toolbar popup and keyboard shortcut on top, and IT can push them company-wide. Managed installs read the workspace slug from browser enterprise policy (Chrome, Edge or Firefox), so every install routes staff through your single sign-on by itself.

The same slug is what you put into your own tools' launcher links, so a custom integration and the managed extensions sign people in identically. The integrations page lists everything prebuilt.

Limits and fair use

• External tools run on paid plans. Both paths are gated on the signed-in account's plan: the launcher shows a free account an upgrade prompt, and the email endpoint answers it with a clear, already-localised upgrade message. The on-site free trial deliberately does not extend to external clients.
• The launcher link carries no entitlement. It is free to build and grants nothing by itself: whatever runs, runs on the person's own account, and a link forwarded to someone else simply meets their sign-in.
• Bursts are throttled. A short per-minute allowance per account keeps the email pipeline responsive for everyone; pace batch jobs accordingly rather than firing a whole mailbox at it in one go.

Security

• A launcher link contains no credentials and grants nothing; sign-in always happens on guard.ch, or through your own SSO.
• The pairing secret never travels through the person signing in, and pairing codes are single-use and short-lived.
• Uploaded emails are analyzed in memory and never written to storage; only the response you receive exists afterwards.
• Every request runs over HTTPS, and all Guard.ch data is stored within the EU under the same DPA as the rest of the product.

Next steps

Start with the launcher: wrap an address into a start link and open it. Add the email endpoint when your pipeline needs verdicts as data: pair a client once, then send it messages. For anything this surface does not cover, contact us.