Skip to content

About

Official Python client for the zaSend transactional email API

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

zasend

License: MIT Python

Official Python client for the zaSend transactional email API.

zaSend is a developer-focused email delivery service for sending product, auth, billing, notification, and lifecycle emails from your application. This package is a small wrapper around the zaSend REST API for Python apps, Django, Flask, FastAPI, background jobs, and scripts.

Use it to:

  • Send transactional email from verified domains
  • Send template-based email with variables
  • Check message status and events
  • Manage suppressions, webhooks, templates, and domains
  • Verify zaSend webhook signatures

The client stays close to the raw API. It has no heavy framework dependencies and uses requests.

Install

pip install zasend

Quick Start

import os

from zasend import ZaSend

client = ZaSend(api_key=os.environ["ZASEND_API_KEY"])

result = client.send_email(
    from_email="zaSend <noreply@zasend.com>",
    to="user@example.com",
    subject="Welcome",
    text="Thanks for signing up.",
)

print(result["message_id"])

Which key do I need?

Create API keys on the API keys page of the dashboard. Each key has an access level and can be limited to one domain:

Access Use it for
Sending only Apps that only send: send_email, send_batch, get_email, get_rate_limits
Agent Sending plus reading received email (list_inbound_messages, get_inbound_message)
Full access Everything, including domains, templates, webhooks, SMTP passwords and API keys
Custom Pick permissions: send, status, inbound, smtp, templates, suppressions, webhooks, domains

If a key lacks a permission the call raises APIError with status_code 403 and missing_permission (for example "inbound"). SMTP passwords (smtp_live_...) are for SMTP apps and don't work with this SDK; older domain keys (dsk_live_...) can still send.

Send HTML Email

client.send_email(
    from_email="Acme <noreply@acme.com>",
    to="customer@example.com",
    subject="Your receipt",
    html="<h1>Thanks for your order</h1><p>Your receipt is attached.</p>",
    text="Thanks for your order. Your receipt is attached.",
)

Send to Multiple Recipients

client.send_email(
    from_email="Acme <noreply@acme.com>",
    to=["one@example.com", "two@example.com"],
    subject="Product update",
    text="A new update is available.",
)

zaSend returns one queued message per to recipient. Suppressed recipients reject the whole request so you can fix the list before sending.

Batch Send

Up to 100 different emails in one call. A partial failure is not an exception: check failed and each result's status.

result = client.send_batch([
    {"from_email": "noreply@yourdomain.com", "to": "ann@example.com", "template": "welcome", "variables": {"name": "Ann"}},
    {"from_email": "noreply@yourdomain.com", "to": "bob@example.com", "subject": "Receipt", "text": "Thanks, Bob"},
])
print(result["queued"], result["failed"], result["results"])

Template Send

client.send_template_email(
    from_email="Acme <noreply@acme.com>",
    to="customer@example.com",
    template="welcome",
    variables={"name": "Ada"},
)

Django Example

# settings.py
import os
ZASEND_API_KEY = os.environ["ZASEND_API_KEY"]

# anywhere in your app
from django.conf import settings
from zasend import ZaSend

zasend = ZaSend(settings.ZASEND_API_KEY)
zasend.send_email(
    from_email="Acme <noreply@acme.com>",
    to=user.email,
    subject="Reset your password",
    text="Use this link to reset your password.",
)

Flask or FastAPI Example

import os
from zasend import ZaSend

zasend = ZaSend(os.environ["ZASEND_API_KEY"])

def send_signup_email(email):
    return zasend.send_template_email(
        from_email="Acme <noreply@acme.com>",
        to=email,
        template="welcome",
        variables={"product": "Acme"},
    )

Webhook Verification

verify_webhook_signature_v2(raw_body, secret, request.headers["X-zaSend-Signature-V2"]) also checks the timestamp and rejects deliveries older than 5 minutes. Prefer it over the older check below.

zaSend signs webhook payloads with HMAC-SHA256. Verify the raw request body before trusting webhook data.

For replay protection, zaSend also sends X-zaSend-Timestamp and X-zaSend-Signature-V2: t=<unix>,v1=<hex>, where v1 is HMAC-SHA256 of "<t>.<raw body>" with the same secret. Reject deliveries older than a few minutes.

from zasend import verify_webhook_signature

ok = verify_webhook_signature(
    request.get_data(),
    "whsec_...",
    request.headers.get("X-zaSend-Signature"),
)

API Methods

Method Description
send_email(**message) Send direct content or a template email
send_template_email(...) Convenience wrapper for template sends
get_email(message_id) Fetch email status and events
get_rate_limits() Fetch daily usage and limits
list_domains() / add_domain(domain) / verify_domain(id) / delete_domain(id) Manage sending domains
list_suppressions(...) / add_suppression(email, ...) / delete_suppression(id) Manage suppression list entries
list_webhooks() / create_webhook(url, events) / delete_webhook(id) Manage signed delivery webhooks
list_templates() / create_template(...) / get_template(id) / update_template(id, ...) / delete_template(id) Manage email templates
list_inbound_messages(limit=, domain=, to=, unread=) / get_inbound_message(id) Read received email
list_smtp_passwords(domain=) / create_smtp_password(domain, name=) / delete_smtp_password(id) SMTP passwords for SMTP apps (the new password is returned once)
list_api_keys() / create_api_key(name, access=, domain=) / revoke_api_key(id) Manage API keys (needs Full access)

Error Handling

import os

from zasend import APIError, RateLimitError, ValidationError, ZaSend

try:
    ZaSend(os.environ["ZASEND_API_KEY"]).send_email(
        from_email="Acme <noreply@acme.com>",
        to="user@example.com",
        subject="Hello",
        text="Body",
    )
except RateLimitError as exc:
    print("Rate limited:", exc)
except ValidationError as exc:
    print("Invalid request:", exc)
except APIError as exc:
    if exc.missing_permission:
        print("This key needs the permission:", exc.missing_permission)
    else:
        print("zaSend API error:", exc)

Links

License

MIT

Attachments

Attachments are enabled per account. Build them from files and send:

import os

from zasend import ZaSend, attachment_from_file

client = ZaSend(os.environ["ZASEND_API_KEY"], timeout=30)
client.send_email(
    idempotency_key="order-1042",  # a retry within 24h returns the first result
    from_email="billing@yourdomain.com",
    to="customer@example.com",
    subject="Your invoice",
    text="Invoice attached.",
    attachments=[attachment_from_file("invoice.pdf")],
)

About

Official Python client for the zaSend transactional email API

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages