Zum Hauptinhalt springen
connic
Starte kostenlos
Verbindungen

Gmail

Agenten mit eingehenden E-Mails in einem Postfach von Google Workspace starten und ihre Antworten oder Benachrichtigungen von dort versenden, über dein eigenes Google-Dienstkonto.

Zuletzt aktualisiert
ModiInbound, Outbound
YAML-Typgmail
ZugangsdatenEin Kontozugang (Connection) vom Typ gmail, im Dashboard Google Workspace genannt, mit dem JSON-Schlüssel deines eigenen Google-Dienstkontos.
PostfächerNutzer in Google Workspace mit Gmail. Private Konten (@gmail.com) werden nicht unterstützt; für diese nutzt du die E-Mail-Verbindung mit einem App-Passwort.
BridgeNicht unterstützt
Custom DomainNicht unterstützt
Verknüpfte AgentenEiner oder mehrere. Jede E-Mail startet alle verknüpften Agenten.
Während der PauseInbound prüft das Label nicht mehr. E-Mails, die in der Zeit ankommen, werden nach Resume verarbeitet. Outbound sendet nichts.

Einrichtung

  1. Lege in einem Google-Cloud-Projekt mit aktivierter Gmail API ein Dienstkonto mit JSON-Schlüssel an. Ein Super Admin autorisiert dann seine Client-ID für die domainweite Delegierung mit dem Bereich https://www.googleapis.com/auth/gmail.modify.

  2. Öffne den Agenten. Klicke im Connector Flow für Inbound auf Add inbound connector oder für Outbound auf Add outbound connector. Klicke dann auf Create New Connector und wähle Gmail.

  3. Wähle den Modus. Wähle unter Connection einen gespeicherten Google-Workspace-Kontozugang oder lege einen mit dem Inhalt der Schlüsseldatei an.

  4. Gib die Mailbox ein. Lege für Inbound das Label und Mark as Read fest. Gib für Outbound optional Default Recipients ein.

  5. Klicke auf Create. Eine Inbound-Verbindung beginnt dann, das Label zu prüfen. Bei Outbound legst du fest, wie der Agent die Verbindung nutzt, und klickst auf Link connector.

Im Code

