Lettermint Python SDK

Installation

pip install lettermint

Quick Start

Sending Emails (Synchronous)

from lettermint import Lettermint
email = Lettermint.email("your-sending-token")
response = (
 email
 .from_("sender@example.com")
 .to("recipient@example.com")
 .subject("Hello from Python!")
 .html("<h1>Welcome!</h1>")
 .text("Welcome!")
 .send()
)
print(response["message_id"])

Sending Emails (Asynchronous)

from lettermint import AsyncLettermint
email = AsyncLettermint.email("your-sending-token")
response = await (
 email
 .from_("sender@example.com")
 .to("recipient@example.com")
 .subject("Hello from Python!")
 .html("<h1>Welcome!</h1>")
 .send()
)
print(response["message_id"])

client = Lettermint(api_token="your-sending-token")
client.email.from_("sender@example.com").to("recipient@example.com").subject("Hello").send()

Email Options

Multiple Recipients

client.email.from_("sender@example.com").to(
 "recipient1@example.com",
 "recipient2@example.com"
).subject("Hello").send()

CC and BCC

client.email.from_("sender@example.com").to("recipient@example.com").cc(
 "cc1@example.com",
 "cc2@example.com"
).bcc("bcc@example.com").subject("Hello").send()

Reply-To

client.email.from_("sender@example.com").to("recipient@example.com").reply_to(
 "reply@example.com"
).subject("Hello").send()

RFC 5322 Addresses

client.email.from_("John Doe <john@example.com>").to(
 "Jane Doe <jane@example.com>"
).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_("sender@example.com").to("recipient@example.com").subject(
 "Your Document"
).attach("document.pdf", content).send()
# Inline attachment (for embedding in HTML)
client.email.from_("sender@example.com").to("recipient@example.com").subject(
 "Welcome"
).html('<img src="cid:logo@example.com">').attach(
 "logo.png", logo_content, "logo@example.com"
).send()

Custom Headers

client.email.from_("sender@example.com").to("recipient@example.com").subject(
 "Hello"
).headers({"X-Custom-Header": "value"}).send()

Metadata and Tags

client.email.from_("sender@example.com").to("recipient@example.com").subject(
 "Hello"
).metadata({"campaign_id": "123", "user_id": "456"}).tag("welcome-campaign").send()

Routing

client.email.from_("sender@example.com").to("recipient@example.com").subject(
 "Hello"
).route("my-route").send()

Idempotency Key

client.email.from_("sender@example.com").to("recipient@example.com").subject(
 "Hello"
).idempotency_key("unique-request-id").send()

Batch Sending

email = Lettermint.email("your-sending-token")
response = email.send_batch([
 {
 "from": "sender@example.com",
 "to": ["recipient@example.com"],
 "subject": "Hello from Python!",
 "text": "This is a batch email.",
 }
])

email.ping()
await AsyncLettermint.email("your-sending-token").ping()

Team API

from lettermint import Lettermint
api = Lettermint.api("your-api-token")
domains = api.domains.list({"page[size]": "10"})
team = api.team.retrieve()
message_html = api.messages.html("message-id")
pong = api.ping()

from lettermint import AsyncLettermint
api = AsyncLettermint.api("your-api-token")
domains = await api.domains.list({"page[size]": "10"})
message_html = await api.messages.html("message-id")

Webhook Verification

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

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

Custom Tolerance

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-sending-token")
try:
 response = client.email.from_("sender@example.com").to("recipient@example.com").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-sending-token",
 base_url="https://custom.api.com/v1",
)

Custom Timeout

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

Context Manager

# Sync
with Lettermint(api_token="your-sending-token") as client:
 client.email.from_("sender@example.com").to("recipient@example.com").send()
# Async
async with AsyncLettermint(api_token="your-sending-token") as client:
 await client.email.from_("sender@example.com").to("recipient@example.com").send()

Type Hints

Requirements

License