| Name | gmail-cli JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Gmail CLI sender tool using OAuth2 authentication for sending emails via Gmail API |
| upload_time | 2025-09-11 22:23:04 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
gmail
email
cli
oauth2
google-api
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Gmail CLI
A command-line tool for sending emails, replying to messages, and managing drafts via Gmail API using OAuth2 authentication.
## Features
- **Two-step workflow** - Create a draft, then send it
- **Reply to emails** - Reply to messages or threads with threading support
- **OAuth2 authentication** - Secure Gmail API access
- **Multiple input formats** - Markdown (default), HTML, and plain text
- **Automatic signature inclusion** - Uses your Gmail signature by default
- **File attachments** - Support for multiple attachments
- **Multiple recipients** - TO, CC, and BCC support
- **Reply-all support** - Smart recipient management for group conversations
- **Configurable credentials** - Support for client ID/secret or credentials file
## Installation
```bash
# Install using pip
pip install gmail-cli
# Or using uv
uv add gmail-cli
```
## Usage
### Two-Step Email Workflow
The Gmail CLI follows a simple two-step process:
1. **Create a draft** with all your email content
2. **Send the draft** using its ID
### Step 1: Creating Drafts
```bash
# Create draft with Markdown content (default)
gmail-cli draft --to recipient@example.com --subject "Hello" --body "**Bold** and *italic* text"
# Returns: Draft ID: r-123456789
# Create draft from markdown file
gmail-cli draft --to user@example.com --subject "Report" --body-file report.md
# Create HTML email draft
gmail-cli draft --to user@example.com --subject "Newsletter" --body-file newsletter.html --input-format html
# Create draft with attachments
gmail-cli draft --to user@example.com --subject "Files" --body "See attached" --attachment file1.pdf --attachment file2.txt
# Multiple recipients
gmail-cli draft --to user1@example.com --to user2@example.com --cc manager@example.com --subject "Meeting" --body "Agenda attached"
```
### Step 2: Sending Drafts
```bash
# Send a draft using its ID
gmail-cli send --draft-id r-123456789
```
### Replying to Emails
The reply command creates a draft reply that preserves email threading:
```bash
# Reply to a specific message
gmail-cli reply --message-id msg_abc123 --body "Thanks for the update!"
# Returns: Draft ID: r-987654321
# Reply to a thread (replies to the latest message)
gmail-cli reply --thread-id thread_xyz789 --body "I agree with this approach."
# Reply-all to include all original recipients
gmail-cli reply --message-id msg_abc123 --body "Thanks everyone!" --reply-all
# Reply with additional recipients
gmail-cli reply --message-id msg_abc123 --body "Adding Jane to this thread" --cc jane@example.com
# Reply with attachments
gmail-cli reply --message-id msg_abc123 --body "See attached" --attachment document.pdf
# Reply without quoting the original message
gmail-cli reply --message-id msg_abc123 --body "Quick reply" --no-quote
# Reply without signature
gmail-cli reply --message-id msg_abc123 --body "Brief response" --no-signature
# Send the reply draft
gmail-cli send --draft-id r-987654321
```
### Complete Workflow Examples
#### New Email
```bash
# 1. Create a draft with your content
gmail-cli draft --to team@example.com --subject "Project Update" --body-file update.md --attachment report.pdf
# Output: Draft created! Draft ID: r-123456789
# 2. Send the draft when ready
gmail-cli send --draft-id r-123456789
# Output: Draft sent successfully!
```
#### Reply to Email
```bash
# 1. Create a reply draft
gmail-cli reply --message-id msg_abc123 --body "Thanks for sharing this!" --reply-all
# Output: Reply draft created! Draft ID: r-987654321
# 2. Send the reply
gmail-cli send --draft-id r-987654321
# Output: Draft sent successfully!
```
## Setup
### Authentication Configuration
The CLI supports multiple authentication methods:
#### Option 1: Credentials File (Legacy)
1. Download OAuth2 credentials from Google Cloud Console
2. Use `--credentials-file path/to/credentials.json` when running commands
#### Option 2: Client ID and Secret (Recommended)
1. Get your OAuth2 client ID and secret from Google Cloud Console
2. Configure using either:
- CLI arguments: `--client-id YOUR_ID --client-secret YOUR_SECRET`
- Config file: Create `~/.config/gmail-cli/config.json`:
```json
{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}
```
### First Run
On first use, the tool will open a browser for OAuth2 authentication and save the token for future use.
## Command Options
### Common Options (All Commands)
- `--credentials-file` - Path to OAuth2 credentials JSON file
- `--token-file` - Path to store/read OAuth2 token
- `--client-id` - OAuth2 client ID
- `--client-secret` - OAuth2 client secret
- `--config-file` - Path to configuration JSON file
### Draft Command Options
- `--to` - Recipient email addresses (required, multiple allowed)
- `--subject` - Email subject (required)
- `--body` - Email body text
- `--body-file` - Read body content from file
- `--input-format` - Input format: `markdown` (default), `html`, or `plaintext`
- `--cc` - CC recipients (multiple allowed)
- `--bcc` - BCC recipients (multiple allowed)
- `--attachment` - File attachments (multiple allowed)
- `--sender` - Override sender email (if permitted)
- `--signature/--no-signature` - Include Gmail signature (default: enabled)
### Reply Command Options
- `--message-id` - Message ID to reply to (use either this or --thread-id)
- `--thread-id` - Thread ID to reply to latest message (use either this or --message-id)
- `--body` - Reply body text (required unless --body-file)
- `--body-file` - Read reply body from file
- `--input-format` - Input format: `markdown` (default), `html`, or `plaintext`
- `--reply-all` - Reply to all recipients
- `--to` - Additional TO recipients (multiple allowed)
- `--cc` - Additional CC recipients (multiple allowed)
- `--bcc` - BCC recipients (multiple allowed)
- `--attachment` - File attachments (multiple allowed)
- `--no-quote` - Don't include quoted original message
- `--signature/--no-signature` - Include Gmail signature (default: enabled)
### Send Command Options
- `--draft-id` - Draft ID to send (required)
## Dependencies
All dependencies are managed via PEP 723 inline metadata:
- google-api-python-client
- google-auth
- google-auth-oauthlib
- google-auth-httplib2
- click
- markdown
- Pygments (for syntax highlighting in code blocks)
Raw data
{
"_id": null,
"home_page": null,
"name": "gmail-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "gmail, email, cli, oauth2, google-api",
"author": null,
"author_email": "Stephan Fitzpatrick <knowsuchagency@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/1e/9a/b22b77f95afaf1079c069c6cecbbc0e20281014b07b40a9a7c97cfc07f84/gmail_cli-0.1.0.tar.gz",
"platform": null,
"description": "# Gmail CLI\n\nA command-line tool for sending emails, replying to messages, and managing drafts via Gmail API using OAuth2 authentication.\n\n## Features\n\n- **Two-step workflow** - Create a draft, then send it\n- **Reply to emails** - Reply to messages or threads with threading support\n- **OAuth2 authentication** - Secure Gmail API access\n- **Multiple input formats** - Markdown (default), HTML, and plain text\n- **Automatic signature inclusion** - Uses your Gmail signature by default\n- **File attachments** - Support for multiple attachments\n- **Multiple recipients** - TO, CC, and BCC support\n- **Reply-all support** - Smart recipient management for group conversations\n- **Configurable credentials** - Support for client ID/secret or credentials file\n\n## Installation\n\n```bash\n# Install using pip\npip install gmail-cli\n\n# Or using uv\nuv add gmail-cli\n```\n\n## Usage\n\n### Two-Step Email Workflow\n\nThe Gmail CLI follows a simple two-step process:\n1. **Create a draft** with all your email content\n2. **Send the draft** using its ID\n\n### Step 1: Creating Drafts\n\n```bash\n# Create draft with Markdown content (default)\ngmail-cli draft --to recipient@example.com --subject \"Hello\" --body \"**Bold** and *italic* text\"\n# Returns: Draft ID: r-123456789\n\n# Create draft from markdown file\ngmail-cli draft --to user@example.com --subject \"Report\" --body-file report.md\n\n# Create HTML email draft\ngmail-cli draft --to user@example.com --subject \"Newsletter\" --body-file newsletter.html --input-format html\n\n# Create draft with attachments\ngmail-cli draft --to user@example.com --subject \"Files\" --body \"See attached\" --attachment file1.pdf --attachment file2.txt\n\n# Multiple recipients\ngmail-cli draft --to user1@example.com --to user2@example.com --cc manager@example.com --subject \"Meeting\" --body \"Agenda attached\"\n```\n\n### Step 2: Sending Drafts\n\n```bash\n# Send a draft using its ID\ngmail-cli send --draft-id r-123456789\n```\n\n### Replying to Emails\n\nThe reply command creates a draft reply that preserves email threading:\n\n```bash\n# Reply to a specific message\ngmail-cli reply --message-id msg_abc123 --body \"Thanks for the update!\"\n# Returns: Draft ID: r-987654321\n\n# Reply to a thread (replies to the latest message)\ngmail-cli reply --thread-id thread_xyz789 --body \"I agree with this approach.\"\n\n# Reply-all to include all original recipients\ngmail-cli reply --message-id msg_abc123 --body \"Thanks everyone!\" --reply-all\n\n# Reply with additional recipients\ngmail-cli reply --message-id msg_abc123 --body \"Adding Jane to this thread\" --cc jane@example.com\n\n# Reply with attachments\ngmail-cli reply --message-id msg_abc123 --body \"See attached\" --attachment document.pdf\n\n# Reply without quoting the original message\ngmail-cli reply --message-id msg_abc123 --body \"Quick reply\" --no-quote\n\n# Reply without signature\ngmail-cli reply --message-id msg_abc123 --body \"Brief response\" --no-signature\n\n# Send the reply draft\ngmail-cli send --draft-id r-987654321\n```\n\n### Complete Workflow Examples\n\n#### New Email\n```bash\n# 1. Create a draft with your content\ngmail-cli draft --to team@example.com --subject \"Project Update\" --body-file update.md --attachment report.pdf\n# Output: Draft created! Draft ID: r-123456789\n\n# 2. Send the draft when ready\ngmail-cli send --draft-id r-123456789\n# Output: Draft sent successfully!\n```\n\n#### Reply to Email\n```bash\n# 1. Create a reply draft\ngmail-cli reply --message-id msg_abc123 --body \"Thanks for sharing this!\" --reply-all\n# Output: Reply draft created! Draft ID: r-987654321\n\n# 2. Send the reply\ngmail-cli send --draft-id r-987654321\n# Output: Draft sent successfully!\n```\n\n## Setup\n\n### Authentication Configuration\n\nThe CLI supports multiple authentication methods:\n\n#### Option 1: Credentials File (Legacy)\n1. Download OAuth2 credentials from Google Cloud Console\n2. Use `--credentials-file path/to/credentials.json` when running commands\n\n#### Option 2: Client ID and Secret (Recommended)\n1. Get your OAuth2 client ID and secret from Google Cloud Console\n2. Configure using either:\n - CLI arguments: `--client-id YOUR_ID --client-secret YOUR_SECRET`\n - Config file: Create `~/.config/gmail-cli/config.json`:\n ```json\n {\n \"client_id\": \"YOUR_CLIENT_ID\",\n \"client_secret\": \"YOUR_CLIENT_SECRET\"\n }\n ```\n\n### First Run\nOn first use, the tool will open a browser for OAuth2 authentication and save the token for future use.\n\n## Command Options\n\n### Common Options (All Commands)\n- `--credentials-file` - Path to OAuth2 credentials JSON file\n- `--token-file` - Path to store/read OAuth2 token\n- `--client-id` - OAuth2 client ID\n- `--client-secret` - OAuth2 client secret\n- `--config-file` - Path to configuration JSON file\n\n### Draft Command Options\n- `--to` - Recipient email addresses (required, multiple allowed)\n- `--subject` - Email subject (required)\n- `--body` - Email body text\n- `--body-file` - Read body content from file\n- `--input-format` - Input format: `markdown` (default), `html`, or `plaintext`\n- `--cc` - CC recipients (multiple allowed)\n- `--bcc` - BCC recipients (multiple allowed)\n- `--attachment` - File attachments (multiple allowed)\n- `--sender` - Override sender email (if permitted)\n- `--signature/--no-signature` - Include Gmail signature (default: enabled)\n\n### Reply Command Options\n- `--message-id` - Message ID to reply to (use either this or --thread-id)\n- `--thread-id` - Thread ID to reply to latest message (use either this or --message-id)\n- `--body` - Reply body text (required unless --body-file)\n- `--body-file` - Read reply body from file\n- `--input-format` - Input format: `markdown` (default), `html`, or `plaintext`\n- `--reply-all` - Reply to all recipients\n- `--to` - Additional TO recipients (multiple allowed)\n- `--cc` - Additional CC recipients (multiple allowed)\n- `--bcc` - BCC recipients (multiple allowed)\n- `--attachment` - File attachments (multiple allowed)\n- `--no-quote` - Don't include quoted original message\n- `--signature/--no-signature` - Include Gmail signature (default: enabled)\n\n### Send Command Options\n- `--draft-id` - Draft ID to send (required)\n\n## Dependencies\n\nAll dependencies are managed via PEP 723 inline metadata:\n- google-api-python-client\n- google-auth\n- google-auth-oauthlib \n- google-auth-httplib2\n- click\n- markdown\n- Pygments (for syntax highlighting in code blocks)\n",
"bugtrack_url": null,
"license": null,
"summary": "Gmail CLI sender tool using OAuth2 authentication for sending emails via Gmail API",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/knowsuchagency/gmail-cli",
"Repository": "https://github.com/knowsuchagency/gmail-cli"
},
"split_keywords": [
"gmail",
" email",
" cli",
" oauth2",
" google-api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "966cbe5219506c1c822435407a53ac09edaffa2e2983a0117104b4b16f87bc4b",
"md5": "6d6ad7fbf2de67e2170b16e4b026cc72",
"sha256": "ba27345380a92fd166ed497c0ceefdd7c2d73397a6d9e4082123549620f00ecd"
},
"downloads": -1,
"filename": "gmail_cli-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6d6ad7fbf2de67e2170b16e4b026cc72",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13150,
"upload_time": "2025-09-11T22:23:03",
"upload_time_iso_8601": "2025-09-11T22:23:03.394950Z",
"url": "https://files.pythonhosted.org/packages/96/6c/be5219506c1c822435407a53ac09edaffa2e2983a0117104b4b16f87bc4b/gmail_cli-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1e9ab22b77f95afaf1079c069c6cecbbc0e20281014b07b40a9a7c97cfc07f84",
"md5": "628720d686aee922b48b0e0e256623bb",
"sha256": "7491b5bb64a9e716595f6554feb6f9cfa0fbfa30f62a647dc5cb532f4d13c6f8"
},
"downloads": -1,
"filename": "gmail_cli-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "628720d686aee922b48b0e0e256623bb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13210,
"upload_time": "2025-09-11T22:23:04",
"upload_time_iso_8601": "2025-09-11T22:23:04.721036Z",
"url": "https://files.pythonhosted.org/packages/1e/9a/b22b77f95afaf1079c069c6cecbbc0e20281014b07b40a9a7c97cfc07f84/gmail_cli-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 22:23:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "knowsuchagency",
"github_project": "gmail-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gmail-cli"
}
