Guard.ch in deine eigenen Tools integrieren

Der Umfang ist bewusst klein gehalten. Die Browser-Erweiterungen rufen gar keine API auf: Sie bauen nur einen Launcher-Link. Die Mail-Integrationen für Gmail und Outlook rufen dagegen nur eine einzige API auf: die E-Mail-API. Diese Seite beschreibt genau diesen Umfang: den Launcher-Link-Mechanismus der Erweiterungen und die E-Mail-API, auf der die Mail-Integrationen laufen.

Die Wahl richtet sich danach, wer das Ergebnis braucht. Soll sich eine Person eine verdächtige Seite ansehen, reicht ein Link: Die Untersuchung öffnet sich in ihrem Browser. Soll Software auf eine Einschätzung reagieren, schickst du die E-Mail und liest das JSON.

Die zwei Integrationswege

• Der Launcher-Link, für Menschen. Dein Tool öffnet einen Link zu guard.ch/start, und die Untersuchung startet live im eigenen Browser der Person, sobald sie angemeldet ist. Die Browser-Erweiterungen nutzen eben diesen Mechanismus.
• Die E-Mail-API, für Pipelines. Dein Client schickt die Rohnachricht an die E-Mail-API und erhält die geparste E-Mail, die Live-Prüfung der Authentifizierung und die Einschätzung des KI-Analysten in einer einzigen synchronen Antwort. Denselben Endpunkt nutzen auch die Mail-Integrationen für Gmail und Outlook.

Bevor du startest

Launcher-Link

guard.ch/start, aufgerufen wie jede URL: keine API-Keys, kein SDK

E-Mail-API

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

Formate

.eml oder .msg, bis 25 MB pro Nachricht

Anmeldung

Nur die E-Mail-API braucht eine; die Geräte-Kopplung liefert sie

Plan

Beide Wege sind in jedem bezahlten Guard.ch-Plan enthalten

Du brauchst kein SDK und keine Bibliothek. Jede Sprache und jede Plattform, die eine URL öffnen und eine HTTPS-Anfrage senden kann, reicht.

Einen Launcher-Link bauen

Der Launcher liegt unter guard.ch/start. Öffnest du ihn mit einem Ziel, übergibst du die Kontrolle an den Browser der Person: Die Person meldet sich bei Bedarf an. Auf einem bezahlten Plan startet dann die Untersuchung, und die Person landet direkt auf der Live-Ansicht. Dein Tool speichert weder ein Konto noch einen Token noch sonstige Guard.ch-Daten: Der Link ist die gesamte Integration.

Drei Query-Parameter, nur der erste davon ist Pflicht:

• url Die Zieladresse. Unsere Erweiterungen kodieren sie in einem kurzen Hex-Format: Auf das Präfix ENCODED- folgt die Adresse als Hex-Bytes in Grossbuchstaben, sodass die verdächtige URL nur als undurchsichtiges Token sichtbar ist, nicht als eingebetteter Link. Ein normal URL-kodierter Wert funktioniert genauso gut.
• location Der Standort, von dem aus die Untersuchung startet: als Ländercode (us) oder als konkrete Stadt (us-dal). Ohne Angabe wählt Guard.ch ihn automatisch.
• workspace Der Workspace-Anmeldename. Damit wird eine noch nicht angemeldete Person durch das SSO des eigenen Unternehmens geleitet statt durch das allgemeine Anmeldeformular. Es ist ein Routing-Hinweis, keine Zugangsdaten: Ein falscher Wert führt einfach zur normalen Anmeldung zurück.

Ein Link ohne Sprachpräfix leitet auf den englischen Launcher um; die Query bleibt dabei erhalten. Für ein deutschsprachiges Team baust du stattdessen guard.ch/de/start.

E-Mail zur Prüfung einreichen

Die E-Mail-API besteht aus einem einzigen Endpunkt: POST /v8/guard/email/analyze auf api.guard.ch. Schicke die Rohnachricht als Multipart-Formulardaten: das Feld email mit einer einzelnen .eml- oder .msg-Datei bis 25 MB, dazu optional das Textfeld locale (en oder de) für die Sprache der Einschätzung. Setze deinen Session-Token in den Header Authorization: Bearer und ergänze den Header X-Product: guard.

Guard.ch liest die Nachricht und prüft ihre Authentifizierung (SPF, DKIM, DMARC) live gegen die DNS-Einträge, dazu die Reputation der Absenderdomain. Der KI-Analyst liest den Inhalt und recherchiert alles Zweifelhafte im offenen Web. Alles landet in einer einzigen synchronen Antwort mit zwei Teilen:

• verdict Die Einschätzung selbst: ein Status aus safe, caution, risk oder couldn't verify, dazu eine Schlagzeile und eine Zusammenfassung in einfacher Sprache. Dazu kommen die Befunde, auf denen die Einschätzung beruht, ein Ratschlag, den du wortwörtlich an die Empfängerin oder den Empfänger weitergeben kannst, sowie die Quellen der Recherche.
• email Der geparste Kontext: Absender und Envelope, die Live-Ergebnisse der Authentifizierung, jeder Link mit Mismatch- und Punycode-Flags sowie die Anhänge.

