Metadata-Version: 2.4
Name: postiee
Version: 0.1.0
Summary: A minimal Python client for the Postmark API
Author-email: Nomadic Influence <support@nomadicinfluence.com>
License: MIT
Project-URL: Homepage, https://github.com/roddy-devs/postie
Project-URL: Repository, https://github.com/roddy-devs/postie
Project-URL: Issues, https://github.com/roddy-devs/postie/issues
Keywords: postmark,email,api,transactional
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# Postie

A minimal Python client for the Postmark API.

## Installation

```bash
pip install postie
```

## Quick Start

```python
from postie import PostieClient

# Initialize client
client = PostieClient(server_token="your-postmark-server-token")

# Send a simple email
response = client.send_email(
    from_email="support@nomadicinfluence.com",
    to="user@example.com",
    subject="Hello from Postie",
    html_body="<h1>Hello!</h1><p>This is a test email.</p>",
    text_body="Hello! This is a test email."
)

print(response)
```

## Features

- ✅ Send single emails
- ✅ Send batch emails (up to 500)
- ✅ Send template-based emails
- ✅ HTML and plain text support
- ✅ CC, BCC, Reply-To
- ✅ Email tagging and metadata
- ✅ Open and link tracking
- ✅ Type hints
- ✅ Minimal dependencies (only `requests`)

## Usage

### Send Email

```python
client.send_email(
    from_email="support@nomadicinfluence.com",
    to="user@example.com",
    subject="Welcome!",
    html_body="<h1>Welcome to our platform</h1>",
    text_body="Welcome to our platform",
    tag="onboarding",
    track_opens=True
)
```

### Send Batch Emails

```python
emails = [
    {
        "From": "support@nomadicinfluence.com",
        "To": "user1@example.com",
        "Subject": "Hello User 1",
        "HtmlBody": "<p>Hello User 1</p>"
    },
    {
        "From": "support@nomadicinfluence.com",
        "To": "user2@example.com",
        "Subject": "Hello User 2",
        "HtmlBody": "<p>Hello User 2</p>"
    }
]

responses = client.send_batch(emails)
```

### Send Template Email

```python
client.send_template_email(
    from_email="support@nomadicinfluence.com",
    to="user@example.com",
    template_id=123456,
    template_model={
        "name": "John Doe",
        "action_url": "https://example.com/verify"
    }
)
```

## Django Integration

### Option 1: Use Django Email Backend (Recommended)

Configure Postie as your Django email backend:

```python
# settings.py
EMAIL_BACKEND = 'postie.django_backend.PostieEmailBackend'
POSTMARK_SERVER_TOKEN = os.getenv('POSTMARK_SERVER_TOKEN')
DEFAULT_FROM_EMAIL = 'support@nomadicinfluence.com'
```

Then use Django's standard email functions:

```python
from django.core.mail import send_mail, EmailMultiAlternatives

# Simple email
send_mail(
    subject='Welcome!',
    message='Welcome to our platform',
    from_email='support@nomadicinfluence.com',
    recipient_list=['user@example.com'],
)

# HTML email
email = EmailMultiAlternatives(
    subject='Welcome!',
    body='Welcome to our platform',
    from_email='support@nomadicinfluence.com',
    to=['user@example.com'],
)
email.attach_alternative('<h1>Welcome!</h1>', "text/html")
email.send()
```

### Option 2: Use PostieClient Directly

```python
# utils/email.py
from postie import PostieClient
from django.conf import settings

postmark = PostieClient(server_token=settings.POSTMARK_SERVER_TOKEN)

def send_welcome_email(user_email, user_name):
    postmark.send_email(
        from_email="support@nomadicinfluence.com",
        to=user_email,
        subject=f"Welcome {user_name}!",
        html_body=f"<h1>Welcome {user_name}!</h1>",
        text_body=f"Welcome {user_name}!"
    )
```

## Error Handling

```python
from postie import PostieClient, PostieAPIError, PostieError

try:
    client.send_email(...)
except PostieAPIError as e:
    print(f"API Error: {e}")
    print(f"Error Code: {e.error_code}")
    print(f"Status Code: {e.status_code}")
except PostieError as e:
    print(f"Client Error: {e}")
```

## Requirements

- Python 3.7+
- requests

## License

MIT

## Contributing

Contributions welcome! Please open an issue or PR.

## Links

- [Postmark API Documentation](https://postmarkapp.com/developer)
- [GitHub Repository](https://github.com/roddy-devs/postie)
