Python SDK

Send email with FastAPI

Use Parcel Wing from FastAPI endpoints with Pydantic validation and dependency-injected clients.

Install the SDK

The official SDK is published as parcelwing.

Terminal

pip install parcelwing

Endpoint

Create a typed endpoint that validates request bodies and sends a saved template.

main.py

import os
from typing import Annotated
 
from fastapi import Depends, FastAPI, HTTPException
from pydantic import BaseModel, EmailStr
from parcelwing import ParcelWing, ParcelWingError
 
app = FastAPI()
 
class WelcomeRequest(BaseModel):
    email: EmailStr
    first_name: str | None = None
 
def get_parcel_wing() -> ParcelWing:
    return ParcelWing(api_key=os.environ["PARCEL_WING_API_KEY"])
 
@app.post("/send-welcome")
def send_welcome(
    payload: WelcomeRequest,
    parcel_wing: Annotated[ParcelWing, Depends(get_parcel_wing)],
):
    try:
        emails = parcel_wing.emails.send(
            from_="Acme <[email protected]>",
            to=payload.email,
            template_alias="welcome_email",
            template_params={
                "first_name": payload.first_name or "friend",
            },
        )
        return {"id": emails[0]["id"]}
    except ParcelWingError as error:
        raise HTTPException(
            status_code=error.status,
            detail={"code": error.code, "request_id": error.request_id},
        ) from error

Production notes

Keep PARCEL_WING_API_KEY in server-side environment variables.
Validate inputs with Pydantic before sending email.
Return or log request_id from ParcelWingError for debugging.