Python SDK

Send email with Python

Install the official Parcel Wing Python SDK, configure a server-side API key, and send your first transactional email.

Install the SDK

The official SDK is published as parcelwing.

Terminal

pip install parcelwing

Create a client

Initialize the SDK from a server-side environment variable. Never expose API keys to browser code.

parcelwing_client.py

import os
 
from parcelwing import ParcelWing
 
parcel_wing = ParcelWing(api_key=os.environ["PARCEL_WING_API_KEY"])

Send an email

Use from_ for keyword arguments because from is reserved in Python.

send.py

emails = parcel_wing.emails.send(
    from_="Acme <[email protected]>",
    to="[email protected]",
    subject="Hello from Parcel Wing",
    text="It works.",
)
 
print(emails[0]["id"])

You can also pass a raw API dictionary when you want exact API field names.

send-raw.py

emails = parcel_wing.emails.send({
    "from": "Acme <[email protected]>",
    "to": "[email protected]",
    "subject": "Hello from Parcel Wing",
    "text": "It works.",
})

Templates

Use saved templates and typed parameters for repeatable lifecycle email.

templates.py

emails = parcel_wing.emails.send(
    from_="Acme <[email protected]>",
    to="[email protected]",
    template_alias="welcome_email",
    template_params={
        "first_name": "John",
    },
)

Handle errors

ParcelWingError exposes status, type, code, request ID, and details.

errors.py

from parcelwing import ParcelWingError
 
try:
    parcel_wing.emails.send(
        from_="Acme <[email protected]>",
        to="[email protected]",
        subject="Hello",
        text="Hi there",
    )
except ParcelWingError as error:
    print(error.status, error.type, error.code, error.request_id)
    print(error.details)

Context manager

Use the client as a context manager when you want to close the underlying HTTP connection pool automatically.

with-client.py

from parcelwing import ParcelWing
 
with ParcelWing(api_key=os.environ["PARCEL_WING_API_KEY"]) as parcel_wing:
    emails = parcel_wing.emails.send(
        from_="Acme <[email protected]>",
        to="[email protected]",
        subject="Hello",
        text="It works.",
    )

Framework guides

FastAPI

Use Parcel Wing from a FastAPI application with server-side API key handling.

Django

Use Parcel Wing from a Django application with server-side API key handling.

Flask

Use Parcel Wing from a Flask application with server-side API key handling.

Pyramid

Use Parcel Wing from a Pyramid application with server-side API key handling.

CherryPy

Use Parcel Wing from a CherryPy application with server-side API key handling.

Bottle

Use Parcel Wing from a Bottle application with server-side API key handling.