postiee 0.1.1
A minimal Python client for the Postmark API
License: MIT
Requires Python: >=3.7
Keywords: postmark, email, api, transactional

# Postiee

A minimal Python client for the Postmark API.

## Installation

```bash
pip install postiee
```

## Quick Start

```python
from postiee 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 Postiee",
    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 Postiee as your Django email backend:

```python
# settings.py
EMAIL_BACKEND = 'postiee.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 postiee 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 postiee 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)