Email API for Python Developers: Handle Exceptions and Worker Boundaries

TL;DR

• Prefer durable business records over in-process sends: create a notification record before calling the provider so recovery has a stable starting point independent of a single Python process.
• Keep the SDK wrapper minimal and retry inputs immutable: validate and hand plain message data to a small provider adapter, and record immutable operation identity and content for safe retries.
• Verify behavior with controlled tests and observable state: exercise success, documented API exceptions and interrupted requests, and ensure each produces the right local state and inspectable evidence for support.

Put email behind a durable application boundary

Python applications send email from many places: web requests, scheduled scripts, task queues and data pipelines. The language does not determine whether that work is durable. A script can finish after a successful send but before recording it; a task can be delivered twice; a web process can terminate while the network outcome remains unknown.

Create a notification record before the external operation. Include the business event, recipient, template version and intended operation identity. A worker can claim that record and update it with provider evidence. This gives recovery a stable starting point instead of relying on the memory of a single Python process.

Keep the provider adapter small. It should accept validated message data and return or raise a result that your worker can classify. Business authorization, template selection and permission checks belong outside the low-level SDK wrapper.

Read the Python contract, not a JavaScript example

The SendDart Python SDK's documented behavior differs from the Node.js SDK: successful methods return parsed response data, while non-success API responses raise SendDartError. Do not copy a JavaScript data/error branching pattern into Python and assume it represents the same interface. SendDart Python SDK.

Handle documented API exceptions using their structured attributes. Preserve a machine-readable reason and any original message identity needed for recovery. A friendly exception message is useful for diagnostics but should not become the sole condition that decides whether to retry.

Also distinguish transport failure from application validation failure. A missing required template variable is not fixed by waiting thirty seconds. A connection interruption may require reconciliation because the service could have accepted the request before the connection broke. Neither case should disappear into a broad exception handler that simply returns False.

Configure credentials once per execution context

Keep credentials in server-side configuration and avoid writing them into task arguments, logs or saved payloads. If workers run for a long time, define how credential rotation reaches them. A new environment value on one web process does not automatically update a separate task fleet.

The documented Python SDK exposes module-level configuration. Be deliberate about that model in multi-tenant or multi-account code. Changing a global credential concurrently for different customers can mix request context if the application is not designed carefully. Use a controlled adapter and the actual SDK contract; do not invent an unsupported per-request client interface.

For separate customer credentials, consider process isolation or another supported configuration strategy after reviewing the implementation. The important requirement is that one job cannot accidentally send using another customer's account. Test the boundary rather than relying on the order you expect concurrent tasks to run.

Do not confuse concurrency with durability

A thread pool can overlap blocking network calls, but it is not a persistent queue. Python's concurrent.futures API manages callable execution within an execution context; it does not turn a notification into a durable business record. Python executor documentation.

Use bounded concurrency when processing a batch. Preserve the identity and result of every item rather than treating one exception as failure of the entire batch. A partially completed workload needs reconciliation, not a fresh loop over every original recipient.

If an asynchronous web framework calls a synchronous SDK, consider how the blocking work affects request handling. A background worker often provides a clearer boundary for slow external operations. If you offload to threads, keep the lifetime and shutdown behavior explicit; a background thread alone does not guarantee completion after the host ends a request.

Design retry inputs as immutable data

The same intended notification should retain its original operation key and content during recovery. If a template changes between attempts, decide whether the existing job uses its saved version or becomes a new explicitly authorized notification. Silently rendering current content under an old operation identity makes evidence difficult to interpret.

For supported SendDart send operations, use the documented idempotency option. Do not assume that passing such an option to every resource makes every operation idempotent. The SDK documentation identifies which endpoints honor the recovery contract.

Store retry count, next eligible time and the reason for retry separately from the message's business status. A job can be delayed by capacity limits without the underlying purchase or account event failing. Keeping those concepts separate produces better user-facing messages and clearer operational dashboards.

Related reading: Scheduled Email Delivery: Store the Time, Content and Cancellation State.

Test failures with a controlled transport

Unit tests should exercise an accepted response, a documented API exception and an interrupted request. Assert that each produces the right local state. Include a response carrying partial or uncertain evidence and verify that the worker does not create a replacement operation automatically.

Test serialization too. Task queues often encode arguments before another process reads them. Pass a notification identifier or a constrained immutable payload rather than a live SDK object, open file handle or mutable global configuration. Confirm that the worker can load the required template version after a deployment.

Use controlled addresses for a separate integration canary. Validate sender setup and response correlation without sending to real customers. Do not present mocked exception tests as evidence of provider deliverability; they demonstrate your application's handling of the contract.

Make the Python workflow inspectable

Support should be able to follow a notification from business event to provider attempt and later delivery evidence. Record identifiers and timestamps, while minimizing private body content in general logs. A useful error record explains the class of failure and the next action without exposing a reset token or attachment.

The result is a Python integration that survives ordinary process boundaries. The SDK handles the API request, while your application owns intent, isolation, recovery and evidence. That separation is what makes email behavior predictable as scripts grow into production services.

Related reading: Best Email API: Choose With a Production Acceptance Test.