Metadata-Version: 2.4
Name: muffinbite
Version: 0.1.14
Summary: Interactive Python CLI tool for sending personalized bulk emails via Gmail API or SMTP with explicit user-triggered execution
Home-page: https://www.muffinbite.dev/
Author: Shivansh Varshney
Author-email: shivanshvarshney45@gmail.com
License: MIT
Project-URL: Github, https://github.com/Shivansh-varshney/MuffinBite
Project-URL: Maintainer, https://www.shivanshvarshney.tech/
Keywords: email,cli,bulk-email,gmail-api,smtp,campaigns
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Environment :: Console
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Utilities
Requires-Python: >=3.10, <3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4==4.13.5
Requires-Dist: build==1.3.0
Requires-Dist: cachetools==5.5.2
Requires-Dist: certifi==2025.1.31
Requires-Dist: cffi==2.0.0
Requires-Dist: charset-normalizer==3.4.1
Requires-Dist: colorama==0.4.6
Requires-Dist: configparser==7.2.0
Requires-Dist: cryptography==45.0.7
Requires-Dist: docutils==0.22.2
Requires-Dist: et_xmlfile==2.0.0
Requires-Dist: google-api-core==2.24.2
Requires-Dist: google-api-python-client==2.167.0
Requires-Dist: google-auth==2.39.0
Requires-Dist: google-auth-httplib2==0.2.0
Requires-Dist: google-auth-oauthlib==1.2.1
Requires-Dist: googleapis-common-protos==1.70.0
Requires-Dist: httplib2==0.22.0
Requires-Dist: id==1.5.0
Requires-Dist: idna==3.10
Requires-Dist: jaraco.classes==3.4.0
Requires-Dist: jaraco.context==6.0.1
Requires-Dist: jaraco.functools==4.3.0
Requires-Dist: jeepney==0.9.0
Requires-Dist: keyring==25.6.0
Requires-Dist: markdown-it-py==4.0.0
Requires-Dist: mdurl==0.1.2
Requires-Dist: more-itertools==10.8.0
Requires-Dist: nh3==0.3.1
Requires-Dist: numpy==2.2.4
Requires-Dist: oauthlib==3.2.2
Requires-Dist: openpyxl==3.1.5
Requires-Dist: packaging==25.0
Requires-Dist: pandas==2.2.3
Requires-Dist: plyer==2.1.0
Requires-Dist: prettytable==3.16.0
Requires-Dist: prompt_toolkit==3.0.52
Requires-Dist: proto-plus==1.26.1
Requires-Dist: protobuf==6.30.2
Requires-Dist: pwinput==1.0.3
Requires-Dist: pyasn1==0.6.1
Requires-Dist: pyasn1_modules==0.4.2
Requires-Dist: pycparser==2.23
Requires-Dist: Pygments==2.19.2
Requires-Dist: pyparsing==3.2.3
Requires-Dist: pyproject_hooks==1.2.0
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: pytz==2025.2
Requires-Dist: readme_renderer==44.0
Requires-Dist: requests==2.32.3
Requires-Dist: requests-oauthlib==2.0.0
Requires-Dist: requests-toolbelt==1.0.0
Requires-Dist: rfc3986==2.0.0
Requires-Dist: rich==14.2.0
Requires-Dist: rsa==4.9.1
Requires-Dist: SecretStorage==3.4.0
Requires-Dist: setuptools==80.9.0
Requires-Dist: six==1.17.0
Requires-Dist: soupsieve==2.8
Requires-Dist: twine==6.2.0
Requires-Dist: typing_extensions==4.15.0
Requires-Dist: tzdata==2025.2
Requires-Dist: uritemplate==4.1.1
Requires-Dist: urllib3==2.4.0
Requires-Dist: watchdog==6.0.0
Requires-Dist: wcwidth==0.2.13
Requires-Dist: wheel==0.45.1
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# MuffinBite

## What MuffinBite Is (Authoritative)

MuffinBite is a **Python-based interactive CLI tool** for sending **personalized bulk emails** using predefined campaigns and **explicit, user-triggered execution**.

MuffinBite sends emails **only when a user runs a command in the CLI**.  
It does **not** run background jobs, scheduled tasks, queues, or analytics services.

If a feature or command is not explicitly documented in this file, it does not exist in the current version of MuffinBite.

## Key Characteristics

- Interactive CLI (not a background daemon)
- Immediate execution only
- Campaign-based email organization
- Gmail API and SMTP provider support
- Local, file-based configuration and data

## Platform Support & Compatibility

MuffinBite is implemented entirely in Python and can be installed on **Linux, Windows, and macOS**.

However, **v0.1.x is optimized and tested primarily on Linux**.  
Some behaviors differ across operating systems due to shell, filesystem, and process model differences.

