Sending Email with the Python SDK

The official leadpush package provides synchronous and asynchronous clients for the Leadpush API. Use this guide when a Python backend needs to send password resets, verification codes, receipts, account alerts, or other application-triggered email.

Before you start

Make sure you have:

• Python 3.10 or newer
• a Leadpush API key for the correct workspace
• a verified sending domain and sender address
• workspace delivery set to Normal when you are ready to deliver real email

Create and copy an API key from Workspace Settings → Developer Keys. The Email API uses this bearer API key, not an SMTP username and password. See API Keys for the complete dashboard workflow.

Install the SDK

Install the latest stable package from PyPI:

pip install leadpush

The package uses httpx for HTTP transport and includes type information for supported editors and type checkers.

Configure the API key

Store the key in an environment variable or secret manager. Never commit it to source control or expose it in browser code.

LEADPUSH_API_KEY=your_workspace_api_key

Send with the synchronous client

Use Leadpush in synchronous applications and workers. The context manager closes the underlying HTTP client after the request finishes.

import os

from leadpush import Leadpush

with Leadpush(os.environ["LEADPUSH_API_KEY"]) as client:
    send = client.emails.send(
        from_address="alerts@example.com",
        to=["customer@example.com"],
        subject="Your verification code",
        html="<p>Your code is 482910</p>",
        text="Your code is 482910",
        reply_to="support@example.com",
        headers={"X-Correlation-ID": "verification-482910"},
    )

    print(send.accepted)
    print(send.message_count)
    print(send.messages[0].uuid)

Replace alerts@example.com with a verified sender from the API key's workspace. Provide html, text, or both, and include at least one recipient across to and bcc.

Send with the asynchronous client

Use AsyncLeadpush when the application already runs an asynchronous event loop.

import asyncio
import os

from leadpush import AsyncLeadpush


async def main() -> None:
    async with AsyncLeadpush(os.environ["LEADPUSH_API_KEY"]) as client:
        send = await client.emails.send(
            from_address="alerts@example.com",
            to=["customer@example.com"],
            subject="Your verification code",
            html="<p>Your code is 482910</p>",
            text="Your code is 482910",
        )

        print(send.messages[0].uuid)


asyncio.run(main())

The synchronous and asynchronous clients expose the same resources. Async network operations require await, while pagination helpers use async for.

Understand the response

A successful send request means Leadpush accepted and queued the message; it does not guarantee final delivery.

• accepted confirms that the request was accepted.
• message_count reports how many unique recipient messages were created.
• messages contains the tracked message UUID for each recipient.

Store the returned UUIDs when your application needs to connect a send with delivery troubleshooting or support activity. See the Send Email API reference for request fields, recipient normalization, response data, and queue behavior.

Troubleshooting

Related reading

• Leadpush SDK directory
• Email API vs SMTP Relay
• API Authorization
• Send Email API
• Python SDK source