mailscript 0.2.1
A Python library for simplified email sending and receiving with secure credentials management
Requires Python: >=3.7
Keywords: email, smtp, mail, template, html-email

# MailScript

A Python library for simplified email sending and receiving with support for templates, attachments, and more.

## Features

- Send plain text and HTML emails
- Template rendering with Jinja2
- Email address validation
- File attachments
- Support for CC and BCC recipients
- TLS/SSL encryption
- Receive emails via IMAP
- Extract and save email attachments
- Output emails in JSON format

## Installation

```bash
pip install mailscript
```

## Configuration

MailScript provides multiple ways to configure your email credentials:

### Option 1: Direct Configuration

Provide credentials directly to the Mailer or Receiver classes:

```python
from mailscript import Mailer

mailer = Mailer(
    smtp_host="smtp.example.com",
    smtp_port=587,
    smtp_user="your-email@example.com",
    smtp_password="your-password",
    use_tls=True
)
```

### Option 2: Configuration File

Create a configuration file in one of these locations:
- `./config/mailscript_config.py`
- `~/.config/mailscript/config.py` 
- `./mailscript_config.py`

Example configuration file:

```python
# mailscript_config.py
smtp_config = {
    "username": "your-email@example.com",
    "password": "your-password",
    "host": "smtp.example.com",
    "port": 587,
    "use_tls": True
}

imap_config = {
    "username": "your-email@example.com",
    "password": "your-password",
    "host": "imap.example.com",
    "port": 993
}

default_recipient = "recipient@example.com"
```

Then use the credential loader:

```python
from mailscript import Mailer
from mailscript.credentials import get_smtp_config

smtp_config = get_smtp_config()
mailer = Mailer(
    smtp_host=smtp_config["host"],
    smtp_port=smtp_config["port"],
    smtp_user=smtp_config["username"],
    smtp_password=smtp_config["password"],
    use_tls=smtp_config["use_tls"]
)
```

## Quick Start

### Basic Usage

```python
from mailscript import Mailer

# Initialize mailer
mailer = Mailer(
    smtp_host="smtp.example.com", 
    smtp_port=587,
    smtp_user="your-email@example.com",
    smtp_password="your-password",
    use_tls=True
)

# Send a simple email
mailer.send(
    sender="your-email@example.com",
    recipients="recipient@example.com",
    subject="Hello from MailScript",
    body="This is a test email from MailScript."
)
```

### HTML Emails

```python
# Send an HTML email
html_content = """
<!DOCTYPE html>
<html>
<body>
    <h1>Hello from MailScript</h1>
    <p>This is an <b>HTML</b> email!</p>
</body>
</html>
"""

mailer.send(
    sender="your-email@example.com",
    recipients="recipient@example.com",
    subject="HTML Email Test",
    body=html_content,
    is_html=True
)
```

### Template Rendering

```python
from mailscript.templates import TemplateRenderer

# Initialize renderer
renderer = TemplateRenderer()

# Render template from string
template = """
<h1>Hello, {{ name }}!</h1>
<p>Welcome to {{ company }}.</p>
"""

context = {"name": "John", "company": "Example Corp"}
html_content = renderer.render_from_string(template, context)

# Send templated email
mailer.send(
    sender="your-email@example.com",
    recipients="recipient@example.com",
    subject="Welcome Email",
    body=html_content,
    is_html=True
)
```

### Built-in Template Methods

```python
# Send an email using a template string directly
context = {
    "name": "John", 
    "features": ["Templates", "Attachments", "HTML Support"]
}

mailer.send_template(
    sender="your-email@example.com",
    recipients="recipient@example.com",
    subject="Welcome Email",
    template_string="<h1>Welcome, {{ name }}!</h1><ul>{% for feature in features %}<li>{{ feature }}</li>{% endfor %}</ul>",
    context=context,
    is_html=True
)

# Send an email using a template file
mailer.send_template_file(
    sender="your-email@example.com",
    recipients="recipient@example.com",
    subject="Newsletter",
    template_name="newsletter.html",
    template_folder="/path/to/templates",
    context={"name": "John", "month": "June"},
    is_html=True
)
```

### With Attachments

```python
# Send email with attachment
with open("document.pdf", "rb") as f:
    attachments = {"document.pdf": f}
    
    mailer.send(
        sender="your-email@example.com",
        recipients="recipient@example.com",
        subject="Email with attachment",
        body="Please find the attached document.",
        attachments=attachments
    )
```

### Receiving Emails

```python
from mailscript import Receiver

# Initialize receiver
receiver = Receiver(
    imap_host="imap.example.com", 
    imap_port=993,
    username="your-email@example.com", 
    password="your-password"
)

# Connect to the server
receiver.connect()

# Select mailbox
receiver.select_mailbox("INBOX")

# Fetch recent emails
emails = receiver.fetch_emails(
    count=5,                          # Number of recent emails to retrieve
    save_attachments=True,            # Save attachments to disk
    output_dir="./my_attachments"     # Directory to save attachments
)

# Process emails
for email in emails:
    print(f"From: {email['from']}")
    print(f"Subject: {email['subject']}")
    print(f"Date: {email['date']}")
    print(f"Body: {email['body'][:100]}...")  # Print first 100 chars
    
    # Process attachments
    for attachment in email['attachments']:
        print(f"Attachment: {attachment['filename']}")
        print(f"Saved at: {attachment['saved_path']}")
    
    print("---")

# Always logout when done
receiver.logout()
```

## Command Line Usage

### Sending Emails

```bash
# Send a plain text email
python -m mailscript send --host smtp.example.com --port 587 --user user@example.com \
    --from "Sender <sender@example.com>" --to recipient@example.com \
    --subject "Hello" --body "This is a test email"

# Send an HTML email with attachments
python -m mailscript send --host smtp.example.com --port 587 --user user@example.com \
    --from "Sender <sender@example.com>" --to recipient@example.com \
    --subject "Hello" --body-file email.html --html --attach document.pdf image.jpg
```

### Receiving Emails

```bash
# Retrieve 10 recent emails and display them
python -m mailscript receive --host imap.example.com --port 993 --user user@example.com \
    --count 10

# Retrieve emails and save attachments
python -m mailscript receive --host imap.example.com --port 993 --user user@example.com \
    --count 5 --save-attachments --output-dir ./downloads

# Save email data to a JSON file
python -m mailscript receive --host imap.example.com --port 993 --user user@example.com \
    --output-file emails.json
```

## Development

### Version Management

This project uses a central `version.txt` file to manage versioning. When updating the version:

1. Edit the version number in `version.txt`
2. Run the update script to propagate the version to all relevant files:
   ```bash
   python update_version.py
   ```

This script automatically updates:
- `mailscript/__init__.py` - Updates the `__version__` variable
- `docs/index.md` - Updates the "Current Version" text in the documentation

### Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License