Send email with Python

Prerequisites

Before getting started, you’ll need to:

Authorize your sending domain
Create and retrieve your SendLayer API key

Installation

Install the SendLayer Python SDK using pip.

pip install sendlayer

Usage

After the installation completes, you’re ready to start integrating the SDK to your code. The SDK includes modules to send emails, manage webhooks and events.

Sending an email

Create a new .py file or edit an existing one. Then import the SendLayer module. Once done, you’ll need to initialize the module with your SendLayer API key.

send_email.py

from sendlayer import SendLayer

# Initialize the email client with your API key
sendlayer = SendLayer("your-api-key")

# Send an email
response = sendlayer.Emails.send(
    to="recipient@example.com",
    sender="sender@example.com",
    subject="Test Email",
    text="This is a test email"
)

Sending HTML emails

To send HTML emails, simply include the html parameter to the send() method.

send_email.py

from sendlayer import SendLayer

# Initialize the email client with your API key
sendlayer = SendLayer("your-api-key")

# Send an email
response = sendlayer.Emails.send(
    to="recipient@example.com",
    sender="sender@example.com",
    subject="Test Email",
    html="<html><body><p>This is a test email sent with the <a href='https://sendlayer.com'>SendLayer</a> API!</p></body></html>"
)

You can include the text parameter to have a plain text and HTML version of your email message

Sending to multiple recipients

You can send emails to multiple recipients including "Cc" and "BCC" email addresses.

send_email.py

from sendlayer import SendLayer

sendlayer = SendLayer(api_key='your-api-key')


# Send to multiple recipients
response = sendlayer.Emails.send(
    to=[
        {'email': 'recipient1@example.com', 'name': 'Recipient 1'},
        {'email': 'recipient2@example.com', 'name': 'Recipient 2'}
    ],
    sender={'email':'sender@example.com', 'name': 'Sender Name'},
    subject='Complex Email',
    html='<p>This is a <strong>test email</strong>!</p>',
    text='This is a test email!',
    cc=[{'email': 'cc@example.com', 'name': 'CC Recipient'}],
    bcc=[{'email': 'bcc@example.com', 'name': 'BCC Recipient'}],
    reply_to=[{'email': 'reply@example.com', 'name': 'Reply To'}],
)

Each recipient field is an array containing the recipient’s name and email as objects.

There are limits to the number of email recipients you can add to a single request. See our rate limiting guide to learn more.

Including attachments

You can include attachments to your email message by adding the attachments parameter to the email payload.

send_email.py

from sendlayer import SendLayer

sendlayer = SendLayer(api_key='your-api-key')


# Send email with attachments
response = sendlayer.Emails.send(
    to=[
        {'email': 'recipient1@example.com', 'name': 'Recipient'},
    ],
    sender={'email': 'sender@example.com', 'name': 'Sender Name'},
    subject='Complex Email',
    html='<p>This is a <strong>test email</strong>!</p>',
    attachments=[{
        'path': 'path/to/file.pdf',
        'type': 'application/pdf',
    }]
)

The maximum email size SendLayer allows is 10MB. This includes both the message as well as attachment files.

Simply replace the path parameter with the path to the attachment file you wish to attach and specify the correct type. SendLayer SDK supports both local and remote file attachments and allows you to add multiple attachment files. See our tutorial to learn more about attaching files to emails.

Email parameters

Below is a table containing the supported parameters for sending emails in Python using SendLayer SDK.

Parameter	Type	Required	Description
`to`	`string` or `list`	Yes	Email address(es) of the recipient(s). Can be a single email string or a list of dictionaries with ‘email’ and ‘name’ keys
`sender`	`string` or `dict`	Yes	Email address of the sender. Can be a single email string or a dictionary with ‘email’ and ‘name’ keys
`subject`	`string`	Yes	Subject line of the email
`text`	`string`	No	Plain text version of the email content
`html`	`string`	No	HTML version of the email content
`cc`	`list`	No	List of dictionaries containing CC recipient email addresses and names
`bcc`	`list`	No	List of dictionaries containing BCC recipient email addresses and names
`reply_to`	`list`	No	List of dictionaries containing reply-to email addresses and names
`attachments`	`list`	No	List of dictionaries containing file paths and MIME types for attachments
`tags`	`list`	No	List of strings used to add tags to email messages
`headers`	`dict`	No	Dictionary with key-value pairs for adding custom email headers

Managing webhooks

With the SendLayer Python SDK, you can create new webhook, view all webhooks you’ve created and also delete a specific webhook.

Creating a new webhook

To create a new webhook, you’ll need to first import the SendLayer module and initialize it with your API key. Then call the Webhooks.create() method and specify the required parameters. This method requires the url and event parameters.

webhooks.py

from sendlayer import SendLayer

sendlayer = SendLayer(api_key='your-api-key')

# Create a webhook
webhook = sendlayer.Webhooks.create(
    url='https://your-domain.com/webhook',
    event='open'
)

The event parameter is constrained to the following options:

bounce
click
open
unsubscribe
complaint
delivery

Example success response for new webhook:

{
   "NewWebhookID": 23718
}

Getting all webhooks

To view all the webhooks you’ve created, use the Webhooks.get() method.

webhooks.py

from sendlayer import SendLayer

sendlayer = SendLayer(api_key='your-api-key')

# Get all webhooks
webhooks = sendlayer.Webhooks.get()

