emailctl

README

emailctl

CLI tool that fetches email as JSON, for use in automation pipelines.

Install

go install github.com/vikingpingvin/emailctl@latest
# or
git clone https://github.com/vikingpingvin/emailctl && cd emailctl && go build -o emailctl .

Setup

Gmail (OAuth2)

Requires a Google Cloud project with Gmail API enabled and OAuth2 Desktop credentials.

emailctl configure --account personal --type gmail
# Prompts: Client ID, Client Secret → opens browser → paste auth code

IMAP (App Password)

For Gmail: generate an App Password at myaccount.google.com/apppasswords.

emailctl configure --account personal --type imap
# Prompts: host (imap.gmail.com), port (993), email, password

See Config for info

Usage

emailctl fetch [--query QUERY] [--limit N] [--offset N] [--account NAME]

Flag	Default	Description
--query	""	Gmail-style search query
--limit	20	Max emails to return
--offset	0	Skip N emails (pagination)
--account	config default	Account name

Query Syntax

Query	Effect
is:unread	Unread only
is:read	Read only
from:addr	From address
subject:text	Subject contains
after:YYYY/MM/DD	Since date
before:YYYY/MM/DD	Before date
category:primary	Gmail Primary tab

JSON Output

{
  "account": "personal",
  "query": "is:unread",
  "total": 2,
  "emails": [
    {
      "id": "19cc32ebebd3669a",
      "thread_id": "19cb40d0d119f61b",
      "from": "Alice <alice@example.com>",
      "to": ["you@gmail.com"],
      "subject": "Meeting tomorrow",
      "snippet": "Hi, can we move the meeting...",
      "body": "Hi, can we move the meeting to 3pm?",
      "date": "2026-03-06T12:45:42Z",
      "labels": ["INBOX", "IMPORTANT"],
      "is_read": false,
      "has_attachment": false
    }
  ]
}

Automation

emailctl fetch --query "is:unread category:primary" --limit 10 | jq '.emails[] | {subject, from, snippet}'

Designed to be composed — pipe output into jq, pass to an LLM node, or trigger downstream actions in n8n / chainrun.

Config

Stored at ~/.config/emailctl/config.json. Credentials are in plaintext — secure your filesystem appropriately.

Providers

Type	Auth method
gmail	OAuth2 via Google Cloud project
imap	Username + password/app-password over TLS