Send emails with Python

In this quickstart, you'll learn how to send transactional emails from your Python project with Sidemail. You'll set up the SDK, send your first email, and see examples for common use cases like welcome emails, password resets, and scheduled reports.

Before you start

1. Create a Sidemail account → get your API key
2. Add a sending domain → set up your domain for sending

1. Install

pip install sidemail

2. Setup

Initialize the client. The SDK automatically reads SIDEMAIL_API_KEY from your environment variables if you don't provide it explicitly.

Option A: Simple setup

Use this for simple scripts.

from sidemail import Sidemail
import os

# Reads SIDEMAIL_API_KEY from environment variables automatically
# or pass api_key="your-key"
sidemail = Sidemail()

Option B: Shared instance (Module)

For larger applications, create a sidemail_client.py file that exports the configured instance.

# create file -> sidemail_client.py

from sidemail import Sidemail
import os

sidemail = Sidemail(api_key=os.getenv("SIDEMAIL_API_KEY"))

Usage:

from sidemail_client import sidemail

sidemail.send_email(
    # ...
)

3. Send a welcome email

sidemail.send_email(
    toAddress="[email protected]",
    fromAddress="[email protected]",
    fromName="Your App",
    templateName="Welcome",
    templateProps={"firstName": "Alex"},
)

4. Send a password reset email

sidemail.send_email(
    toAddress="[email protected]",
    fromAddress="[email protected]",
    fromName="Your App",
    templateName="Password Reset",
    templateProps={
        "actionUrl": "https://myapp.com/reset/token123",
    },
)

5. Send a weekly report (Cron Task)

Create a standalone script to run via cron.

# scripts/send_weekly_report.py
from sidemail_client import sidemail

def main():
    # In a real app, fetch this from your database
    new_signups = 150
    chart_data = [100, 200, 300, 400, 200, 300, 200, 500]

    sidemail.send_email(
        toAddress="[email protected]",
        fromAddress="[email protected]",
        fromName="My App",
        templateName="Weekly Report",
        templateProps={
            "signups": new_signups,
            "chart": chart_data,
        },
    )

if __name__ == "__main__":
    main()

Run it via cron:

# Run every Monday at 8:00 AM
0 8 * * 1 python3 /path/to/scripts/send_weekly_report.py

6. Send HTML email

You can use f-strings to render HTML directly in your code.

amount = 99
html_content = f"""
  <div>
    <h1>Invoice</h1>
    <p>Amount due: ${amount}</p>
  </div>
"""

sidemail.send_email(
    toAddress="[email protected]",
    fromAddress="[email protected]",
    fromName="Your App",
    subject="Your Invoice",
    html=html_content,
)

7. Send Markdown email

Store your markdown content in a file and load it (learn more).

with open("templates/emails/welcome.md", "r") as f:
    markdown_content = f.read()

# Subject and sender are defined in the markdown frontmatter
sidemail.send_email(
    toAddress="[email protected]",
    markdown=markdown_content,
    templateProps={
        "name": "John",
        "link": "https://example.com",
    },
)

8. Send plain text email

sidemail.send_email(
    toAddress="[email protected]",
    fromAddress="[email protected]",
    fromName="Your App",
    subject="Hello",
    text="Hello! 👋",
)

9. Schedule email

Send email later. Set scheduledAt to an ISO date string.

import datetime

# Schedule for 1 hour from now
scheduled_at = (datetime.datetime.utcnow() + datetime.timedelta(hours=1)).isoformat() + "Z"

sidemail.send_email(
    toAddress="[email protected]",
    fromAddress="[email protected]",
    fromName="Your App",
    templateName="Welcome",
    templateProps={"firstName": "Alex"},
    scheduledAt=scheduled_at,
)

10. Send with attachment

Use the Sidemail.file_to_attachment helper to attach files.

from sidemail import Sidemail

with open("invoice.pdf", "rb") as f:
    pdf_data = f.read()

attachment = Sidemail.file_to_attachment("invoice.pdf", pdf_data)

sidemail.send_email(
    toAddress="[email protected]",
    fromAddress="[email protected]",
    fromName="Your App",
    subject="Your invoice",
    text="See attached.",
    attachments=[attachment],
)

11. Handle errors

from sidemail import SidemailError

try:
    sidemail.send_email(
        # ...
    )
except SidemailError as e:
    # Log error to file or monitoring system
    print(f"Sidemail error: {e.message}")