Du brauchst keine makellose Originalnachricht. Auch unsere eigenen Mail-Integrationen kommen nie an das echte MIME heran: Sie bauen aus den Feldern, die sie lesen können (den Envelope-Headern und dem HTML-Body), eine minimale .eml nach und lassen Guard.ch die Authentifizierung live auf dem Server prüfen. Eine solche Rekonstruktion reicht als Input vollständig aus.

Den Client anmelden

Die E-Mail-API verlangt eine Anmeldung; dein Client braucht also eine eigene Guard.ch-Sitzung. Eingebettete Oberflächen können meist keine normale Browser-Anmeldung durchlaufen; dafür gibt es die Geräte-Kopplung. So meldet sich auch unser Outlook-Add-in an:

1. Dein Client ruft POST /v7/auth/pair/start auf und bekommt einen kurzen Kopplungscode sowie ein privates Polling-Secret zurück.
2. Dein Client öffnet oder zeigt den Link guard.ch/pair?code=…; die Person meldet sich dort wie gewohnt an, in einem beliebigen Browser: per Anmeldelink, Passkey, Google oder Passwort.
3. Dein Client fragt POST /v7/auth/pair/poll mit dem Code und dem Secret ab und erhält seinen eigenen, frischen Session-Token, sobald der Code eingelöst wird.

Jeder Code ist nur einmal gültig und läuft nach zehn Minuten ab. Das Polling-Secret verlässt den Client nie, darum kann der kurze Code allein nie zu einem Token führen. Bewahre den Session-Token wie ein Passwort auf und nutze ihn wieder; die Kopplung passiert einmal, nicht bei jedem Aufruf.

Unser Gmail-Add-on meldet sich anders an: Es tauscht seinen Google-Identitätstoken still im Hintergrund aus. Dieser Weg ist Google-Workspace-Add-ons vorbehalten; für eigene Clients ist die Kopplung der vorgesehene Weg.

Auf die Geräteflotte ausrollen

Damit die ganze Belegschaft den interaktiven Weg nutzen kann, ohne dass du selbst etwas baust, rollst du die Browser-Erweiterungen aus. Sie bringen den Launcher-Link mit, dazu ein Rechtsklick-Menü, ein Symbolleisten-Popup und ein Tastenkürzel; deine IT verteilt sie unternehmensweit. Verwaltete Installationen lesen den workspace-Anmeldenamen aus der Browser-Richtlinie (Chrome, Edge oder Firefox), sodass sich jede Mitarbeiterin und jeder Mitarbeiter automatisch über dein SSO anmeldet.

Denselben Anmeldenamen setzt du auch in die Launcher-Links deiner eigenen Tools ein, damit sich Menschen bei deiner eigenen Integration genauso anmelden wie bei den verwalteten Erweiterungen. Die Integrationsseite listet alles auf, was es bereits gibt.

Limits und faire Nutzung

• Externe Tools brauchen einen bezahlten Plan. Beide Wege richten sich nach dem Plan des angemeldeten Kontos: Der Launcher zeigt einem kostenlosen Konto einen Upgrade-Hinweis; die E-Mail-API antwortet mit einer klaren, bereits lokalisierten Upgrade-Meldung. Die kostenlose Testphase auf der Website gilt bewusst nicht für externe Clients.
• Der Launcher-Link gibt selbst keine Berechtigung. Ihn zu bauen kostet nichts, und für sich genommen gewährt er auch nichts: Alles läuft auf dem eigenen Konto der Person, die ihn öffnet. Ein weitergeleiteter Link führt einfach zur eigenen Anmeldung dieser Person.
• Lastspitzen werden gedrosselt. Ein knappes Kontingent pro Minute und Konto hält die E-Mail-Pipeline für alle reaktionsschnell. Drossle das Tempo deiner Batch-Jobs entsprechend, statt ein ganzes Postfach auf einen Schlag abzufeuern.

Sicherheit

• Ein Launcher-Link enthält keine Zugangsdaten und gewährt nichts. Die Anmeldung findet immer bei Guard.ch statt oder über dein eigenes SSO.
• Das Polling-Secret gelangt nie an die Person, die sich anmeldet. Kopplungscodes sind kurzlebige Einmalcodes.
• Hochgeladene E-Mails werden im Arbeitsspeicher analysiert und nie gespeichert. Danach existiert nur noch die Antwort, die du erhältst.
• Jede Anfrage läuft über HTTPS. Sämtliche Guard.ch-Daten liegen innerhalb der EU, unter demselben Auftragsverarbeitungsvertrag wie der Rest des Produkts.

Nächste Schritte

Starte mit dem Launcher: Verpacke eine Adresse in einen Launcher-Link und öffne ihn. Sobald deine Pipeline Einschätzungen als Daten braucht, ergänzt du die E-Mail-API: Kopple einen Client einmal, dann schicke ihm Nachrichten. Für alles, was dieser Umfang nicht abdeckt, kontaktiere uns.