lettermint 1.0.2

Official Lettermint Python SDK

Lettermint Python SDK

Official Python SDK for the Lettermint email API.

Installation

pip install lettermint

Quick Start

Sending Emails (Synchronous)

from lettermint import Lettermint

client = Lettermint(api_token="your-api-token")

response = (
    client.email
    .from_("[e-mail]")
    .to("[e-mail]")
    .subject("Hello from Python!")
    .html("<h1>Welcome!</h1>")
    .text("Welcome!")
    .send()
)

print(response["message_id"])

Sending Emails (Asynchronous)

from lettermint import AsyncLettermint

async with AsyncLettermint(api_token="your-api-token") as client:
    response = await (
        client.email
        .from_("[e-mail]")
        .to("[e-mail]")
        .subject("Hello from Python!")
        .html("<h1>Welcome!</h1>")
        .send()
    )
    print(response["message_id"])

Email Options

Multiple Recipients

client.email.from_("[e-mail]").to(
    "[e-mail]",
    "[e-mail]"
).subject("Hello").send()

CC and BCC

client.email.from_("[e-mail]").to("[e-mail]").cc(
    "[e-mail]",
    "[e-mail]"
).bcc("[e-mail]").subject("Hello").send()

Reply-To

client.email.from_("[e-mail]").to("[e-mail]").reply_to(
    "[e-mail]"
).subject("Hello").send()

RFC 5322 Addresses

client.email.from_("John Doe <[e-mail]>").to(
    "Jane Doe <[e-mail]>"
).subject("Hello").send()

Attachments

import base64

# Read and encode your file
with open("document.pdf", "rb") as f:
    content = base64.b64encode(f.read()).decode()

# Regular attachment
client.email.from_("[e-mail]").to("[e-mail]").subject(
    "Your Document"
).attach("document.pdf", content).send()

# Inline attachment (for embedding in HTML)
client.email.from_("[e-mail]").to("[e-mail]").subject(
    "Welcome"
).html('<img src="cid:[e-mail]">').attach(
    "logo.png", logo_content, "[e-mail]"
).send()

Custom Headers

client.email.from_("[e-mail]").to("[e-mail]").subject(
    "Hello"
).headers({"X-Custom-Header": "value"}).send()

Metadata and Tags

client.email.from_("[e-mail]").to("[e-mail]").subject(
    "Hello"
).metadata({"campaign_id": "123", "user_id": "456"}).tag("welcome-campaign").send()

Routing

client.email.from_("[e-mail]").to("[e-mail]").subject(
    "Hello"
).route("my-route").send()

Idempotency Key

Prevent duplicate sends when retrying failed requests:

client.email.from_("[e-mail]").to("[e-mail]").subject(
    "Hello"
).idempotency_key("unique-request-id").send()

Webhook Verification

Verify webhook signatures to ensure authenticity:

from lettermint import Webhook

# Create a webhook verifier
webhook = Webhook(secret="your-webhook-secret")

# Verify using headers (recommended)
payload = webhook.verify_headers(request.headers, request.body)

# Or verify using the signature directly
payload = webhook.verify(
    payload=request.body,
    signature=request.headers["X-Lettermint-Signature"],
)

print(payload["event"])

Static Method

For one-off verification:

from lettermint import Webhook

payload = Webhook.verify_signature(
    payload=request.body,
    signature=request.headers["X-Lettermint-Signature"],
    secret="your-webhook-secret",
)

Custom Tolerance

Adjust the timestamp tolerance (default: 300 seconds):

webhook = Webhook(secret="your-webhook-secret", tolerance=600)

Error Handling

from lettermint import Lettermint
from lettermint.exceptions import (
    ValidationError,
    ClientError,
    HttpRequestError,
    TimeoutError,
)

client = Lettermint(api_token="your-api-token")

try:
    response = client.email.from_("[e-mail]").to("[e-mail]").subject(
        "Hello"
    ).send()
except ValidationError as e:
    # 422 errors (e.g., daily limit exceeded)
    print(f"Validation error: {e.error_type}")
    print(f"Response: {e.response_body}")
except ClientError as e:
    # 400 errors
    print(f"Client error: {e}")
except TimeoutError as e:
    # Request timeout
    print(f"Timeout: {e}")
except HttpRequestError as e:
    # Other HTTP errors
    print(f"HTTP error {e.status_code}: {e}")

Webhook Errors

from lettermint import Webhook
from lettermint.exceptions import (
    InvalidSignatureError,
    TimestampToleranceError,
    JsonDecodeError,
    WebhookVerificationError,
)

try:
    payload = webhook.verify_headers(headers, body)
except InvalidSignatureError:
    print("Invalid signature - request may be forged")
except TimestampToleranceError:
    print("Timestamp too old - possible replay attack")
except JsonDecodeError:
    print("Invalid JSON in payload")
except WebhookVerificationError as e:
    print(f"Verification failed: {e}")

Configuration

Custom Base URL

client = Lettermint(
    api_token="your-api-token",
    base_url="https://custom.api.com/v1",
)

Custom Timeout

client = Lettermint(
    api_token="your-api-token",
    timeout=60.0,  # 60 seconds
)

Context Manager

Both sync and async clients support context managers for proper resource cleanup:

# Sync
with Lettermint(api_token="your-api-token") as client:
    client.email.from_("[e-mail]").to("[e-mail]").send()

# Async
async with AsyncLettermint(api_token="your-api-token") as client:
    await client.email.from_("[e-mail]").to("[e-mail]").send()

Type Hints

This SDK is fully typed with py.typed marker. You'll get full autocomplete and type checking in your IDE.

Requirements

• Python 3.9+
• httpx

License

MIT