| Platform | Support Level |
|--------|--------------|
| Linux | Fully supported (primary development platform) |
| macOS | Partially supported |
| Windows | Partially supported |

## Current Capabilities (Implemented)

The following list describes the **current, implemented capabilities** of MuffinBite.  
No functionality exists beyond what is listed here.

- Send bulk emails using the Gmail API
- Send bulk emails using SMTP providers (Brevo, Mailgun, Postmark, etc.)
- Campaign management (create, list, show, delete)
- Send HTML emails with embedded images (base64 supported)
- Personalize email content using CSV or Excel data files
- Variable substitution in subject lines and email bodies
- Attach unlimited files of any type
- Add a global HTML email signature (enable/disable)
- Configure a fixed time delay between consecutive emails
- Test mode for validating campaigns before real sends
- Real-time directory watching for Attachments and DataFiles **(Linux-only in v0.1.x)**
- Log successful and failed email attempts to CSV files
- Detailed error logging when debug mode is enabled
- Full configuration via CLI commands

## Shell Commands

Shell commands can be executed from within the MuffinBite CLI using the `!<command>` prefix.

These commands are executed using the **system shell**, and behavior depends on the operating system:

- Linux / macOS: bash or zsh
- Windows: cmd.exe or PowerShell

Shell command syntax is **OS-specific**.

Examples:
- Linux/macOS: `!ls`, `!clear`
- Windows: `!dir`, `!cls`

## Experimental & Linux-First Features (v0.1.x)

The following behaviors are **experimental and Linux-first** in the current v0.1.x series:

- Automatic session refresh using file system watchers
- Automatic CLI restart after `build` and `config` commands

These features rely on Linux-specific process and filesystem behavior and may behave differently or be unavailable on Windows and macOS.

They are expected to be **removed or redesigned in v0.2.0**, as MuffinBite moves toward a stateless and fully cross-platform CLI architecture.

## MuffinBite CLI Commands (Complete and Exclusive)

The commands listed below are the **only commands supported by MuffinBite**.  
Any other commands mentioned elsewhere are **incorrect**.

### `bite`
Enter the muffinbite CLI
```
~/Documents/all_codes/tryMuffinBite$ bite
```

### `build`
Initializes the working directory structure required by MuffinBite.
```
bite> build
```

### `camp`
Campaign management commands.
```
bite> camp --create
bite> camp --show <campaign_name>
bite> camp --delete <campaign_name>
bite> camp --list
```

### `send`
Send emails for the active campaign.
```
bite> send --test # send emails using test data
bite> send --real # send emails using real data
```
Emails are sent immediately when this command is executed.

### `config`
Configure MuffinBite settings.
```
bite> config --user-name <name>
bite> config --user-email <email>
bite> config --service-provider-name <provider>
bite> config --service-provider-server <server_address>
bite> config --service-provider-login <login>
bite> config --service-provider-port <port>
bite> config --signature <html>
bite> config --signature-on
bite> config --signature-off
bite> config --time-delay <seconds>
bite> config --show
bite> config --debug True|False
```
### `reset`

Deletes the configuration file.
```
bite> reset
```
### `help`

Shows all available commands and their usage.
```
bite> help
```
### `exit`

Exit the MuffinBite CLI.
```
bite> exit
```
## Explicitly Not Supported

The following features are intentionally not supported:

- Scheduled or delayed execution at a specific date or time
- Background queues or worker processes
- Email analytics dashboards or statistics
- Command aliases not listed in this README
- REST APIs or web dashboards

## Folder Structure
```
repo_root/
├── muffinbite/
│ ├── commands/
│ │ ├── build.py
│ │ ├── campaign.py
│ │ ├── configure.py
│ │ ├── quit.py
│ │ ├── reset_config.py
│ │ └── send.py
│ ├── esp/
│ │ ├── google_esp.py
│ │ └── smtp_esp.py
│ ├── management/
│ │ ├── cli.py
│ │ ├── session_watcher.py
│ │ └── settings.py
│ ├── sender/
│ │ └── sender.py
│ └── utils/
│ ├── abstracts.py
│ ├── helpers.py
│ └── hybridcompleter.py
├── LICENSE
├── MANIFEST.in
├── README.md
├── requirements.txt
└── setup.py
```

## Setup Instructions
### 1. Clone the repository
```
git clone https://github.com/Shivansh-varshney/MuffinBite
```
### 2. Install the project in a virtual environment
```
pip install /path/to/muffinbite/
```
### 3. Enter the MuffinBite CLI
```
bite
```
### 4. First-time setup
```
bite> build
bite> help
```
> Place Google Gmail API credentials in a `credentials.json` file in the working directory.  
On first use, a browser window will open to complete authentication and generate `token.json`.

## License

> MIT License
