Metadata-Version: 2.4
Name: mailerpy
Version: 1.0.0
Summary: Simple SMTP and IMAP email helper for Python beginners
Author: Rabindra Sapkota
License-Expression: MIT
Project-URL: Homepage, https://github.com/Rabindra-Sapkota/mailerpy
Project-URL: Repository, https://github.com/Rabindra-Sapkota/mailerpy
Project-URL: Documentation, https://github.com/Rabindra-Sapkota/mailerpy
Keywords: email,mail,smtp,imap,gmail,attachments
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Internet
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: packaging>=23.0; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Dynamic: license-file

# MailerPy

MailerPy is a beginner-friendly Python library for sending and reading email without needing to understand SMTP, IMAP, MIME, or network internals.

## Installation

```bash
pip install mailerpy
```

## Quick start

```python
from mailerpy import Mailer

mail = Mailer.gmail("me@gmail.com", "your-app-password")
mail.send_mail(
    "friend@gmail.com",
    "Hello",
    "Hello from MailerPy!"
)

messages = mail.read_mail(limit=5)
for message in messages:
    print(message.sender)
    print(message.subject)
```

## Backward compatibility

The old API continues to work:

```python
from mailerpy import Mailer

mailer = Mailer(
    "smtp.gmail.com",
    "587",
    "user@gmail.com",
    "your-app-password"
)

mailer.send_mail(
    ["receiver@gmail.com"],
    "Hello",
    "Hello world",
    mail_cc=["cc@gmail.com"],
    mail_bcc=["bcc@gmail.com"],
    attachments=["report.pdf"],
    file_as_html=True,
)
```

The newer string convenience is also supported:

```python
mailer.send_mail("receiver@gmail.com", "Hello", "Hello world")
```

## Sending email

### One recipient

```python
mail.send_mail("friend@gmail.com", "Hello", "Hello!")
```

### Multiple recipients

```python
mail.send_mail(
    ["friend1@gmail.com", "friend2@gmail.com"],
    "Hello",
    "Hello everyone!"
)
```

### CC and BCC

```python
mail.send_mail(
    "friend@gmail.com",
    "Hello",
    "Hello!",
    mail_cc="manager@gmail.com",
    mail_bcc=["audit@example.com"]
)
```

### Attachments

```python
mail.send_mail(
    "teacher@gmail.com",
    "Assignment",
    "Please find the assignment attached.",
    attachments=["assignment.pdf"]
)
```

### HTML content

```python
html = """
<table>
    <tr><th>Name</th><th>Score</th></tr>
    <tr><td>Ram</td><td>95</td></tr>
</table>
"""

mail.send_mail(
    "teacher@gmail.com",
    "Results",
    html,
    file_as_html=True,
)
```

### Body variables

```python
body = """
Hello {NAME},

Your score is {SCORE}.
"""

mail.send_mail(
    "student@gmail.com",
    "Result",
    body,
    mail_body_args={"NAME": "Ram", "SCORE": 95},
)
```

Missing template keys raise `ValueError`.

## Gmail setup

Gmail users should normally use a Google App Password instead of the regular account password.

1. Turn on 2-Step Verification for the Google account.
2. Open Google App Passwords.
3. Create an app password.
4. Copy the generated password.
5. Use that value in MailerPy.

Google App Passwords generally require 2-Step Verification and may be unavailable for some account types or organization security policies.

```python
from mailerpy import Mailer

mail = Mailer.gmail("your-email@gmail.com", "your-app-password")
```

> Use the generated App Password, not your normal Gmail password.

Official Google documentation: https://support.google.com/accounts/answer/185833

## Reading email

```python
messages = mail.read_mail(limit=10)
for message in messages:
    print(message.sender)
    print(message.subject)
    print(message.body)
```

### Filters

```python
messages = mail.read_mail(sender="teacher@gmail.com")
messages = mail.read_mail(subject="Assignment")
messages = mail.read_mail(unread=True)
messages = mail.read_mail(has_attachment=True)
messages = mail.read_mail(
    sender="teacher@gmail.com",
    subject="Assignment",
    unread=True,
    has_attachment=True,
    limit=5,
)
```

The default behavior is to return the newest email first, up to 10 messages.

### Message object

```python
for message in mail.read_mail(limit=5):
    print(message.sender)
    print(message.to)
    print(message.cc)
    print(message.subject)
    print(message.body)
    print(message.date)
    print(message.unread)
    print(message.has_attachments)
```

## Attachments in received mail

```python
messages = mail.read_mail(limit=1)
message = messages[0]

for attachment in message.attachments:
    print(attachment.name)
    print(attachment.size)
    print(attachment.content_type)
```

Download all attachments:

```python
message.download_attachments("downloads")
```

Download one attachment:

```python
attachment = message.attachments[0]
path = attachment.download("downloads")
print(path)
```

Attachment downloads are explicit and do not happen automatically during `read_mail()`.

## Custom SMTP/IMAP configuration

```python
mail = Mailer(
    "smtp.example.com",
    587,
    "me@example.com",
    "your-app-password",
    imap_host="imap.example.com",
)
```

SMTP handles sending. IMAP handles reading.

## Deprecated arguments

These legacy parameters remain accepted for compatibility, but they emit a deprecation warning:

- `compression`
- `password`

Example:

```python
mail.send_mail("friend@gmail.com", "Hello", "Hi", compression="gzip")
```

This warns and continues to work for now.

## Security

- Do not commit passwords to version control.
- Prefer App Passwords where supported.
- Revoke exposed app passwords when needed.
- Use environment variables in production.

```python
import os
from mailerpy import Mailer

mail = Mailer.gmail(
    os.environ["MAIL_EMAIL"],
    os.environ["MAIL_PASSWORD"],
)
```

## Upgrading from MailerPy 0.1.0

The established constructor and sending API remain supported. Existing list recipients, CC, BCC, attachments, HTML bodies, and body arguments continue to work. MailerPy 1.0.0 adds `read_mail()` and Gmail setup without requiring a migration; `compression` and the send-level `password` argument are retained but deprecated.

## API reference

```python
from mailerpy import Mailer, MailMessage

mail = Mailer.gmail("me@gmail.com", "app-password")
messages = mail.read_mail(limit=10)
for message in messages:
    print(message.sender)
    print(message.subject)
```

Mailer methods:

- `Mailer.gmail(email, password)`
- `Mailer.send_mail(...)`
- `Mailer.read_mail(limit=10, sender=None, subject=None, unread=None, has_attachment=None)`

`MailMessage` attributes:

- `sender`
- `to`
- `cc`
- `subject`
- `body`
- `date`
- `unread`
- `has_attachments`
- `attachments`

`Attachment` attributes:

- `name`
- `size`
- `content_type`

## Notes

- This library intentionally keeps the beginner-facing API simple.
- The public API is designed around `Mailer.send_mail(...)` and `Mailer.read_mail(...)`.
- SMTP and IMAP details are handled internally.

## License

MIT
