Skip to main content
connic
Connectors

Gmail

Start agents from incoming email in a Google Workspace mailbox and send their replies or notifications from it, through your own Google service account.

Last updated
ModesInbound, outbound
YAML typegmail
CredentialsA Connection of type gmail, shown as Google Workspace in the dashboard, with the JSON key of your own Google service account.
MailboxesGoogle Workspace users with Gmail. Consumer accounts (@gmail.com) aren't supported; connect them with the Email connector and an app password.
BridgeNot supported
Custom domainNot supported
Linked agentsOne or more. An email starts every linked agent.
While pausedInbound stops checking the label. Email that arrives meanwhile is processed after Resume. Outbound sends nothing.

Set up

  1. Create a service account with a JSON key in a Google Cloud project that has the Gmail API enabled. Then have a super admin authorize its client ID for domain-wide delegation with the scope https://www.googleapis.com/auth/gmail.modify.

  2. Open the agent. In Connector Flow, click Add inbound connector for inbound or Add outbound connector for outbound. Then click Create New Connector and choose Gmail.

  3. Choose the mode. Under Connection, pick a saved Google Workspace Connection or create one with the contents of the key file.

  4. Enter the Mailbox. For inbound, set the Label and Mark as Read. For outbound, optionally enter Default Recipients.

  5. Click Create. An inbound connector starts checking the label. For outbound, choose how the agent uses the connector and click Link connector.

In code

