django-email-toolkit 0.1.0

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).

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:

{"email": "[e-mail]", "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

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:

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

2. Run migrations:

python manage.py migrate django_email_toolkit

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

from django_email_toolkit.models import EmailConfig

EmailConfig.objects.create(
    host_user="[e-mail]",
    host_password="your-app-password",
    default_from_email="[e-mail]",
    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:

EMAIL_TOOLKIT_GEMINI_API_KEY = "your-gemini-api-key"

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

# 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

from django_email_toolkit import services

services.send_email(
    {"email": "[e-mail]", "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:

recipients = [
    {"email": "[e-mail]", "name": "Ayesha"},
    {"email": "[e-mail]", "name": "Babar"},
]

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

AI-generated content (Gemini by default)

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:

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

# 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

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

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:

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