---
title: Supermail Contact Groups
---
# Supermail Contact Groups

## What it is

Contact groups let you name a reusable set of people once, then drop the whole group into a
Supermail recipient field (To / Cc / Bcc) instead of typing everyone's address every time. Pick a
group and each person is added as an individual, removable recipient.

There are TWO sources, side by side:

- **Your Google contact groups** — the groups you already keep in Google Contacts, shown READ-ONLY.
  You manage them in Google Contacts; Supermail just lets you use them. They follow you across
  devices automatically (it's Google's data).
- **Your own in-app groups** — quick groups you create right in Supermail, saved on THIS device for
  the signed-in account.

It is **in development and off by default** — hidden until you turn it on in Settings → Lab (the
`supermailContactGroupsEnabled` toggle). When off, nothing changes.

## Where to find it

In development and off by default — reveal it from **Settings → Lab**. Once on, groups are managed in Supermail's own **Settings → Inbox → Contact groups** and used from the composer's recipient fields.

## How it behaves

### How to use it

- **In the composer:** start typing a group's name in To / Cc / Bcc. Matching groups appear ABOVE
  the individual contacts, each showing how many people are in it (a Google group is tagged
  "Google"). Select one and everyone in it is filled in as individual chips — a group is never sent
  as an opaque blob.
- **Make your own:** Supermail's Settings → Inbox → "Contact groups" — create a group, rename it, add or
  remove people by email, or delete it (with undo). Your Google groups are listed there read-only
  with a note that they're managed in Google Contacts.

### Read-only for Google, and why

Supermail can *use* your Google groups but not *edit* them — the shared permission is read-only by
design. To change who is in a Google group, edit it in Google Contacts and it updates here
automatically. Editing is reserved for your own in-app groups.

### Requirements + honest states

- Google groups need Omniscio's shared Google connection turned on ("Use Omniscio's Google
  connection for mail"). Without it, the Settings section says so and only your in-app groups work.
- If your Google connection predates the contacts permission, you are asked to reconnect once.
- Only groups with at least one email-bearing member appear, and the member count reflects people
  who actually have an email — so "Team (5)" always fills in 5.

## For agents

### How it works (architecture)

Shaped by Supermail's split (the mailbox / compose UI is the vendored plugin; the Google grant
lives only in the main process):

- **Google groups are read through Omniscio's shared Google grant** — the SAME read-only
  `contacts.readonly` permission the Quick Email address book already uses (no new consent screen).
  The main process reads the People API `contactGroups` (USER groups only, resolving each member to
  a name + email) and returns them over a desktop-only bridge/IPC channel
  (`SUPERMAIL_CONTACT_GROUPS`, blocked over the mobile web bridge). The OAuth token never leaves the
  main process; fetched contacts are held in memory only and are never written to disk.
- **Your in-app groups are device-local** — stored in the browser's local storage under a
  per-account key, so a group made under one account never bleeds into another.
- **Either kind expands to individual recipients before send** — the outbound message only ever
  carries individual addresses, never a group object.

Code: `src/main/services/google/google-contact-groups-service.ts` (main) +
`src/plugins/supermail/ui/src/features/contact-groups/` (plugin). Contract:
supermail-contact-groups-contract.

## Related

Supermail itself covers the client these groups are used from, and the send-shortcuts page explains what happens after you fill the recipient fields.