Python SDK

The jetemail package is the official Python SDK for JetEmail transactional email (MIT license, Python 3.8+, requests 2.28+). Create a transactional API key in the dashboard: Outbound → Keys → Add API key. Use that key with the SDK.

Installation

pip install jetemail

Package on PyPI: jetemail. Source on GitHub: jetemail/jetemail-python.

Quick start

from jetemail import JetEmail, SendEmailOptions

client = JetEmail(api_key="your-transactional-api-key")

result = client.emails.send(
    SendEmailOptions(
        from_="Your App <hello@yourdomain.com>",
        to="user@example.com",
        subject="Welcome!",
        html="<h1>Welcome!</h1>",
    )
)

print(result["id"])

Use a from_ address on a verified domain (see Getting started).

The sender field is named from_ (with a trailing underscore) because from is a reserved word in Python. It is sent to the API as from.

Creating a client

from jetemail import JetEmail

# API key only
client = JetEmail(api_key="your-transactional-api-key")

# With a custom base URL
client = JetEmail(
    api_key="your-transactional-api-key",
    base_url="https://api.jetemail.com",  # optional, this is the default
)

The client is synchronous (built on requests). Passing an empty API key raises jetemail.ApiKeyIsMissing. JetEmail(...) exposes two services:

Service	Property	Description
Email	`client.emails`	Send a single email
Batch	`client.batch`	Send up to 100 emails in one request

`client.emails.send(options)`

Send a single email. options is a SendEmailOptions dataclass (import it from jetemail).

Field	Required	Description
`from_`	✓	Sender, e.g. `"Name <email@domain.com>"` (sent as `from`)
`to`	✓	Recipient(s), string or list (max 50)
`subject`	✓	Subject line
`html`	*	HTML body (need `html` and/or `text`)
`text`	*	Plain text (need `html` and/or `text`)
`cc`, `bcc`, `reply_to`		Recipients, string or list (max 50 each)
`headers`		Custom headers as `{"X-Header": "value"}`
`attachments`		List of `Attachment` objects (max 40MB total)

from jetemail import JetEmail, SendEmailOptions, Attachment

client = JetEmail(api_key="your-transactional-api-key")

result = client.emails.send(
    SendEmailOptions(
        from_="App <noreply@example.com>",
        to="user@example.com",
        subject="Order Confirmation",
        html="<p>Your order has been confirmed.</p>",
        text="Your order has been confirmed.",
        cc=["manager@example.com"],
        bcc=["archive@example.com"],
        reply_to="support@example.com",
        headers={"X-Custom-Header": "value"},
        attachments=[
            Attachment.from_path("/path/to/receipt.pdf"),
        ],
    )
)

print(result["id"])        # Message ID
print(result["response"])  # Queue confirmation message

Missing required fields (or neither html nor text) raise a ValueError before any request is made.

Responses

Every call returns the API response as a plain dict. Response shape for a single send: {"id": str, "response": str}.

`client.batch.send(emails)`

Send up to 100 emails in one request. emails is a list of SendEmailOptions, each using the same fields as a single send. Returns a dict with summary (total, successful, failed) and results per message.

from jetemail import JetEmail, SendEmailOptions

client = JetEmail(api_key="your-transactional-api-key")

result = client.batch.send([
    SendEmailOptions(
        from_="App <noreply@example.com>",
        to="alice@example.com",
        subject="Hello Alice",
        html="<p>Hi Alice!</p>",
    ),
    SendEmailOptions(
        from_="App <noreply@example.com>",
        to="bob@example.com",
        subject="Hello Bob",
        html="<p>Hi Bob!</p>",
    ),
])

print(result["summary"]["successful"])

for item in result["results"]:
    print(item)

An empty list, more than 100 emails, or an invalid email in the list raises a ValueError (the message includes the index of the offending email).

Attachments

Attachment holds a filename and base64-encoded data. Build one from a file path, from raw content, or directly:

from jetemail import JetEmail, SendEmailOptions, Attachment

result = client.emails.send(
    SendEmailOptions(
        from_="you@example.com",
        to="recipient@example.com",
        subject="Invoice",
        html="<p>Please find your invoice attached.</p>",
        attachments=[
            Attachment.from_path("/path/to/invoice.pdf"),                    # filename defaults to the basename
            Attachment.from_path("/path/to/invoice.pdf", filename="inv.pdf"),  # custom filename
            Attachment.from_content("Hello World", "hello.txt"),              # str or bytes
            Attachment(filename="raw.txt", data="SGVsbG8="),                  # already base64-encoded
        ],
    )
)

Error handling

API and network errors raise JetEmailError, which exposes message, status_code (0 for network failures) and response (the parsed error body, or None). Client-side validation raises a standard ValueError.

from jetemail import JetEmail, SendEmailOptions, JetEmailError

try:
    client.emails.send(SendEmailOptions(...))
except JetEmailError as e:
    print(e.status_code)  # HTTP status code
    print(e.message)      # Error message
    print(e.response)     # Full error response dict

Common status codes: 400 invalid request, 401 bad/missing API key, 500 server error.

Webhook signature verification

The SDK includes a standalone helper for verifying webhook signatures that does not need a client instance. It checks the HMAC-SHA256 signature and rejects events whose timestamp is older than the tolerance (default 300 seconds).

from jetemail import verify_webhook, WebhookSignatureVerificationFailed

try:
    verify_webhook(
        payload=request.body,  # raw request body as bytes
        signature=request.headers["X-Webhook-Signature"],
        timestamp=request.headers["X-Webhook-Timestamp"],
        secret="your-webhook-secret",
        # tolerance=300,  # optional, seconds
    )

    # Signature is valid
except WebhookSignatureVerificationFailed as e:
    # Invalid or expired signature
    return ("Unauthorized", 401)

verify_webhook() returns True on success and raises WebhookSignatureVerificationFailed otherwise. Pass the raw request body as bytes; re-serialised JSON will not match the signature.

For additional examples, see the README on GitHub. REST details: API reference.

​Python SDK

​Installation

​Quick start

​Creating a client

​client.emails.send(options)

​Responses

​client.batch.send(emails)

​Attachments

​Error handling

​Webhook signature verification

Python SDK

Installation

Quick start

Creating a client

`client.emails.send(options)`

Responses

`client.batch.send(emails)`

Attachments

Error handling

Webhook signature verification