Skip to content

Advanced Usage

This page covers advanced usage scenarios for the ZeptoMail Python API.

Custom MIME Headers

You can add custom MIME headers to your emails:

from zeptomail import ZeptoMail

client = ZeptoMail("your-api-key-here")

# Define custom MIME headers
mime_headers = {
    "X-Custom-ID": "campaign-123",
    "X-Priority": "1",
    "X-Campaign-Source": "newsletter"
}

# Send email with custom headers
response = client.send_email(
    from_address="sender@example.com",
    from_name="Sender Name",
    to=[client.add_recipient("recipient@example.com", "Recipient Name")],
    subject="Email with Custom Headers",
    html_body="<p>This email has custom MIME headers.</p>",
    mime_headers=mime_headers
)

print(f"Response: {response}")

Tracking Options

Control click and open tracking:

from zeptomail import ZeptoMail

client = ZeptoMail("your-api-key-here")

# Send email with tracking options
response = client.send_email(
    from_address="sender@example.com",
    from_name="Sender Name",
    to=[client.add_recipient("recipient@example.com", "Recipient Name")],
    subject="Email with Tracking Options",
    html_body="<p>This email has custom tracking settings.</p>",
    track_opens=True,   # Track when recipients open the email
    track_clicks=False  # Don't track link clicks
)

print(f"Response: {response}")

Client Reference

The client_reference parameter allows you to add your own identifier to emails:

from zeptomail import ZeptoMail

client = ZeptoMail("your-api-key-here")

# Send email with client reference
response = client.send_email(
    from_address="sender@example.com",
    from_name="Sender Name",
    to=[client.add_recipient("recipient@example.com", "Recipient Name")],
    subject="Email with Client Reference",
    html_body="<p>This email has a client reference.</p>",
    client_reference="order-confirmation-12345"  # Your custom reference
)

print(f"Response: {response}")

Error Handling with Solutions

The ZeptoMail client provides detailed error handling with suggested solutions:

from zeptomail import ZeptoMail, ZeptoMailError

client = ZeptoMail("your-api-key-here")

try:
    response = client.send_email(
        from_address="sender@example.com",
        from_name="Sender Name",
        to=[client.add_recipient("recipient@example.com")],
        subject="",  # Empty subject will cause an error
        html_body="<p>Test email content</p>"
    )
    print(f"Email sent successfully: {response}")
except ZeptoMailError as e:
    print(f"Error sending email: {e}")
    # Output will include the error and a suggested solution:
    # ZeptoMail API Error: Mandatory Field 'subject' was set as Empty Value. 
    # (Code: TM_3201, Sub-Code: GE_102)
    # Details: subject: This field is required
    # Set a non-empty subject for your email.

Working with Bytes Objects

The client automatically handles conversion of bytes to base64:

from zeptomail import ZeptoMail
import base64

client = ZeptoMail("your-api-key-here")

# Read a file as bytes
with open("document.pdf", "rb") as f:
    file_bytes = f.read()

# The client will automatically convert bytes to base64
attachment = client.add_attachment_from_content(
    content=file_bytes,  # Can be bytes or base64 string
    mime_type="application/pdf",
    name="document.pdf"
)

response = client.send_email(
    from_address="sender@example.com",
    from_name="Sender Name",
    to=[client.add_recipient("recipient@example.com", "Recipient Name")],
    subject="Email with Attachment",
    html_body="<p>Please find the attached document.</p>",
    attachments=[attachment]
)

print(f"Response: {response}")