EmailOS Groups Command Documentation

The mailos groups command manages email groups for bulk email sending. Groups allow you to organize email addresses into named collections that can be used with the --group flag in send commands.

Basic Usage

# List all groups
mailos groups

# Create a new group
mailos groups --update "team" --emails "[email protected],[email protected]"

# Send email to a group
mailos send --group "team" --subject "Team Update" --body "Hello team!"

Command-Line Flags

Advanced Options

Flag	Short	Type	Default	Description	Example
--account	-a	string		Email account to use	mailos groups --account [email protected]
--add-member		string		Add a member to an existing group	mailos groups --add-member value
--delete		string		Delete the specified group	mailos groups --delete value
--description		string		Description for the group	mailos groups --description value
--emails		string		Comma-separated list of email addresses	mailos groups --emails value
--group		string		Group name for add/remove member operations	mailos groups --group value
--list-members		string		List all members of the specified group	mailos groups --list-members value
--remove-member		string		Remove a member from an existing group	mailos groups --remove-member value
--update		string		Create or update a group with the given name	mailos groups --update value

Group Operations

Creating Groups

Create a new group with multiple email addresses:

mailos groups \
  --update "dev-team" \
  --description "Development team members" \
  --emails "[email protected],[email protected],[email protected]"

Listing Groups

View all configured groups:

mailos groups

Output example:

Email Groups:
=============

dev-team (3 emails)
  Description: Development team members
  Emails: [email protected], [email protected], [email protected]

marketing (2 emails)
  Description: Marketing team
  Emails: [email protected], [email protected]

Managing Group Members

Add a new member to an existing group:

mailos groups --add-member "[email protected]" --group "dev-team"

Remove a member from a group:

mailos groups --remove-member "[email protected]" --group "dev-team"

List all members of a specific group:

mailos groups --list-members "dev-team"

Updating Groups

Modify an existing group's emails and description:

mailos groups \
  --update "dev-team" \
  --description "Updated development team" \
  --emails "[email protected],[email protected],[email protected]"

Note: Updating a group replaces all existing members with the new list.

Deleting Groups

Remove a group entirely:

mailos groups --delete "old-team"

Using Groups with Send Command

Once groups are created, use them with the send command:

Single Group

mailos send \
  --group "dev-team" \
  --subject "Sprint Planning" \
  --body "Please join the sprint planning meeting at 2 PM."

Multiple Recipients

Combine groups with individual recipients:

mailos send \
  --group "dev-team" \
  --to "[email protected]" \
  --cc "[email protected]" \
  --subject "Project Update" \
  --body "Weekly status update attached" \
  --attach "status-report.pdf"

Local Recipient Files

mailos send --group can also read recipients from a local .md, .markdown, or .txt file. This is useful when you want a portable recipient set outside ~/.email/groups.json. A local file path in --group is treated as a recipient file, not as the message body; keep using --body, stdin, or --file for the email content itself.

Recipient files may use YAML-style frontmatter delimiters (---) or plain key: value metadata. They must include at least one to, cc, or bcc recipient.

to: [email protected], [email protected]
cc: [email protected]
bcc: [email protected]
name: Team Updates
subject: Project Update
description: Weekly project recipients
preheader: Quick weekly status summary
signature: "Regards, Andrew"

mailos send \
  --group ./team-recipients.txt \
  --body "Weekly status update attached" \
  --dry-run

Supported recipient-file metadata fields are:

Field	Description
to	Comma-separated primary recipients
cc	Comma-separated CC recipients
bcc	Comma-separated BCC recipients
subject	Default subject when --subject is not supplied
name	Sender display name used for the message
from_name	Sender display name alias
description	Human-readable note about the recipient file
preheader	Preview text for templated messages
signature	Signature text unless --no-signature is used
group	Group metadata value for frontmatter workflows
priority	Priority metadata value for frontmatter workflows
file	Body file metadata used by frontmatter workflows

Command-line flags still win where applicable. For example, --subject overrides a subject: value in the recipient file.

Nested Recipient Files

Values inside to, cc, or bcc can also reference another local recipient file in the same directory. Use either an explicit filename such as finance.txt or an extensionless name such as finance; extensionless names are resolved by trying .txt, .md, and .markdown.

The nested file's to, cc, and bcc recipients are flattened into the field that referenced it. This lets a parent file control whether a reusable nested group is used as To, CC, or BCC for that send.

Parent file:

to: [email protected]
cc: project-watchers
bcc: audit-archive
name: Project Updates

project-watchers.txt:

to: [email protected], [email protected]

audit-archive.txt:

to: [email protected]

Dry-run the expanded send before removing --dry-run:

mailos send \
  --group ./parent.txt \
  --subject "Nested group check" \
  --body "Checking nested recipient expansion" \
  --plain \
  --dry-run

The preview expands to:

To: [email protected]
CC: [email protected], [email protected]
BCC: [email protected]

Nested group references are resolved relative to the file that contains the reference. Recursive references fail with an error instead of looping.

Group Storage

Groups are stored in ~/.email/groups.json in JSON format:

{
  "groups": [
    {
      "name": "dev-team",
      "description": "Development team members",
      "emails": [
        "[email protected]",
        "[email protected]",
        "[email protected]"
      ]
    }
  ]
}

Email Validation

When adding emails to groups, EmailOS performs basic validation:

• Emails must contain an "@" symbol
• Invalid emails are automatically filtered out
• Duplicate emails within a group are prevented
• Case-insensitive duplicate detection

Use Cases

Team Communications

# Organize by department
mailos groups --update "engineering" --emails "[email protected],[email protected]"
mailos groups --update "design" --emails "[email protected],[email protected]"

# Send department updates
mailos send --group "engineering" --subject "Code Review Process" --file code-review.md

Client Management

# Organize clients by project
mailos groups --update "project-alpha" --emails "[email protected],[email protected]"

# Send project updates
mailos send --group "project-alpha" --subject "Alpha Project Status" --file alpha-update.md

Error Handling

Common errors and solutions:

Group Not Found

Error: group 'team-name' not found

• Verify group name spelling
• Use mailos groups to list available groups
• Create the group first if it doesn't exist

Invalid Email Addresses

Error: no valid emails provided

• Ensure emails contain "@" symbol
• Check for typos in email addresses
• Provide at least one valid email

Missing Required Flags

Error: --group flag is required when adding members

• Specify the target group when adding/removing members
• Use --group "group-name" flag

Best Practices

Group Naming

• Use descriptive, lowercase names with hyphens
• Examples: dev-team, customers-premium, project-alpha
• Avoid spaces and special characters

Email Management

• Regularly audit group membership
• Remove bounced or inactive email addresses
• Validate new email addresses before adding
• Use consistent email formatting

Notes

• Group names are case-insensitive for lookups
• Maximum group size is limited by your email provider's recipient limits
• Groups are stored locally and not synced across devices
• Email addresses are normalized to lowercase for consistency