Declare the connector in connectors/*.yaml. connection names the Connection that holds the service account key.

connectors/support-inbox.yaml
type: gmail
mode: inbound
connection: acme-google   # Google Workspace Connection with the service account key
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 }

Configuration

The fields of a Gmail connector, the same in connectors/*.yaml, the REST API, and connic MCP. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.

FieldTypeStatusDescription
typestringRequiredgmail.
modestringRequiredinbound or outbound. Dashboard: Mode.
connectionstringRequiredName or ID of a Connection of type gmail. See Service account. Dashboard: Connection.
configobjectRequiredGmail settings.
mailboxstringRequiredThe address of the Google Workspace user whose mailbox receives or sends the email, such as support@example.com. The user needs Gmail; a group isn't a mailbox. Dashboard: Mailbox.
labelstringOptionalInbound. The label to check: a system label by its ID, such as INBOX, STARRED, or IMPORTANT, or a label of your own by its name, case-insensitive. A nested label takes its full name, such as Support/Billing. Dashboard: Label.Default: INBOX
mark_as_readbooleanOptionalInbound. Mark an email as read once every linked agent received it. Dashboard: Mark as Read.Default: true
default_tostringOptionalOutbound. Recipients of an email that neither sets to nor replies to an incoming Gmail email: one address or comma-separated addresses. Dashboard: Default Recipients.

Agent input

Modes: Inbound

An inbound connector follows the label through the Gmail history and starts a run for every linked agent with each new email. It starts with the email that arrives after its first check; email that was already there isn't processed, and neither is an older email that gets the label later. Email that arrives with the label, for example through a Gmail filter, counts. connic remembers how far it got, so an email isn't processed twice, even with Mark as Read off. Changing the mailbox or the label starts again at that moment. The run receives the email in the same shape as the Email connector, so an agent can take input from both:

payload.json
{
  "subject": "Help with order #12345",
  "from": "Jane Doe <jane@example.com>",
  "from_address": "jane@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": "Hi, my order hasn't arrived yet...",
  "body_html": "<div>Hi, my order hasn't arrived yet...</div>",
  "has_attachments": true,
  "attachments": [
    {
      "filename": "receipt.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 and to are the email's headers with name and address; from_address is the bare sender address.
  • date is the email's Date header, or the time Gmail received it when the header is missing. message_id is the email's Message-ID header.
  • body_text and body_html are the plain-text and HTML parts as the sender wrote them. Gmail doesn't convert between the two, so one of them can be empty.
  • _gmail names the connector, the mailbox, the label, the email's Gmail message ID, and the ID of its Gmail thread.

Attachments

Attachments follow the rules of the Email connector: the same included types, the same skipped tracking images and inline images under 50 KB, and the same encoding. Text, JSON, and XML files carry their content as text ("encoding": "text"), all other files as base64 ("encoding": "base64").

An email takes up to 50 attachments, at most 32 MiB combined. At the first attachment over a limit, connic keeps the attachments before it and omits that one and all later ones. Files of other types are omitted too. An omitted attachment has "content": null and a file_issue, and the payload lists every omission in file_issues:

omitted attachment
{
  "filename": "archive.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": "archive.rar",
    "size_bytes": 20480
  }
}

The agent receives the email even when no attachment was accepted. Turn on Files required for an agent in the connector's details drawer, or set files_required: true on its link in YAML, to fail the run before it starts when an attachment is missing or was omitted.

Service account

connic signs in to Google as a service account in your own Google Cloud project, with no consent screen and no user sign-in. Its key lives on the Connection, not on the connector, and connic stores it encrypted. Manage Connections under Project Settings → Connections; a changed Connection applies to every connector that uses it. One Google Workspace Connection can serve Gmail and Google Sheets connectors, inbound and outbound, on several mailboxes and spreadsheets.

  1. In the Google Cloud console, pick or create a project in your organization and enable the Gmail API. For Google Sheets connectors, enable the Google Sheets API too.

  2. Under IAM & Admin → Service accounts, click Create service account. It needs no roles.

  3. Open the service account and go to Keys → Add key → Create new key. Choose JSON and click Create. Google downloads the key file once and can't show it again.

  4. Paste the contents of the file into Service account key (JSON) of a Google Workspace Connection. connic checks that it's a service account key with a readable private key when you save.

Key file valueDescription
client_idThe service account's numeric client ID, also shown as Unique ID on its page in the Google Cloud console. A super admin enters it for domain-wide delegation.
client_emailThe service account's email address, ending in .iam.gserviceaccount.com. Spreadsheets for Google Sheets connectors are shared with it. The dashboard suggests Google Workspace · <client_email> as the Connection's name.

In Google Cloud organizations created on or after 3 May 2024, the organization policy iam.disableServiceAccountKeyCreation (iam.managed.disableServiceAccountKeyCreation) blocks creating service account keys by default. An organization policy administrator has to allow it for the project; Google describes a tag-based exception in Create and delete service account keys.

Keys don't expire unless an organization policy sets a validity period. To rotate the key, create a new one, paste it into the Connection, and then delete the old key in the Google Cloud console.

Domain-wide delegation

A Gmail connector acts as its mailbox through domain-wide delegation. A super admin opens the Google Admin console, goes to Security → Access and data control → API controls → Manage Domain Wide Delegation, and clicks Add new. There, they enter the service account's client ID and this scope under OAuth scopes, then click Authorize:

OAuth scope
https://www.googleapis.com/auth/gmail.modify

The scope lets the service account read, change, and send email as every user of the domain. Google can't limit domain-wide delegation to certain users or organizational units. connic acts only as the mailbox named on each Gmail connector. Google Sheets connectors don't need delegation.

Outbound delivery

Modes: Outbound

An outbound Gmail connector sends one email from the Mailbox each time it's used: when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage. The email lands in the mailbox's Sent folder. These fields control it:

FieldDescription
toRecipients: one address, comma-separated addresses, or a list. Each can be address or Name <address>. Sends a new email even when the run came from an incoming Gmail email.
ccCopy recipients, in the same formats as to. Also used for replies.
bccBlind copy recipients, in the same formats as to. Also used for replies.
subjectThe subject of a new email. Replies take the subject of the incoming email.
bodyThe plain-text body.
html_bodyAn HTML body. Together with body, the email has both parts and the plain text is the alternative for mail apps that don't show HTML. Without body, the email is HTML only.
reply_toThe address that replies to this email go to.

When an inbound Gmail connector started the run and the output sets no to, the email is a reply to the incoming email, in the same Gmail thread. That needs the outbound connector to use the same mailbox and Connection as the inbound one. The reply goes to the reply-to address of the incoming email, or to its sender if it has none. Its subject is the incoming subject with Re: in front, unless it already starts with it, and its In-Reply-To and References headers keep the conversation together in other mail apps too. Otherwise, the recipients come from to, then the connector's Default Recipients; without either, the send fails with missing_recipient. A new email takes its subject from subject, or Agent Response without one. Outbound emails have no attachments.

Automatic output

An automatic link turns the run's final output into an email. Plain text, and any output that isn't a JSON object, becomes the body. A JSON object sets the fields above, and also accepts message for body and html for html_body. Give the agent an output schema to make it return these fields. This output replies to the incoming email with a copy to the orders team:

output.json
{
  "body": "Your order shipped this morning.",
  "html_body": "<p>Your order shipped this morning.</p>",
  "cc": ["orders@example.com"]
}

Agent-tool and middleware payload

The model or middleware passes the fields above as the payload. body is required and all other fields are optional; message, html, and any other field are rejected. connic adds the mailbox, the sign-in, and the retries, none of which the model sees.

connector-payload.json
{
  "body": "Your request has been resolved.",
  "to": ["jane@example.com"],
  "subject": "Your support request",
  "html_body": "<p>Your request has been resolved.</p>",
  "cc": ["manager@example.com"],
  "bcc": ["archive@example.com"],
  "reply_to": "support@example.com"
}

Delivery and retries

connic signs in as the service account on behalf of the mailbox and hands the email to the Gmail API, which sends it to every address in to, cc, and bcc. When Gmail can't be reached or rate-limits the request, connic tries again, 3 times in total, waiting as long as Google asks. Any other error fails the delivery without a retry. If the connection breaks after the email was handed over, or Gmail answers with a server error, connic can't tell whether the email went out and doesn't retry, so it's never sent twice; check the mailbox's Sent folder. The connector's runs show each delivery with its error.

Limits and errors

LimitValue
Label checksAbout every 30 seconds
Emails per checkRead from the Gmail history 10 at a time until the label is caught up or 60 seconds have passed. The rest follow in the next check.
Attachments per email50, at most 32 MiB combined
Delivery attempts3, only when Gmail can't be reached or rate-limits the request
Google sending limits2,000 messages per user per day, set by Google Workspace
Gmail API limits6,000 quota units per minute per user and Google Cloud project, per the Gmail API usage limits. Other apps of the same project that act as the same mailbox count too.

When Google rejects the sign-in, for example because the key was deleted, delegation is missing, or the mailbox is outside your Google Workspace, or when the label doesn't exist, the connector's logs show Polling stopped with the reason, and connic stops checking until you save the connector or its Connection again. The same happens when Gmail answers 400, 401, 403, or 404, such as when the Gmail API isn't enabled in the project. Rate limits, network errors, and server errors appear as Poll error; connic keeps trying and waits longer after each failure, up to 15 minutes. If an email can't be marked as read, the logs show a warning and the email still counts as processed.

Gmail keeps a mailbox's history for at least about a week, in rare cases only a few hours. When the history connic needs is gone, for example after a long pause, connic reads the label again from its last complete check, minus 5 minutes, and skips email that agents already received.

Every processed email appears in the connector's runs with the number of agents it started. If a run can't be started, connic reads the email again on the next check; agents that already received it don't get a second run. connic skips an email after 3 failed reads caused by the email itself, such as one that takes longer than 20 seconds to download, so later email isn't held up. A skipped email appears in the connector's runs as failed.