​
Prerequisites

Before getting started, you’ll need to:

  1. Authorize your sending domain
  2. Create and retrieve your SendLayer API key

​
Installation

Install the SendLayer Python SDK using the command:

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.

ParameterTypeRequiredDescription
tostring or listYesEmail address(es) of the recipient(s). Can be a single email string or a list of dictionaries with ‘email’ and ‘name’ keys
senderstring or dictYesEmail address of the sender. Can be a single email string or a dictionary with ‘email’ and ‘name’ keys
subjectstringYesSubject line of the email
textstringNoPlain text version of the email content
htmlstringNoHTML version of the email content
cclistNoList of dictionaries containing CC recipient email addresses and names
bcclistNoList of dictionaries containing BCC recipient email addresses and names
reply_tolistNoList of dictionaries containing reply-to email addresses and names
attachmentslistNoList of dictionaries containing file paths and MIME types for attachments
tagslistNoList of strings used to add tags to email messages
headersdictNoDictionary 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 wehbook:

{
   "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.

ParameterTypeRequiredDescription
urlstringYesThe webhook endpoint URL where events will be sent
eventstringYesThe type of event to listen for. Options: bounce, click, open, unsubscribe, complaint, delivery
webhook_idintegerYesUnique 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.

ParameterTypeRequiredDescription
start_datedatetimeNoStart date for filtering events
end_datedatetimeNoEnd date for filtering events
eventstringNoFilter the API request by the type of event. Supported events include: accepted, rejected, delivered, opened, clicked, unsubscribed, complained, failed
message_idstringNoFilter by the email MessageId
start_fromintegerNoSpecify a starting number for the email filter
retrieve_countintegerNoThis 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.