Deklariere die Verbindung in connectors/*.yaml. connection nennt den Kontozugang mit dem Schlüssel des Dienstkontos.

connectors/support-inbox.yaml
type: gmail
mode: inbound
connection: acme-google   # Google-Workspace-Kontozugang mit dem Dienstkonto-Schlüssel
config:
  mailbox: support@example.com
  label: INBOX
agents:
  - support-triage
connectors/support-replies.yaml
type: gmail
mode: outbound
connection: acme-google
config:
  mailbox: support@example.com
agents:
  - name: support-triage
    outbound: { usage: automatic }

Konfiguration

Die Felder einer Gmail-Verbindung, in connectors/*.yaml genauso wie in der REST API und connic MCP. Die Beschreibungen nennen die passende Einstellung im Dashboard. Verbindungen im Code beschreibt die Felder, die alle Verbindungen gemeinsam haben, etwa agents und environments.

FeldTypStatusBeschreibung
typestringRequiredgmail.
modestringRequiredinbound oder outbound. Dashboard: Mode.
connectionstringRequiredName oder ID eines Kontozugangs vom Typ gmail. Siehe Dienstkonto. Dashboard: Connection.
configobjectRequiredEinstellungen der Gmail-Verbindung.
mailboxstringRequiredDie Adresse des Google-Workspace-Nutzers, dessen Postfach die E-Mails empfängt oder versendet, etwa support@example.com. Der Nutzer braucht Gmail; eine Gruppe ist kein Postfach. Dashboard: Mailbox.
labelstringOptionalInbound. Das zu prüfende Label: ein Systemlabel mit seiner ID wie INBOX, STARRED oder IMPORTANT oder ein eigenes Label mit seinem Namen, ohne Rücksicht auf Groß- und Kleinschreibung. Ein verschachteltes Label steht mit vollem Namen da, etwa Support/Billing. Dashboard: Label.Default: INBOX
mark_as_readbooleanOptionalInbound. Eine E-Mail als gelesen markieren, sobald alle verknüpften Agenten sie erhalten haben. Dashboard: Mark as Read.Default: true
default_tostringOptionalOutbound. Empfänger einer E-Mail, die weder to setzt noch auf eine eingehende Gmail-E-Mail antwortet: eine Adresse oder mehrere durch Kommas getrennte Adressen. Dashboard: Default Recipients.

Agent-Input

Modi: Inbound

Eine Inbound-Verbindung verfolgt das Label über den Gmail-Verlauf und startet mit jeder neuen E-Mail einen Run für jeden verknüpften Agenten. Sie beginnt mit den E-Mails, die nach ihrer ersten Prüfung ankommen. Was schon da ist, verarbeitet sie nicht, ebenso wenig eine ältere E-Mail, die das Label erst später bekommt. E-Mails, die mit dem Label ankommen, etwa über einen Gmail-Filter, zählen dagegen. connic merkt sich, wie weit es gekommen ist, und verarbeitet keine E-Mail zweimal, auch wenn Mark as Read aus ist. Ein anderes Postfach oder ein anderes Label beginnt ab diesem Zeitpunkt neu. Der Run erhält die E-Mail im selben Format wie bei der E-Mail-Verbindung, sodass ein Agent Input aus beiden verarbeiten kann:

payload.json
{
  "subject": "Hilfe zu Bestellung #12345",
  "from": "Jana Schmidt <jana@example.com>",
  "from_address": "jana@example.com",
  "to": "Acme Support <support@example.com>",
  "date": "Mon, 12 Oct 2026 08:30:00 +0000",
  "message_id": "<CAJ8sK2mPq7x@mail.gmail.com>",
  "body_text": "Hallo, meine Bestellung ist noch nicht angekommen...",
  "body_html": "<div>Hallo, meine Bestellung ist noch nicht angekommen...</div>",
  "has_attachments": true,
  "attachments": [
    {
      "filename": "beleg.pdf",
      "content_type": "application/pdf",
      "size_bytes": 45678,
      "content": "JVBERi0xLjQK...",
      "encoding": "base64"
    }
  ],
  "_gmail": {
    "connector_id": "550e8400-e29b-41d4-a716-446655440000",
    "mailbox": "support@example.com",
    "label": "INBOX",
    "message_id": "18f3a2b4c5d6e7f8",
    "thread_id": "18f3a2b4c5d6e7f8",
    "timestamp": "2026-10-12T08:30:05.123456"
  }
}
  • from und to sind die Header der E-Mail mit Name und Adresse; from_address ist die reine Absenderadresse.
  • date ist der Header Date der E-Mail oder, wenn er fehlt, der Zeitpunkt, zu dem Gmail sie empfangen hat. message_id ist der Header Message-ID der E-Mail.
  • body_text und body_html sind der Klartext- und der HTML-Teil so, wie der Absender sie geschickt hat. Gmail wandelt nicht zwischen beiden um, deshalb kann einer davon leer sein.
  • _gmail nennt die Verbindung, das Postfach, das Label, die Gmail-ID der E-Mail und die ID ihres Gmail-Threads.

Anhänge

Für Anhänge gelten die Regeln der E-Mail-Verbindung: dieselben übernommenen Typen, dieselben übersprungenen Tracking-Bilder und eingebetteten Bilder unter 50 KB und dieselbe Kodierung. Text-, JSON- und XML-Dateien enthalten ihren Inhalt als Text ("encoding": "text"), alle anderen Dateien Base64-kodiert ("encoding": "base64").

Eine E-Mail nimmt bis zu 50 Anhänge auf, höchstens 32 MiB zusammen. Beim ersten Anhang über einem Limit behält connic die Anhänge davor und lässt diesen und alle folgenden aus. Dateien anderer Typen werden ebenfalls ausgelassen. Ein ausgelassener Anhang hat "content": null und ein file_issue, und die Payload führt alle Auslassungen unter file_issues auf:

ausgelassener Anhang
{
  "filename": "archiv.rar",
  "content_type": "application/vnd.rar",
  "size_bytes": 20480,
  "content": null,
  "content_omitted": true,
  "file_issue": {
    "code": "unsupported_file_type",
    "message": "File type is not supported.",
    "retryable": false,
    "name": "archiv.rar",
    "size_bytes": 20480
  }
}

Der Agent erhält die E-Mail auch dann, wenn kein Anhang übernommen wurde. Aktivierst du im Detailbereich der Verbindung Files required für einen Agenten oder setzt files_required: true an seiner Verknüpfung in YAML, schlägt der Run schon vor dem Start fehl, wenn ein Anhang fehlt oder ausgelassen wurde.

Dienstkonto

connic meldet sich bei Google als Dienstkonto in deinem eigenen Google-Cloud-Projekt an, ohne Zustimmungsbildschirm und ohne Anmeldung eines Nutzers. Sein Schlüssel liegt im Kontozugang, nicht in der Verbindung, und connic speichert ihn verschlüsselt. Verwalte Kontozugänge unter Project Settings → Connections; eine Änderung gilt für alle Verbindungen, die den Kontozugang nutzen. Ein Google-Workspace-Kontozugang kann Gmail- und Google-Sheets-Verbindungen bedienen, Inbound wie Outbound, für mehrere Postfächer und Tabellen.

  1. Wähle in der Google Cloud Console ein Projekt deiner Organisation oder lege eines an und aktiviere die Gmail API. Für Google-Sheets-Verbindungen aktivierst du zusätzlich die Google Sheets API.

  2. Klicke unter IAM und Verwaltung → Dienstkonten auf Dienstkonto erstellen. Rollen braucht das Dienstkonto nicht.

  3. Öffne das Dienstkonto und gehe zu Schlüssel → Schlüssel hinzufügen → Neuen Schlüssel erstellen. Wähle JSON und klicke auf Erstellen. Google lädt die Schlüsseldatei einmal herunter und kann sie danach nicht erneut anzeigen.

  4. Füge den Inhalt der Datei in Service account key (JSON) eines Google-Workspace-Kontozugangs ein. Beim Speichern prüft connic, ob es ein Dienstkonto-Schlüssel mit lesbarem privatem Schlüssel ist.

Wert der SchlüsseldateiBeschreibung
client_idDie numerische Client-ID des Dienstkontos, in der Google Cloud Console auch als Eindeutige ID auf seiner Seite zu sehen. Ein Super Admin trägt sie für die domainweite Delegierung ein.
client_emailDie E-Mail-Adresse des Dienstkontos, die auf .iam.gserviceaccount.com endet. Für Google-Sheets-Verbindungen gibst du Tabellen für diese Adresse frei. Das Dashboard schlägt Google Workspace · <client_email> als Namen des Kontozugangs vor.

In Google-Cloud-Organisationen, die am 3. Mai 2024 oder später angelegt wurden, verhindert die Organisationsrichtlinie iam.disableServiceAccountKeyCreation (iam.managed.disableServiceAccountKeyCreation) standardmäßig, dass Dienstkonto-Schlüssel erstellt werden. Ein Administrator für Organisationsrichtlinien muss das für das Projekt erlauben; eine Ausnahme über Tags beschreibt Google unter Dienstkontoschlüssel erstellen und löschen.

Schlüssel laufen nicht ab, solange keine Organisationsrichtlinie eine Gültigkeitsdauer festlegt. Um den Schlüssel zu wechseln, erstellst du einen neuen, trägst ihn im Kontozugang ein und löschst danach den alten in der Google Cloud Console.

Domainweite Delegierung

Eine Gmail-Verbindung handelt über die domainweite Delegierung im Namen ihres Postfachs. Dafür öffnet ein Super Admin die Google Admin-Konsole, geht zu Sicherheit → Zugriffs- und Datenkontrolle → API-Steuerung → Domainweite Delegierung verwalten und klickt auf Neu hinzufügen. Dort trägt er die Client-ID des Dienstkontos und unter OAuth-Bereiche diesen Bereich ein und klickt auf Autorisieren:

OAuth-Bereich
https://www.googleapis.com/auth/gmail.modify

Mit diesem Bereich kann das Dienstkonto im Namen jedes Nutzers der Domain E-Mails lesen, ändern und senden. Google kann die domainweite Delegierung nicht auf bestimmte Nutzer oder Organisationseinheiten beschränken. connic handelt nur im Namen des Postfachs, das in der jeweiligen Gmail-Verbindung steht. Google-Sheets-Verbindungen brauchen keine Delegierung.

Outbound-Zustellung

Modi: Outbound

Eine Outbound-Gmail-Verbindung sendet bei jeder Nutzung eine E-Mail aus der Mailbox: wenn der Run eines verknüpften Agenten abgeschlossen ist, wenn das Modell sie als Tool aufruft oder wenn Middleware sie aufruft, je nach Nutzung der Verknüpfung. Die E-Mail landet im Ordner Gesendet des Postfachs. Diese Felder steuern sie:

FeldBeschreibung
toEmpfänger: eine Adresse, mehrere durch Kommas getrennte Adressen oder eine Liste. Jeder Eintrag kann adresse oder Name <adresse> sein. Sendet eine neue E-Mail, auch wenn eine eingehende Gmail-E-Mail den Run gestartet hat.
ccEmpfänger einer Kopie, in denselben Formaten wie to. Gilt auch für Antworten.
bccEmpfänger einer Blindkopie, in denselben Formaten wie to. Gilt auch für Antworten.
subjectDer Betreff einer neuen E-Mail. Antworten übernehmen den Betreff der eingehenden E-Mail.
bodyDer Text als Klartext.
html_bodyEin HTML-Text. Zusammen mit body enthält die E-Mail beide Teile, und der Klartext dient als Alternative für Mail-Programme, die kein HTML anzeigen. Ohne body enthält sie nur HTML.
reply_toDie Adresse, an die Antworten auf diese E-Mail gehen.

Hat eine Inbound-Gmail-Verbindung den Run gestartet und setzt die Ausgabe kein to, wird die E-Mail eine Antwort auf die eingehende E-Mail, im selben Gmail-Thread. Dafür muss die Outbound-Verbindung dasselbe Postfach und denselben Kontozugang nutzen wie die Inbound-Verbindung. Die Antwort geht an die Antwortadresse der eingehenden E-Mail oder, wenn sie keine hat, an ihren Absender. Als Betreff dient der eingehende Betreff mit vorangestelltem Re:, sofern er nicht schon damit beginnt. Die Header In-Reply-To und References halten den Verlauf auch in anderen Mail-Programmen zusammen. Sonst kommen die Empfänger aus to, danach aus den Default Recipients der Verbindung; fehlt beides, schlägt der Versand mit missing_recipient fehl. Eine neue E-Mail nimmt ihren Betreff aus subject, ohne ihn lautet er Agent Response. Ausgehende E-Mails haben keine Anhänge.

Automatische Ausgabe

Eine automatische Verknüpfung macht aus der finalen Ausgabe des Runs eine E-Mail. Klartext und jede andere Ausgabe, die kein JSON-Objekt ist, werden zum Text der E-Mail. Ein JSON-Objekt setzt die Felder oben und nimmt außerdem message statt body und html statt html_body an. Mit einem Output Schema gibt der Agent diese Felder zuverlässig zurück. Diese Ausgabe antwortet auf die eingehende E-Mail, mit einer Kopie an das Bestellteam:

output.json
{
  "body": "Deine Bestellung wurde heute Morgen verschickt.",
  "html_body": "<p>Deine Bestellung wurde heute Morgen verschickt.</p>",
  "cc": ["orders@example.com"]
}

Payload für Agent-Tool und Middleware

Das Modell oder die Middleware übergibt die Felder oben als Payload. body ist Pflicht, alle anderen Felder sind optional; message, html und alle anderen Felder werden abgelehnt. Postfach, Anmeldung und Wiederholungen ergänzt connic, das Modell sieht davon nichts.

connector-payload.json
{
  "body": "Deine Anfrage ist erledigt.",
  "to": ["jana@example.com"],
  "subject": "Deine Support-Anfrage",
  "html_body": "<p>Deine Anfrage ist erledigt.</p>",
  "cc": ["manager@example.com"],
  "bcc": ["archiv@example.com"],
  "reply_to": "support@example.com"
}

Zustellung und Wiederholungen

connic meldet sich als Dienstkonto im Namen des Postfachs an und übergibt die E-Mail an die Gmail API, die sie an alle Adressen in to, cc und bcc sendet. Ist Gmail nicht erreichbar oder drosselt es die Anfrage, versucht connic es erneut, insgesamt dreimal, und wartet so lange, wie Google es verlangt. Jeder andere Fehler beendet die Zustellung ohne weiteren Versuch. Bricht die Netzwerkverbindung ab, nachdem die E-Mail übergeben wurde, oder antwortet Gmail mit einem Serverfehler, weiß connic nicht, ob die E-Mail verschickt wurde, und versucht es nicht erneut, damit sie nie doppelt ankommt. Prüfe dann den Ordner Gesendet des Postfachs. Die Runs der Verbindung zeigen jede Zustellung mit ihrem Fehler.

Limits und Fehler

LimitWert
Label-PrüfungEtwa alle 30 Sekunden
E-Mails pro PrüfungJeweils 10 auf einmal aus dem Gmail-Verlauf, bis das Label aufgeholt ist oder 60 Sekunden vergangen sind. Der Rest folgt bei der nächsten Prüfung.
Anhänge pro E-Mail50, höchstens 32 MiB zusammen
Zustellversuche3, nur wenn Gmail nicht erreichbar ist oder die Anfrage drosselt
Versandlimits von Google2.000 Nachrichten pro Nutzer und Tag, festgelegt von Google Workspace
Limits der Gmail API6.000 Kontingenteinheiten pro Minute je Nutzer und Google-Cloud-Projekt, laut den Nutzungslimits der Gmail API. Andere Anwendungen desselben Projekts, die im Namen desselben Postfachs handeln, zählen mit.

Lehnt Google die Anmeldung ab, etwa weil der Schlüssel gelöscht wurde, die Delegierung fehlt oder das Postfach nicht zu deinem Google Workspace gehört, oder gibt es das Label nicht, zeigen die Logs der Verbindung Polling stopped mit dem Grund. connic prüft dann nicht weiter, bis du die Verbindung oder ihren Kontozugang erneut speicherst. Dasselbe passiert, wenn Gmail mit 400, 401, 403 oder 404 antwortet, etwa weil die Gmail API im Projekt nicht aktiviert ist. Drosselung, Netzwerk- und Serverfehler erscheinen als Poll error. connic versucht es weiter und wartet nach jedem Fehler länger, bis zu 15 Minuten. Lässt sich eine E-Mail nicht als gelesen markieren, zeigen die Logs eine Warnung, und die E-Mail gilt trotzdem als verarbeitet.

Gmail bewahrt den Verlauf eines Postfachs mindestens etwa eine Woche auf, in seltenen Fällen nur einige Stunden. Fehlt der Verlauf, den connic braucht, etwa nach einer langen Pause, liest connic das Label ab seiner letzten vollständigen Prüfung abzüglich 5 Minuten erneut und überspringt E-Mails, die Agenten schon erhalten haben.

Jede verarbeitete E-Mail erscheint in den Runs der Verbindung mit der Zahl der gestarteten Agenten. Lässt sich ein Run nicht starten, liest connic die E-Mail bei der nächsten Prüfung erneut. Agenten, die sie schon erhalten haben, bekommen dabei keinen zweiten Run. Nach 3 fehlgeschlagenen Leseversuchen, die an der E-Mail selbst liegen, etwa weil das Herunterladen länger als 20 Sekunden dauert, überspringt connic die E-Mail, damit spätere E-Mails nicht warten müssen. Eine übersprungene E-Mail erscheint in den Runs der Verbindung als fehlgeschlagen.