Metadata-Version: 2.4
Name: django-email-toolkit
Version: 0.1.0
Summary: Drop-in bulk/templated/AI-assisted email automation for any Django project — CC/BCC-safe bulk sending, {placeholder} templates, attachments, and pluggable AI content generation (Gemini built-in).
Author: Raihan Islam
License: MIT
Project-URL: Homepage, https://github.com/your-username/django-email-toolkit
Project-URL: Issues, https://github.com/your-username/django-email-toolkit/issues
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4
Classifier: Framework :: Django :: 5
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: requests>=2.28
Provides-Extra: api
Requires-Dist: djangorestframework>=3.14; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-django; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# django-email-toolkit

Drop-in email automation for **any** Django project — bulk sending that
doesn't spam your CC/BCC inbox, `{placeholder}` templating, attachments,
and AI-generated email copy (Gemini built in, any provider pluggable).

Extracted and genericized from a production EduCRM email-automation
module — nothing in this package references leads, customers, or any
other app-specific model. Recipients are always plain dicts:

```python
{"email": "a@b.com", "name": "Ayesha", "course_name": "IELTS Prep"}
```

That's what makes it installable into a CRM, an e-commerce backend, a
SaaS onboarding flow, or anything else with an email list.

## Install

```bash
pip install django-email-toolkit
# or, with the optional REST API layer:
pip install "django-email-toolkit[api]"
```

## Setup (any Django project)

1. Add to `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    ...,
    "django_email_toolkit",
]
```

2. Run migrations:

```bash
python manage.py migrate django_email_toolkit
```

3. Configure sending (once — via admin, shell, or a data migration):

```python
from django_email_toolkit.models import EmailConfig

EmailConfig.objects.create(
    host_user="you@gmail.com",
    host_password="your-app-password",
    default_from_email="you@gmail.com",
    smtp_host="smtp.gmail.com",
    smtp_port=587,
    send_delay_seconds=2,   # pause between sends in a bulk batch
)
```

4. (Optional) AI content generation — add to `settings.py`:

```python
EMAIL_TOOLKIT_GEMINI_API_KEY = "your-gemini-api-key"
```

5. (Optional) mount the REST API — needs `pip install "django-email-toolkit[api]"`:

```python
# project urls.py
urlpatterns = [
    ...,
    path("api/email/", include("django_email_toolkit.urls")),
]
```

That's the entire integration. No app-specific code to write for basic use.

## Usage — direct from Python (no API layer needed)

### Single email

```python
from django_email_toolkit import services

services.send_email(
    {"email": "ayesha@example.com", "name": "Ayesha", "course_name": "IELTS"},
    subject="Hi {name}, your {course_name} seat is ready",
    message="Hello {name}, ...",
)
```

### Bulk email — the CC/BCC bug this package fixes

A common bug in hand-rolled bulk-email code: CC/BCC gets attached to
*every single recipient's* email, so a 50-person batch drops 50 copies
of the same email into the CC inbox. `send_bulk_email` sends the CC/BCC
address exactly **one** summary email after the whole batch finishes:

```python
recipients = [
    {"email": "a@example.com", "name": "Ayesha"},
    {"email": "b@example.com", "name": "Babar"},
]

result = services.send_bulk_email(
    recipients,
    subject="Hi {name}",
    message="Hello {name}, welcome!",
    cc=["coordinator@example.com"],   # gets ONE summary, not 50 copies
)
print(result.sent_count, result.failed_count, result.errors)
```

### AI-generated content (Gemini by default)

```python
from django_email_toolkit.ai import generate_email_content

draft = generate_email_content(
    topic="New IELTS batch starting, 30% early-bird discount",
    tone="promotional",
    language="English",
    placeholder_keys=["name", "course_name", "link"],
)
# {"subject": "...", "message": "..."} — with {placeholders} intact,
# ready to pass straight into send_email() / send_bulk_email()
```

Swap in a different AI provider without touching call sites:

```python
# settings.py
EMAIL_TOOLKIT_AI_PROVIDER = "myapp.ai.MyOpenAIProvider"
```

```python
# myapp/ai.py
from django_email_toolkit.ai.base import AIEmailProvider

class MyOpenAIProvider(AIEmailProvider):
    def generate(self, topic, *, placeholder_keys=None, tone="...", language="..."):
        ...
        return {"subject": "...", "message": "..."}
```

### Attachments

```python
services.send_email(
    recipient,
    subject="Your invoice",
    message="Please find attached.",
    attachments=[
        {"filename": "invoice.pdf", "content": pdf_bytes, "mimetype": "application/pdf"},
    ],
)
```

### Preflight-checking placeholders before a send

```python
report = services.check_placeholders_for_recipients(subject, message, recipients)
# {"total": 50, "recipients_with_missing": 3, "details": [...]}
```

## Usage — REST API (optional)

With `django_email_toolkit.urls` mounted:

| Endpoint | Method | Purpose |
|---|---|---|
| `/templates/` | GET/POST/PUT/DELETE | CRUD for `EmailTemplate` |
| `/logs/` | GET | Read `EmailLog` history |
| `/send/` | POST | Send to one recipient |
| `/send-bulk/` | POST | Bulk send with CC/BCC-safe summary |
| `/check-placeholders/` | POST | Preflight-check a batch |
| `/ai/generate/` | POST | AI-generate subject/message |

All endpoints require authentication (`IsAuthenticated`) — wire in your
project's own auth (JWT, session, etc.) the normal DRF way.

## Dev backend / testing

The toolkit never hardcodes the SMTP backend — it uses whatever
`EMAIL_BACKEND` your Django project has configured. Point it at the
console or locmem backend for local dev/tests:

```python
EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"
```

## What's intentionally NOT in this package

- No frontend code (the `page.tsx` / React UI this was extracted from is
  project-specific — build your own UI against the REST API above, or
  call `django_email_toolkit.services` directly from your own views).
- No CRM-specific models (Lead, Customer, etc.) — that coupling is what
  made the original code non-reusable, so it was deliberately removed.

## License

MIT