Here is an example response:

{
  "Webhooks": [
    {
      "WebhookID": "23718",
      "CreatedAt": "2025-04-11 09:43:07",
      "UpdatedAt": "2025-04-11 09:43:07", 
      "Status": "Enabled",
      "WebhookURL": "http://example.com/webhook",
      "Event": "delivered",
      "LastResponseCode": "0",
      "LastResponseBody": "",
      "LastResponseAt": "0000-00-00 00:00:00",
      "LastResponseTryCounter": "0"
    }
  ]
}

Deleting a webhook

To delete a specific webhook, use the Webhooks.delete() method. This method accepts one required parameter webhook_id that needs to be a number.

Deleting a webhook cannot be undone. You won’t be able to recover or access your webhook after deleting it.

webhooks.py

from sendlayer import SendLayer

sendlayer = SendLayer(api_key='your-api-key')

# Delete a webhook
webhook_id = 23718
sendlayer.Webhooks.delete(webhook_id)

Webhooks parameters

The table below contains details about the supported parameters in the Webhooks module.

Parameter	Type	Required	Description
`url`	`string`	Yes	The webhook endpoint URL where events will be sent
`event`	`string`	Yes	The type of event to listen for. Options: bounce, click, open, unsubscribe, complaint, delivery
`webhook_id`	`integer`	Yes	Unique identifier for the webhook (used in delete operation)

Retrieving email events

You can view all events connected to your API key.

Getting all events

To get started, import the SendLayer module and initialize it with your API key. Then call the Events.get() method to retrieve all events.

The Events.get() method retrieves the top 5 events in your account if no filter parameter is specified.

events.py

from sendlayer import SendLayer

sendlayer = SendLayer(api_key='your-api-key')

# Get all events
events = sendlayer.Events.get()

Example response

{
  "totalRecords": 5,
  "events": [
    {
      "Event": "delivered",
      "LoggedAt": 1746340896,
      "LogLevel": "info",
      "Message": {
        "Headers": {
          "MessageId": "06e4491f-fc5a-49cb-bc57-xxxxxx",
          "From": [["", "paulie@example.com"]],
          "ReplyTo": [],
          "To": [["", "recipient@example.com"]],
          "Cc": [],
          "Bcc": []
        },
        "Size": 2004,
        "Transport": "api"
      },
      "Recipient": "recipient@example.com",
      "Reason": "Email has been delivered."
    }
  ]
}

Filtering events

The Events.get() method in the SendLayer module accepts some optional parameters. These parameters can be used to filter the API response. Here is an example:

events.py

from sendlayer import SendLayer
from datetime import datetime, timedelta

sendlayer = SendLayer(api_key='your-api-key')

# Filter events for the last 4 hours
events = sendlayer.Events.get(
    start_date=datetime.now() - timedelta(hours=4),
    end_date=datetime.now(),
    event="opened"
)

Events parameters

The table below contains details about the available parameters in the Events module.

Parameter	Type	Required	Description
`start_date`	`datetime`	No	Start date for filtering events
`end_date`	`datetime`	No	End date for filtering events
`event`	`string`	No	Filter the API request by the type of event. Supported events include: `accepted`, `rejected`, `delivered`, `opened`, `clicked`, `unsubscribed`, `complained`, `failed`
`message_id`	`string`	No	Filter by the email `MessageId`
`start_from`	`integer`	No	Specify a starting number for the email filter
`retrieve_count`	`integer`	No	This parameter controls the number of event records that’ll be displayed. It defaults to 5 if none is specified

Error handling

The SDK provides custom exceptions for better error handling. You can import the SendLayerError or SendLayerAPIError modules, then use Python’s try & exception syntax when sending your emails:

from sendlayer import (
    SendLayer,
    SendLayerError,
    SendLayerAPIError,
)

sendlayer = SendLayer('your-api-key')

try:
    response = sendlayer.Emails.send(...)
except SendLayerAPIError as e:
    print(f"API error: {e.status_code} - {e.message}")
except SendLayerError as e:
    print("Error: ", e)

Here is an example error response:

Error: Invalid event name - 'opened' is not a valid event name

More examples

SendLayer Python SDK

View more details and examples on GitHub.

Getting Started

SDKs

Guides

Integrations

Releases

Prerequisites

Installation

Usage

Sending an email

Sending HTML emails

Sending to multiple recipients

Including attachments

Email parameters

Managing webhooks

Creating a new webhook

Getting all webhooks

Deleting a webhook

Webhooks parameters

Retrieving email events

Getting all events

Filtering events

Events parameters

Error handling

More examples

SendLayer Python SDK

​Prerequisites

​Installation

​Usage

​Sending an email

​Sending HTML emails

​Sending to multiple recipients

​Including attachments

​Email parameters

​Managing webhooks

​Creating a new webhook

​Getting all webhooks

​Deleting a webhook

​Webhooks parameters

​Retrieving email events

​Getting all events

​Filtering events

​Events parameters

​Error handling

​More examples

SendLayer Python SDK

Prerequisites

Installation

Usage

Sending an email

Sending HTML emails

Sending to multiple recipients

Including attachments

Email parameters

Managing webhooks

Creating a new webhook

Getting all webhooks

Deleting a webhook

Webhooks parameters

Retrieving email events

Getting all events

Filtering events

Events parameters

Error handling

More examples