# Send Email
Source: https://developers.sendlayer.com/api-reference/endpoint/email

sendlayer.json POST /email



# Retrieve Events
Source: https://developers.sendlayer.com/api-reference/endpoint/events

sendlayer.json GET /events



# Delete Webhook
Source: https://developers.sendlayer.com/api-reference/endpoint/webhooks/delete

sendlayer.json DELETE /webhooks/{id}



# Get Webhooks
Source: https://developers.sendlayer.com/api-reference/endpoint/webhooks/get

sendlayer.json GET /webhooks



# Create Webhook
Source: https://developers.sendlayer.com/api-reference/endpoint/webhooks/post

sendlayer.json POST /webhooks



# Error Codes
Source: https://developers.sendlayer.com/api-reference/error-codes

List of API errors and their description

### SendLayer API Error Codes

If your API call is unsuccessful, an error code and message will be returned in JSON. Below is a list of the error codes:

| Code | Message                                                                                                                   |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| 1    | Missing SenderAPIKey                                                                                                      |
| 2    | Missing FromName                                                                                                          |
| 3    | Missing FromEmail                                                                                                         |
| 4    | Missing ReplyToName                                                                                                       |
| 5    | Missing ReplyToEmail                                                                                                      |
| 6    | Missing ToName                                                                                                            |
| 7    | Missing ToEmail                                                                                                           |
| 8    | Missing Subject                                                                                                           |
| 9    | Missing ContentType                                                                                                       |
| 10   | Missing HTMLContent                                                                                                       |
| 11   | Missing PlainContent                                                                                                      |
| 12   | Invalid user                                                                                                              |
| 13   | Invalid sender API key                                                                                                    |
| 14   | Recipient email is suppressed                                                                                             |
| 15   | Invalid TemplateID                                                                                                        |
| 16   | Invalid TargetListID                                                                                                      |
| 17   | Email quota reached                                                                                                       |
| 18   | Recipient name or email address is missing                                                                                |
| 19   | Recipient email address is invalid                                                                                        |
| 20   | There is no recipient set for the email **OR** The number of recipients exceeds the allowed recipient email address count |
| 21   | CC name or email address is missing                                                                                       |
| 22   | CC email address is invalid                                                                                               |
| 23   | Invalid from email address format                                                                                         |
| 24   | BCC email addresses must be set as an array                                                                               |
| 25   | BCC name or email address is missing                                                                                      |
| 26   | BCC email address is invalid                                                                                              |
| 27   | The number of BCC email addresses exceed the allowed email address count                                                  |
| 28   | Reply-To email addresses must be set as an array                                                                          |
| 29   | Reply-To name or email address is missing                                                                                 |
| 30   | Reply-To email address is invalid                                                                                         |
| 31   | The number of Reply-To email addresses exceed the allowed email address count                                             |
| 32   | Domain is not activated                                                                                                   |
| 404  | Resource not found                                                                                                        |
| 422  | Invalid request parameters                                                                                                |
| 429  | Too many requests                                                                                                         |

### Example Error Response

```json theme={null}
{
    "Errors": [
        {
            "Code": 13,
            "Message": "Invalid SenderAPIKey"
        }
    ]
}
```


# Introduction
Source: https://developers.sendlayer.com/api-reference/introduction

SendLayer API endpoints

Welcome to the SendLayer API endpoint reference. SendLayer provides access to its API endpoints to allow developers integrate SendLayer into their applications. Here, you'll learn about the available API endpoints and how to interact with each of the endpoints.

## Base URL

SendLayer's API follows **REST** principles. All requests contain the following base URL:

```
https://console.sendlayer.com/api/v1/
```

## Authentication

All API endpoints are authenticated using Bearer tokens. To authenticate, you'll need to add an **Authorization** header with the content of the header being `Bearer <token>`, where token is your SendLayer API key.

To learn how to access your SendLayer API key, check out our tutorial on [managing API keys](https://sendlayer.com/docs/managing-api-keys/).

```
Authorization: 'Bearer <token>'
```


# Rate Limits
Source: https://developers.sendlayer.com/api-reference/rate-limit

SendLayer API rate limits

SendLayer API rate limits are applied to the API key used to make the request.

## Email Sending

SendLayer API limit usage varies depending on your account plan. Below are the available plans and their respective limits.

| SendLayer Plan | Emails/minute | Emails/hour | Emails/day |
| -------------- | ------------- | ----------- | ---------- |
| Trial          | 10            | 25          | 50         |
| Starter        | 50            | 300         | 500        |
| Business       | 120           | 500         | 1000       |
| Growth         | 200           | 1000        | 2500       |

<Note>See our detailed guide to learn more about [SendLayer rate limits](https://sendlayer.com/docs/understanding-sendlayer-rate-limiting/)</Note>

## Email Recipients

When sending emails to multiple recipients, the following limits apply to all users regardless of account type.

* **Send To:** 10 email addresses
* **CC:** 10 email addresses
* **BCC:** 5 email addresses

## Email Size

When sending an email, the maximum file size per email is **10 MB**. This includes both the content and additional email attachments.


# Viewing Recent Changelogs
Source: https://developers.sendlayer.com/changelog

SendLayer API updates

<Update label="March 16, 2026" description="v1.0.0">
  ### Golang SDK

  Major v1 release with a revamped, struct-based request API across Email, Events, and Webhooks.

  #### Summary

  * Revamped email sending to use `SendEmailRequest` instead of positional arguments.
  * Aligned events querying and webhook creation with `GetEventsRequest` and `WebhookCreateRequest`.

  #### Details

  **Email**

  * Added `SendEmailRequest` with `From`, `To`, `Subject`, `Text`, `Html`, `Cc`, `Bcc`, `ReplyTo`, `Attachments`, `Headers`, and `Tags`.
  * Updated `EmailsService.Send` signature to `Send(req *SendEmailRequest) (*EmailResponse, error)`.

  **Events**

  * Added `GetEventsRequest` with `StartDate`, `EndDate`, `Event`, `MessageID`, `StartFrom`, and `RetrieveCount`.
  * Updated `EventsService.Get` signature to `Get(req *GetEventsRequest) (*EventsResponse, error)`.
  * All fields are optional; `nil` means no filters (`GET /events`).

  **Webhooks**

  * Reused `WebhookCreateRequest` as the user-facing create payload.
  * Updated `WebhooksService.Create` signature to `Create(req *WebhookCreateRequest) (*WebhookCreateResponse, error)`.

  #### Breaking Changes

  * `EmailsService.Send` no longer supports the old 12-argument signature.
  * `EventsService.Get` and `WebhooksService.Create` now require struct-based request payloads.
  * Existing integrations must migrate to request structs.

  #### Migration Example

  **Before**

  ```go theme={null}
  func main() {
  	sl := sendlayer.New(os.Getenv("SENDLAYER_API_KEY"))

  	resp, err := sl.Emails.Send(
  		"paulie@example.com",
  		"recipient@example.com",
  		"Test Email",
  		"This is a test email",
  		"",
  		nil, nil, nil,
  		nil, nil, nil,
  	)
  	if err != nil {
  		log.Fatal(err)
  	}

  	fmt.Println("Email sent! Message ID:", resp.MessageID)
  }
  ```

  **After**

  ```go theme={null}
  func main() {
  	sl := sendlayer.New(os.Getenv("SENDLAYER_API_KEY"))

  	resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
  		From:    "paulie@example.com",
  		To:      "recipient@example.com",
  		Subject: "Test Email",
  		Text:    "This is a test email",
  	})
  	if err != nil {
  		log.Fatal(err)
  	}

  	fmt.Println("Email sent! Message ID:", resp.MessageID)
  }
  ```
</Update>

<Update label="January 15, 2026" description="v1.0.0">
  ### MCP Server

  Released a MCP server for AI tools like Cursor and Claude to send emails and manage webhooks/events.
</Update>

<Update label="December 12, 2025" description="v1.0.2">
  ### Node.js SDK

  Fixed TypeScript declarations resolution by pointing `"types"` to `"./dist"`.
</Update>

<Update label="October 9, 2025" description="v1.0.0">
  ### Ruby SDK

  Released a RubyGems client SDK for Ruby developers to integrate with SendLayer's API.
</Update>

<Update label="October 9, 2025" description="v0.1.0">
  ### Go SDK

  Released a client SDK for Golang developers to integrate with SendLayer's API.
</Update>

<Update label="August 28, 2025" description="v1.0.0">
  ### PHP SDK

  Released a client SDK for PHP developers to integrate with SendLayer's API.
</Update>

<Update label="June 26, 2025" description="v1.0.0">
  ### Node.js SDK

  Released a client SDK for JavaScript developers to integrate with SendLayer's API.
</Update>

<Update label="June 26, 2025" description="v1.0.0">
  ### Python SDK

  Released a client SDK for Python developers to integrate the API.
</Update>


# Retrieving Email Events
Source: https://developers.sendlayer.com/guides/get-events

Learn how to retrieve and filter email events using the SendLayer API

## Overview

The SendLayer API allows you to retrieve detailed information about email events such as deliveries, opens, clicks, bounces, and more. This guide shows you how to fetch these events and apply various filters to get the specific data you need.

## Prerequisites

* [Authorize your domain](https://sendlayer.com/docs/authorizing-your-domain/)
* [Create or retrieve your API key](https://sendlayer.com/docs/managing-api-keys/)
* [Install the SendLayer SDK](/quickstart/installation)

## Retrieving All Events

To get started, you can retrieve all events associated with your account. By default, this returns the most recent 5 events.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  const sendlayer = new SendLayer('your-api-key');

  // Get all events (defaults to 5 most recent)
  const events = await sendlayer.Events.get();
  console.log('Total records:', events.totalRecords);
  console.log('Events:', events.events);
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer

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

  # Get all events (defaults to 5 most recent)
  events = sendlayer.Events.get()
  print(f"Total records: {events['totalRecords']}")
  print(f"Events: {events['events']}")
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  // Get all events (defaults to 5 most recent)
  $events = $sendlayer->Events->get();
  ```

  ```ruby Ruby theme={null}
  require 'sendlayer'

  sendlayer = SendLayer::SendLayer.new('your-api-key')

  events = sendlayer.events.get
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  all, err := sl.Events.Get(nil)
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://console.sendlayer.com/api/v1/events \
    --header 'Authorization: Bearer <apiKey>'
  ```
</CodeGroup>

<Warning>Replace `<apiKey>` with your actual SendLayer API key in the request header.</Warning>

### Example Response

When you retrieve events, you'll receive data in this format:

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

## Filtering Events

You can apply various filters to narrow down the events you want to retrieve. This is useful for analyzing specific time periods, event types, or individual emails.

### Filter by Date Range

Retrieve events within a specific time period using Unix timestamps.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  const sendlayer = new SendLayer('your-api-key');

  // Filter events for the last 24 hours
  const startDate = Math.floor((Date.now() - 24 * 60 * 60 * 1000) / 1000); // 24 hours ago
  const endDate = Math.floor(Date.now() / 1000); // current time

  const events = await sendlayer.Events.get({
    startDate: startDate,
    endDate: endDate
  });
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer
  from datetime import datetime, timedelta

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

  # Filter events for the last 24 hours
  start_date = int((datetime.now() - timedelta(hours=24)).timestamp())
  end_date = int(datetime.now().timestamp())

  events = sendlayer.Events.get(
      start_date=start_date,
      end_date=end_date
  )
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  // Filter events for the last 24 hours
  $events = $sendlayer->Events->get([
    'startDate' => time() - 24 * 60 * 60,
    'endDate' => time()
  ]);
  ```

  ```ruby Ruby theme={null}
  sendlayer = SendLayer::SendLayer.new('your-api-key')

  start_date = (Time.now - 24*60*60).to_i
  end_date = Time.now.to_i

  events = sendlayer.events.get(
    start_date: start_date,
    end_date: end_date
  )
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  end := time.Now()
  start := end.Add(-24 * time.Hour)

  events, err := sl.Events.Get(&sendlayer.GetEventsRequest{
    StartDate: &start,
    EndDate:   &end,
  })
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://console.sendlayer.com/api/v1/events?StartDate=1746254496&EndDate=1746340896' \
    --header 'Authorization: Bearer <apiKey>'
  ```
</CodeGroup>

### Filter by Event Type

You can filter events by type. Here is an example:

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  const sendlayer = new SendLayer('your-api-key');

  // Get only opened events
  const openedEvents = await sendlayer.Events.get({
    event: 'opened'
  });

  // Get only bounced events
  const bouncedEvents = await sendlayer.Events.get({
    event: 'bounced'
  });
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer

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

  # Get only opened events
  opened_events = sendlayer.Events.get(event='opened')

  # Get only bounced events
  bounced_events = sendlayer.Events.get(event='bounced')
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $openedEvents = $sendlayer->Events->get([
    'event' => 'opened'
  ]);

  $bouncedEvents = $sendlayer->Events->get([
    'event' => 'bounced'
  ]);
  ```

  ```ruby Ruby theme={null}
  sendlayer = SendLayer::SendLayer.new('your-api-key')

  opened_events = sendlayer.events.get(event: 'opened')
  bounced_events = sendlayer.events.get(event: 'bounced')
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  opened, err := sl.Events.Get(&sendlayer.GetEventsRequest{
    Event: "opened",
  })
  bounced, err := sl.Events.Get(&sendlayer.GetEventsRequest{
    Event: "bounced",
  })
  ```

  ```bash cURL theme={null}
  # Get opened events
  curl --request GET \
    --url 'https://console.sendlayer.com/api/v1/events?Event=opened' \
    --header 'Authorization: Bearer <apiKey>'

  # Get bounced events
  curl --request GET \
    --url 'https://console.sendlayer.com/api/v1/events?Event=bounced' \
    --header 'Authorization: Bearer <apiKey>'
  ```
</CodeGroup>

Below, we've highlighted the available event types:

* `opened`: Recipient opened the email
* `clicked`: Recipient clicked a link in the email
* `unsubscribed`: Recipient unsubscribed from emails
* `complained`: Recipient marked email as spam
* `delivered`: Email successfully delivered to recipient's inbox
* `failed`: Email failed to deliver and bounced back
* `accepted`: Email was accepted by the recipient's email server. In some cases, this may be seen as `accepted-by-system`
* `rejected`: Email was rejected by the recipient's email server

### Filter by Message ID

Retrieve events for a specific email using its Message ID.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  const sendlayer = new SendLayer('your-api-key');

  // Get events for a specific email
  const messageEvents = await sendlayer.Events.get({
    messageId: '06e4491f-fc5a-49cb-bc57-xxxxxx'
  });
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer

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

  # Get events for a specific email
  message_events = sendlayer.Events.get(
      message_id='06e4491f-fc5a-49cb-bc57-xxxxxx'
  )
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $messageEvents = $sendlayer->Events->get([
    'messageId' => '06e4491f-fc5a-49cb-bc57-xxxxxx'
  ]);
  ```

  ```ruby Ruby theme={null}
  sendlayer = SendLayer::SendLayer.new('your-api-key')

  message_events = sendlayer.events.get(message_id: '06e4491f-fc5a-49cb-bc57-xxxxxx')
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  msgID := "06e4491f-fc5a-49cb-bc57-xxxxxx"
  events, err := sl.Events.Get(&sendlayer.GetEventsRequest{
    MessageID: msgID,
  })
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://console.sendlayer.com/api/v1/events?MessageID=06e4491f-fc5a-49cb-bc57-xxxxxx' \
    --header 'Authorization: Bearer <apiKey>'
  ```
</CodeGroup>

### Pagination and Result Limits

Control how many events to retrieve and implement pagination.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  const sendlayer = new SendLayer('your-api-key');

  // Get 20 events starting from the 10th event
  const events = await sendlayer.Events.get({
    startFrom: 10,
    retrieveCount: 20
  });
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer

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

  # Get 20 events starting from the 10th event
  events = sendlayer.Events.get(
      start_from=10,
      retrieve_count=20
  )
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $events = $sendlayer->Events->get([
    'startFrom' => 10,
    'retrieveCount' => 20
  ]);
  ```

  ```ruby Ruby theme={null}
  sendlayer = SendLayer::SendLayer.new('your-api-key')

  events = sendlayer.events.get(
    start_from: 10,
    retrieve_count: 20
  )
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  startFrom := 10
  retrieveCount := 20
  events, err := sl.Events.Get(&sendlayer.GetEventsRequest{
    StartFrom:    &startFrom,
    RetrieveCount: &retrieveCount,
  })
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://console.sendlayer.com/api/v1/events?StartFrom=10&RetrieveCount=20' \
    --header 'Authorization: Bearer <apiKey>'
  ```
</CodeGroup>

## Combining Filters

You can combine multiple filters to get very specific results.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  const sendlayer = new SendLayer('your-api-key');

  // Get opened events from the last 7 days, limited to 50 results
  const startDate = Math.floor((Date.now() - 7 * 24 * 60 * 60 * 1000) / 1000);
  const endDate = Math.floor(Date.now() / 1000);

  const events = await sendlayer.Events.get({
    startDate: startDate,
    endDate: endDate,
    event: 'opened',
    retrieveCount: 50
  });
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer
  from datetime import datetime, timedelta

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

  # Get opened events from the last 7 days, limited to 50 results
  start_date = int((datetime.now() - timedelta(days=7)).timestamp())
  end_date = int(datetime.now().timestamp())

  events = sendlayer.Events.get(
      start_date=start_date,
      end_date=end_date,
      event='opened',
      retrieve_count=50
  )
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $events = $sendlayer->Events->get([
    'startDate' => time() - 7 * 24 * 60 * 60,
    'endDate' => time(),
    'event' => 'opened',
    'retrieveCount' => 50
  ]);
  ```

  ```ruby Ruby theme={null}
  sendlayer = SendLayer::SendLayer.new('your-api-key')

  events = sendlayer.events.get(
    start_date: (Time.now - 7*24*60*60).to_i,
    end_date: Time.now.to_i,
    event: 'opened',
    retrieve_count: 50
  )
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  end := time.Now()
  start := end.Add(-7 * 24 * time.Hour)
  retrieveCount := 50

  events, err := sl.Events.Get(&sendlayer.GetEventsRequest{
    StartDate:    &start,
    EndDate:      &end,
    Event:        "opened",
    RetrieveCount: &retrieveCount,
  })
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://console.sendlayer.com/api/v1/events?StartDate=1745736096&EndDate=1746340896&Event=opened&RetrieveCount=50' \
    --header 'Authorization: Bearer <apiKey>'
  ```
</CodeGroup>

## Available Parameters

The events API supports the following parameters for filtering and pagination:

| Parameter       | Type     | Required | Description                                                                                             |
| --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `startDate`     | `number` | No       | Unix timestamp for the start of the date range                                                          |
| `endDate`       | `number` | No       | Unix timestamp for the end of the date range                                                            |
| `event`         | `string` | No       | Filter by event type (accepted, rejected, failed, delivered, opened, clicked, unsubscribed, complained) |
| `messageId`     | `string` | No       | Filter by specific email Message ID                                                                     |
| `startFrom`     | `number` | No       | Starting position for pagination (default: 0)                                                           |
| `retrieveCount` | `number` | No       | Number of events to retrieve (default: 5)                                                               |

## Event Data Structure

Each event contains detailed information about what happened to your email:

```json theme={null}
{
  "Event": "opened",
  "LoggedAt": 1746340896,
  "LogLevel": "info",
  "Message": {
    "Headers": {
      "MessageId": "06e4491f-fc5a-49cb-bc57-xxxxxx",
      "From": [["", "sender@example.com"]],
      "ReplyTo": [],
      "To": [["", "recipient@example.com"]],
      "Cc": [],
      "Bcc": []
    },
    "Size": 2004,
    "Transport": "api"
  },
  "Recipient": "recipient@example.com",
  "Reason": "Email opened.",
  "Ip": "10.30.126.18",
  "Geolocation": {
    "City": "San Francisco",
    "Region": "CA",
    "Country": "US"
  }
}
```

### Event Fields Explained

* **Event**: The type of event that occurred
* **LoggedAt**: Unix timestamp when the event was logged
* **LogLevel**: Log level (usually "info")
* **Message**: Email message details including headers and metadata
* **Recipient**: The email address of the recipient
* **Reason**: Human-readable description of what happened
* **Ip**: IP address where the event occurred (for opens/clicks)
* **Geolocation**: Geographic location data (for opens/clicks)

## Best Practices

1. **Use Date Filters**: Always specify date ranges when retrieving events to avoid overwhelming results
2. **Implement Pagination**: Use `startFrom` and `retrieveCount` for large datasets
3. **Cache Results**: Store event data locally to avoid repeated API calls
4. **Monitor Rate Limits**: Be mindful of API rate limits when making frequent requests
5. **Error Handling**: Implement proper error handling for API failures
6. **Regular Polling**: Set up regular intervals to check for new events

## FAQ

<AccordionGroup>
  <Accordion title="How far back can I retrieve events?">
    SendLayer stores event data for a limited time period. This varies by account and is subject to change. Contact support for specific retention details for your account.
  </Accordion>

  <Accordion title="How often should I check for new events?">
    For real-time monitoring, check every few minutes. For batch processing, hourly or daily checks are usually sufficient.
  </Accordion>

  <Accordion title="What timezone are the timestamps in?">
    All timestamps are in Unix timestamp format (seconds since epoch) and are in UTC timezone.
  </Accordion>
</AccordionGroup>


# Managing Webhooks
Source: https://developers.sendlayer.com/guides/manage-webhooks

Learn how to create, retrieve, and delete webhooks using the SendLayer API

## Overview

Webhooks are HTTP callbacks that allow SendLayer to notify your application in real-time when specific email events occur. Instead of polling the API to check for updates, webhooks automatically send data to your specified URL when events happen, such as when an email is opened, clicked, or bounced.

## How Webhooks Work

1. **Setup**: You create a webhook by providing a URL endpoint and specifying which events you want to monitor
2. **Monitoring**: SendLayer monitors your email activity for the specified events
3. **Notification**: When an event occurs, SendLayer sends an HTTP POST request to your webhook URL with event data
4. **Processing**: Your application receives and processes the webhook data

## Prerequisites

* [Authorize your domain](https://sendlayer.com/docs/authorizing-your-domain/)
* [Create or retrieve your API key](https://sendlayer.com/docs/managing-api-keys/)
* A publicly accessible webhook endpoint URL
* [Install the SendLayer SDK](/quickstart/installation)

## Creating a Webhook

To create a webhook, you need to specify the event type you want to monitor and the URL where SendLayer should send notifications.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  const sendlayer = new SendLayer('your-api-key');

  const params = {
    url: 'https://your-domain.com/webhook',
    event: 'open'
  };

  const response = await sendlayer.Webhooks.create(params);
  console.log('Webhook created with ID:', response.NewWebhookID);
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer

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

  params = {
      "url": "https://your-domain.com/webhook",
      "event": "open"
  }

  response = sendlayer.Webhooks.create(**params)
  print(f"Webhook created with ID: {response['NewWebhookID']}")
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $params = [
    'url' => 'https://your-domain.com/webhook',
    'event' => 'open'
  ];

  $response = $sendlayer->Webhooks->create($params);
  ```

  ```ruby Ruby theme={null}
  require 'sendlayer'

  sendlayer = SendLayer::SendLayer.new('your-api-key')

  webhook = sendlayer.webhooks.create(
    url: 'https://your-domain.com/webhook',
    event: 'open'
  )
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  webhook, err := sl.Webhooks.Create(&sendlayer.WebhookCreateRequest{
    WebhookURL: "https://your-domain.com/webhook",
    Event:      "open",
  })
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://console.sendlayer.com/api/v1/webhooks \
    --header 'Authorization: Bearer <apiKey>' \
    --header 'Content-Type: application/json' \
    --data '{
    "Event": "open",
    "WebhookURL": "https://your-domain.com/webhook"
  }'
  ```
</CodeGroup>

<Warning>Replace `<apiKey>` with your actual SendLayer API key in the request header.</Warning>

### Available Event Types

You can monitor the following email events:

| Event         | Description                                       |
| ------------- | ------------------------------------------------- |
| `delivery`    | Email successfully delivered to recipient's inbox |
| `open`        | Recipient opened the email                        |
| `click`       | Recipient clicked a link in the email             |
| `bounce`      | Email failed to deliver and bounced back          |
| `unsubscribe` | Recipient unsubscribed from emails                |
| `complaint`   | Recipient marked email as spam                    |

## Retrieving Webhooks

You can retrieve all webhooks associated with your account to see their current status and configuration.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  const sendlayer = new SendLayer('your-api-key');

  const webhooks = await sendlayer.Webhooks.get();
  console.log('Webhooks:', webhooks.Webhooks);
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer

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

  webhooks = sendlayer.Webhooks.get()
  print("Webhooks:", webhooks['Webhooks'])
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $webhooks = $sendlayer->Webhooks->get();
  ```

  ```ruby Ruby theme={null}
  sendlayer = SendLayer::SendLayer.new('your-api-key')
  webhooks = sendlayer.webhooks.get
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")
  webhooks, err := sl.Webhooks.Get()
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://console.sendlayer.com/api/v1/webhooks \
    --header 'Authorization: Bearer <apiKey>'
  ```
</CodeGroup>

### Get Webhook Response Format

When you retrieve webhooks, you'll receive data in this format:

```json theme={null}
{
  "Webhooks": [
    {
      "WebhookID": "23718",
      "CreatedAt": "2025-04-11 09:43:07",
      "UpdatedAt": "2025-04-11 09:43:07",
      "Status": "Enabled",
      "WebhookURL": "https://your-domain.com/webhook",
      "Event": "open",
      "LastResponseCode": "200",
      "LastResponseBody": "",
      "LastResponseAt": "2025-04-11 10:15:30",
      "LastResponseTryCounter": "0"
    }
  ]
}
```

## Deleting a Webhook

You can delete a webhook by providing its ID. This action cannot be undone.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  const sendlayer = new SendLayer('your-api-key');

  const webhookId = 23718;
  await sendlayer.Webhooks.delete(webhookId);
  console.log('Webhook deleted successfully');
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer

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

  webhook_id = 23718
  sendlayer.Webhooks.delete(webhook_id)
  print("Webhook deleted successfully")
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $webhookId = 23718;
  $sendlayer->Webhooks->delete($webhookId);
  ```

  ```ruby Ruby theme={null}
  sendlayer = SendLayer::SendLayer.new('your-api-key')
  webhook_id = 23718
  sendlayer.webhooks.delete(webhook_id)
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")
  webhookID := 23718
  _ = sl.Webhooks.Delete(webhookID)
  ```

  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://console.sendlayer.com/api/v1/webhooks/23718 \
    --header 'Authorization: Bearer <apiKey>'
  ```
</CodeGroup>

<Warning>Deleting a webhook cannot be undone. You won't be able to recover or access your webhook after deleting it.</Warning>

## Webhook Payload Format

When SendLayer sends a webhook notification to your endpoint, it includes detailed information about the event. Below, we've provided examples of the payload for each event:

<CodeGroup>
  ```json Open theme={null}
  {
    "event": {
      "method": "POST",
      "path": "/",
      "query": {},
      "client_ip": "0.0.0.0",
      "url": "https://your-domain.com/webhook",
      "headers": {
        "host": "your-domain.com",
        "content-length": 320,
        "user-agent": "GuzzleHttp/6.5.1 curl/7.68.0 PHP/5.6.40-67+ubuntu20.04.1+deb.sury.org+1",
        "content-type": "application/json"
      },
      "body": {
        "Signature": {
          "Timestamp": 1758100959,
          "Token": "c0a6c82bdde01faab7e857",
          "Signature": "3d1bf89405e4b71ed80bc240cd512aa7ed9db9dcfb17"
        },
        "EventData": {
          "Event": "opened",
          "Domain": "example.com",
          "MessageID": "4331c06-2d1d-4387-969e-697835",
          "To": "recipient@example.com",
          "IPAddress": "10.30.126.18"
        }
      }
    }
  }
  ```

  ```json Click theme={null}
  {
    "event": {
      "method": "POST",
      "path": "/",
      "query": {},
      "client_ip": "0.0.0.0",
      "url": "https://your-domain.com/webhook",
      "headers": {
        "host": "your-domain.com",
        "content-length": 320,
        "user-agent": "GuzzleHttp/6.5.1 curl/7.68.0 PHP/5.6.40-67+ubuntu20.04.1+deb.sury.org+1",
        "content-type": "application/json"
      },
      "body": {
        "Signature": {
          "Timestamp": 1758100959,
          "Token": "c0a6c82bdde01faab7e857",
          "Signature": "3d1bf89405e4b71ed80bc240cd512aa7ed9db9dcfb17"
        },
        "EventData": {
          "Event": "clicked",
          "Domain": "example.com",
          "MessageID": "4331c06-2d1d-4387-969e-697835",
          "To": "recipient@example.com",
          "IPAddress": "10.30.126.18"
        }
      }
    }
  }
  ```

  ```json Delivery theme={null}
  {
    "event": {
      "method": "POST",
      "path": "/",
      "query": {},
      "client_ip": "0.0.0.0",
      "url": "https://your-domain.com/webhook",
      "headers": {
        "host": "your-domain.com",
        "content-length": 320,
        "user-agent": "GuzzleHttp/6.5.1 curl/7.68.0 PHP/5.6.40-67+ubuntu20.04.1+deb.sury.org+1",
        "content-type": "application/json"
      },
      "body": {
        "Signature": {
          "Timestamp": 1758100959,
          "Token": "c0a6c82bdde01faab7e857",
          "Signature": "3d1bf89405e4b71ed80bc240cd512aa7ed9db9dcfb17"
        },
        "EventData": {
          "Event": "delivered",
          "Domain": "example.com",
          "MessageID": "4331c06-2d1d-4387-969e-697835",
          "To": "recipient@example.com",
        }
      }
    }
  }
  ```

  ```json Bounce theme={null}
  {
    "event": {
      "method": "POST",
      "path": "/",
      "query": {},
      "client_ip": "0.0.0.0",
      "url": "https://your-domain.com/webhook",
      "headers": {
        "host": "your-domain.com",
        "content-length": 320,
        "user-agent": "GuzzleHttp/6.5.1 curl/7.68.0 PHP/5.6.40-67+ubuntu20.04.1+deb.sury.org+1",
        "content-type": "application/json"
      },
      "body": {
        "Signature": {
          "Timestamp": 1758100959,
          "Token": "c0a6c82bdde01faab7e857",
          "Signature": "3d1bf89405e4b71ed80bc240cd512aa7ed9db9dcfb17"
        },
        "EventData": {
          "Event": "bounced",
          "EventType": "failed",
          "Domain": "example.com",
          "MessageID": "4331c06-2d1d-4387-969e-697835",
          "BouncedEmailAddress": {
            "EmailAddress": "recipient@example.com",
            "Status": "smtp;550 5.1.1 User Unknown",
            "DiagnosticCode": "5.1.1 (bad destination mailbox address)"
          },
          "Reason": "smtp;550 5.1.1 User Unknown",
          "Code": "5.1.1 (bad destination mailbox address)"
        }
      }
    }
  }
  ```

  ```json Unsubscribe theme={null}
  {
    "event": {
      "method": "POST",
      "path": "/",
      "query": {},
      "client_ip": "0.0.0.0",
      "url": "https://your-domain.com/webhook",
      "headers": {
        "host": "your-domain.com",
        "content-length": 320,
        "user-agent": "GuzzleHttp/6.5.1 curl/7.68.0 PHP/5.6.40-67+ubuntu20.04.1+deb.sury.org+1",
        "content-type": "application/json"
      },
      "body": {
        "Signature": {
          "Timestamp": 1758100959,
          "Token": "c0a6c82bdde01faab7e857",
          "Signature": "3d1bf89405e4b71ed80bc240cd512aa7ed9db9dcfb17"
        },
        "EventData": {
          "Event": "unsubscribed",
          "Domain": "example.com",
          "MessageID": "4331c06-2d1d-4387-969e-697835",
          "To": "recipient@example.com",
          "IPAddress": "10.30.126.18"
        }
      }
    }
  }
  ```
</CodeGroup>

## Best Practices

1. **Use HTTPs**: Always use HTTPs URLs for your webhook endpoints to ensure data security
2. **Monitor Status**: Regularly check your webhook status and response codes
3. **Error Handling**: Implement proper error handling for webhook processing

## FAQs

<AccordionGroup>
  <Accordion title="How many webhooks can I create?">
    You can create multiple webhooks for different events and endpoints. There's no strict limit, but it's recommended to keep the number manageable for easier maintenance.
  </Accordion>

  <Accordion title="What happens if my webhook endpoint is down?">
    SendLayer will retry sending webhook notifications if your endpoint is unavailable. Check the `LastResponseCode` and `LastResponseTryCounter` fields to monitor delivery status.
  </Accordion>

  <Accordion title="Can I update an existing webhook?">
    Currently, webhooks cannot be updated. You'll need to delete the existing webhook and create a new one with the updated configuration.
  </Accordion>

  <Accordion title="How do I test my webhook endpoint?">
    You can use tools like webhook.site or ngrok to create temporary public URLs for testing webhook functionality during development.
  </Accordion>

  <Accordion title="What should I do if webhooks stop working?">
    Check your webhook endpoint's availability, verify the URL is correct, and ensure your server can handle POST requests. Review the `LastResponseCode` field for error details.
  </Accordion>
</AccordionGroup>


# Send Email
Source: https://developers.sendlayer.com/guides/send-email

Learn how to send emails using the SendLayer API

## Overview

SendLayer makes it easy to send transactional and marketing emails via a simple API. This guide walks you through sending your first email using the SendLayer API, with examples for popular programming languages.

## Prerequisites

* [Authorize your domain](https://sendlayer.com/docs/authorizing-your-domain/)
* [Create or retrieve your API key](https://sendlayer.com/docs/managing-api-keys/)
* [Install the SendLayer SDK](/quickstart/installation)

## Sending an Email

After setting up your domain and API key, you can send emails using the SDK or directly via HTTP requests.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  const sendlayer = new SendLayer('your-api-key');

  const params = {
    from: 'sender@example.com',
    to: 'recipient@example.com', // or array of recipients
    subject: 'Test Email',
    text: 'This is a test email sent using SendLayer Node.js SDK',
  };

  const response = await sendlayer.Emails.send(params);
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer

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

  params = {
      "sender": "sender@example.com",
      "to": "recipient@example.com",
      "subject": "Sending a Test Email",
      "text": "This is a test email sent using SendLayer's Python SDK" 
  }

  response = sendlayer.Emails.send(**params)
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $params = [
    'from' => 'sender@example.com',
    'to' => 'recipient@example.com', // or array of recipients
    'subject' => 'Test Email',
    'text' => "This is a test email sent using SendLayer's PHP SDK",
  ];

  $response = $sendlayer->Emails->send($params);
  ```

  ```ruby Ruby theme={null}
  require 'sendlayer'

  sendlayer = SendLayer::SendLayer.new('your-api-key')

  response = sendlayer.emails.send(
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Sending a Test Email',
    text: "This is a test email sent using SendLayer's Ruby SDK"
  )
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
    From:    "sender@example.com",
    To:      "recipient@example.com",
    Subject: "Sending a Test Email",
    Text:    "This is a test email sent using SendLayer's Go SDK",
  })
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://console.sendlayer.com/api/v1/email \
    --header 'Authorization: Bearer <apiKey>' \
    --header 'Content-Type: application/json' \
    --data '{
    "From": {
      "name": "Paulie Paloma",
      "email": "paulie@example.com"
    },
    "To": [
      {
        "name": "Pattie Paloma",
        "email": "pattie@exampledomain.com"
      }
    ],
    "Subject": "This is the email subject",
    "ContentType": "Text",
    "PlainContent": "This is a test email sent with the SendLayer API!"
  }'
  ```
</CodeGroup>

<Warning>Replace `<apiKey>` with your actual SendLayer API key in the request header.</Warning>

You can also send to [multiple recipients](/guides/send-email-to-multiple-recipients), add CC/BCC, and [attach files](/guides/send-email-with-attachments).

SendLayer API also let's you send HTML emails. This can be useful if you'd like to use a template to send welcome emails to new users.

To send HTML emails, simply update the `params` variable to include the `html` object. Then enter your HTML email as a string.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const params = {
    from: 'sender@example.com',
    to: 'recipient@example.com', // or array of recipients
    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>',
  };
  ```

  ```python Python theme={null}
  params = {
      "sender": "sender@example.com",
      "to": "recipient@example.com",
      "subject": "Sending a 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>" 
  }
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $params = [
    'from' => 'sender@example.com',
    'to' => 'recipient@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>',
  ];
  ```

  ```ruby Ruby theme={null}
  sendlayer = SendLayer::SendLayer.new('your-api-key')

  response = sendlayer.emails.send(
    from: 'sender@example.com',
    to: 'recipient@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>'
  )
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
    From:    "sender@example.com",
    To:      "recipient@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>",
  })
  ```

  ```bash cURL theme={null}
    --data '{
    "From": {
      "name": "Paulie Paloma",
      "email": "paulie@example.com"
    },
    "To": [
      {
        "name": "Pattie Paloma",
        "email": "pattie@exampledomain.com"
      }
    ],
    "Subject": "This is the email subject",
    "ContentType": "HTML",
    "HTMLContent": "<html><body><p>This is a test email sent with the <a href=\"https://sendlayer.com\">SendLayer</a> API!</p></body></html>"
  }'
  ```
</CodeGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Why do I need to authorize my domain?">
    Authorizing your domain proves ownership and improves email deliverability by reducing the likelihood of your emails being marked as spam.
  </Accordion>

  <Accordion title="Where do I find my API key?">
    You can create or retrieve your API key from your SendLayer dashboard under the **Settings » API Keys** section.
  </Accordion>

  <Accordion title="Can I send emails to multiple recipients?">
    Yes, you can provide an array of email addresses in the `to` field or see our [guide](/guides/send-email-to-multiple-recipients) for more details.
  </Accordion>

  <Accordion title="How do I attach files to my email?">
    See our [attachments guide](/guides/send-email-with-attachments) for instructions on sending emails with attachments.
  </Accordion>

  <Accordion title="What should I do if my email is not delivered?">
    Check your domain authorization, verify your API key, and review the response from the API for any error messages. You can also consult the SendLayer dashboard for delivery status and logs.
  </Accordion>
</AccordionGroup>


# Send Email to Multiple Recipients
Source: https://developers.sendlayer.com/guides/send-email-to-multiple-recipients

Learn how to send emails to multiple recipients using the SendLayer API

## Overview

SendLayer allows you to send emails to multiple recipients in a single API call. This guide shows you how to send emails to multiple recipients using the SendLayer API, with examples for popular programming languages.

## Prerequisites

* [Authorize your domain](https://sendlayer.com/docs/authorizing-your-domain/)
* [Create or retrieve your API key](https://sendlayer.com/docs/managing-api-keys/)
* [Install the SendLayer SDK](/quickstart/installation)

## Sending Emails to Multiple Recipients

You can send emails to multiple recipients by providing an array of email addresses in the `to` field. Each recipient will receive the same email content.

<Note>**Rate Limit**: When sending to multiple recipients, be aware of SendLayer's rate limits. We recommend sending to no more than 100 recipients per request for optimal performance. For larger lists, consider using our bulk sending features or sending in batches.</Note>

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  const sendlayer = new SendLayer('your-api-key');

  const params = {
    from: 'sender@example.com',
    to: ['recipient1@example.com', 'recipient2@example.com', 'recipient3@example.com'],
    subject: 'Newsletter Update',
    html: '<html><body><h1>Newsletter Update</h1><p>This is a newsletter sent to multiple recipients using SendLayer Node.js SDK</p></body></html>',
  };

  const response = await sendlayer.Emails.send(params);
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer

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

  params = {
      "sender": "sender@example.com",
      "to": ["recipient1@example.com", "recipient2@example.com", "recipient3@example.com"],
      "subject": "Newsletter Update",
      "html": "<html><body><h1>Newsletter Update</h1><p>This is a newsletter sent to multiple recipients using SendLayer's Python SDK</p></body></html>" 
  }

  response = sendlayer.Emails.send(**params)
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $params = [
    'from' => 'sender@example.com',
    'to' => ['recipient1@example.com', 'recipient2@example.com', 'recipient3@example.com'],
    'subject' => 'Newsletter Update',
    'html' => '<html><body><h1>Newsletter Update</h1><p>This is a newsletter sent to multiple recipients using SendLayer\'s PHP SDK</p></body></html>',
  ];

  $response = $sendlayer->Emails->send($params);
  ```

  ```ruby Ruby theme={null}
  require 'sendlayer'

  sendlayer = SendLayer::SendLayer.new('your-api-key')

  response = sendlayer.emails.send(
    from: { email: 'sender@example.com', name: 'Sender Name' },
    to: [
      { email: 'recipient1@example.com', name: 'Recipient 1' },
      { email: 'recipient2@example.com', name: 'Recipient 2' },
      { email: 'recipient3@example.com', name: 'Recipient 3' }
    ],
    subject: 'Newsletter Update',
    html: '<html><body><h1>Newsletter Update</h1><p>This is a newsletter sent to multiple recipients using SendLayer Ruby SDK</p></body></html>'
  )
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
    From: sendlayer.EmailAddress{Email: "sender@example.com", Name: "Sender Name"},
    To: []sendlayer.EmailAddress{
      {Email: "recipient1@example.com", Name: "Recipient 1"},
      {Email: "recipient2@example.com", Name: "Recipient 2"},
      {Email: "recipient3@example.com", Name: "Recipient 3"},
    },
    Subject: "Newsletter Update",
    Html:    "<html><body><h1>Newsletter Update</h1><p>This is a newsletter sent to multiple recipients using SendLayer Go SDK</p></body></html>",
  })
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://console.sendlayer.com/api/v1/email \
    --header 'Authorization: Bearer <apiKey>' \
    --header 'Content-Type: application/json' \
    --data '{
    "From": {
      "name": "Newsletter Team",
      "email": "newsletter@example.com"
    },
    "To": [
      {
        "name": "John Doe",
        "email": "john@example.com"
      },
      {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      {
        "name": "Bob Johnson",
        "email": "bob@example.com"
      }
    ],
    "Subject": "Weekly Newsletter",
    "ContentType": "HTML",
    "HTMLContent": "<html><body><h1>Weekly Newsletter</h1><p>This is our weekly newsletter sent to multiple subscribers using the <a href=\"https://sendlayer.com\">SendLayer</a> API!</p></body></html>"
  }'
  ```
</CodeGroup>

<Warning>Replace `<apiKey>` with your actual SendLayer API key in the request header.</Warning>

## Using CC and BCC

You can also use CC (Carbon Copy) and BCC (Blind Carbon Copy) to send emails to additional recipients. CC recipients will be visible to all recipients, while BCC recipients will be hidden from other recipients.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const params = {
    from: 'sender@example.com',
    to: ['recipient1@example.com', 'recipient2@example.com'],
    cc: ['cc1@example.com', 'cc2@example.com'],
    bcc: ['bcc1@example.com', 'bcc2@example.com'],
    subject: 'Meeting Invitation',
    html: '<html><body><h1>Meeting Invitation</h1><p>You are invited to our team meeting next week.</p></body></html>',
  };
  ```

  ```python Python theme={null}
  params = {
      "sender": "sender@example.com",
      "to": ["recipient1@example.com", "recipient2@example.com"],
      "cc": ["cc1@example.com", "cc2@example.com"],
      "bcc": ["bcc1@example.com", "bcc2@example.com"],
      "subject": "Meeting Invitation",
      "html": "<html><body><h1>Meeting Invitation</h1><p>You are invited to our team meeting next week.</p></body></html>"
  }
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $params = [
    'from' => 'sender@example.com',
    'to' => ['recipient1@example.com', 'recipient2@example.com'],
    'cc' => ['cc1@example.com', 'cc2@example.com'],
    'bcc' => ['bcc1@example.com', 'bcc2@example.com'],
    'subject' => 'Meeting Invitation',
    'html' => '<html><body><h1>Meeting Invitation</h1><p>You are invited to our team meeting next week.</p></body></html>',
  ];
  ```

  ```ruby Ruby theme={null}
  params = {
    from: 'sender@example.com',
    to: ['recipient1@example.com', 'recipient2@example.com'],
    cc: ['cc1@example.com', 'cc2@example.com'],
    bcc: ['bcc1@example.com', 'bcc2@example.com'],
    subject: 'Meeting Invitation',
    html: '<html><body><h1>Meeting Invitation</h1><p>You are invited to our team meeting next week.</p></body></html>'
  }

  sendlayer = SendLayer::SendLayer.new('your-api-key')
  response = sendlayer.emails.send(params)
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
    From: "sender@example.com",
    To: []sendlayer.EmailAddress{
      {Email: "recipient1@example.com"},
      {Email: "recipient2@example.com"},
    },
    Subject: "Meeting Invitation",
    Html:    "<html><body><h1>Meeting Invitation</h1><p>You are invited to our team meeting next week.</p></body></html>",
    Cc:      []sendlayer.EmailAddress{{Email: "cc1@example.com"}, {Email: "cc2@example.com"}},
    Bcc:     []sendlayer.EmailAddress{{Email: "bcc1@example.com"}, {Email: "bcc2@example.com"}},
  })
  ```
</CodeGroup>

## Including Names and Email Addresses

You can include both names and email addresses for senders and recipients to make your emails more professional and personal. This is especially useful for newsletters, announcements, or any communication where you want to display the sender's name.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const params = {
    from: {
      name: 'John Smith',
      email: 'john@example.com'
    },
    to: [
      {
        name: 'Alice Johnson',
        email: 'alice@example.com'
      },
      {
        name: 'Bob Wilson',
        email: 'bob@example.com'
      },
      {
        name: 'Carol Davis',
        email: 'carol@example.com'
      }
    ],
    subject: 'Team Update',
    html: '<html><body><h1>Team Update</h1><p>Hello team, here is our weekly update.</p></body></html>',
  };
  ```

  ```python Python theme={null}
  params = {
      "sender": {
          "name": "John Smith",
          "email": "john@example.com"
      },
      "to": [
          {
              "name": "Alice Johnson",
              "email": "alice@example.com"
          },
          {
              "name": "Bob Wilson", 
              "email": "bob@example.com"
          },
          {
              "name": "Carol Davis",
              "email": "carol@example.com"
          }
      ],
      "subject": "Team Update",
      "html": "<html><body><h1>Team Update</h1><p>Hello team, here is our weekly update.</p></body></html>"
  }
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $params = [
    'from' => [ 'name' => 'John Smith', 'email' => 'john@example.com' ],
    'to' => [
      [ 'name' => 'Alice Johnson', 'email' => 'alice@example.com' ],
      [ 'name' => 'Bob Wilson', 'email' => 'bob@example.com' ],
      [ 'name' => 'Carol Davis', 'email' => 'carol@example.com' ]
    ],
    'subject' => 'Team Update',
    'html' => '<html><body><h1>Team Update</h1><p>Hello team, here is our weekly update.</p></body></html>',
  ];
  ```

  ```ruby Ruby theme={null}
  params = {
    from: { name: 'John Smith', email: 'john@example.com' },
    to: [
      { name: 'Alice Johnson', email: 'alice@example.com' },
      { name: 'Bob Wilson', email: 'bob@example.com' },
      { name: 'Carol Davis', email: 'carol@example.com' }
    ],
    subject: 'Team Update',
    html: '<html><body><h1>Team Update</h1><p>Hello team, here is our weekly update.</p></body></html>'
  }

  sendlayer = SendLayer::SendLayer.new('your-api-key')
  response = sendlayer.emails.send(params)
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
    From: sendlayer.EmailAddress{Email: "john@example.com", Name: "John Smith"},
    To: []sendlayer.EmailAddress{
      {Email: "alice@example.com", Name: "Alice Johnson"},
      {Email: "bob@example.com", Name: "Bob Wilson"},
      {Email: "carol@example.com", Name: "Carol Davis"},
    },
    Subject: "Team Update",
    Html:    "<html><body><h1>Team Update</h1><p>Hello team, here is our weekly update.</p></body></html>",
  })
  ```
</CodeGroup>

<Note>See our [Send Email guide](/guides/send-email) for basic email sending instructions.</Note>

## FAQ

<AccordionGroup>
  <Accordion title="What is the maximum number of recipients I can send to?">
    SendLayer has specific limits for multiple recipients regardless of your account type:

    * **Send To**: 10 email addresses
    * **CC**: 10 email addresses
    * **BCC**: 5 email addresses

    For more information, see our [Rate Limits](/api-reference/rate-limit) documentation.
  </Accordion>

  <Accordion title="Can I personalize emails for each recipient?">
    Yes, you can personalize emails by using merge tags or by sending individual emails in a loop.
  </Accordion>

  <Accordion title="What's the difference between CC and BCC?">
    CC (Carbon Copy) recipients are visible to all other recipients in the email. BCC (Blind Carbon Copy) recipients are hidden from other recipients, making them ideal for privacy-sensitive communications.
  </Accordion>

  <Accordion title="How do I handle bounced emails for multiple recipients?">
    SendLayer provides webhook notifications for bounced emails. You can set up webhooks to receive real-time notifications when emails bounce, allowing you to clean your recipient lists.
  </Accordion>

  <Accordion title="Can I track email opens and clicks for multiple recipients?">
    Yes, SendLayer provides tracking capabilities for email opens and clicks. You can enable tracking in your email parameters and receive webhook notifications for engagement events.
  </Accordion>

  <Accordion title="What should I do if some recipients don't receive the email?">
    Check your domain authorization, verify your API key, and review the response from the API for any error messages. You can also consult the SendLayer dashboard for delivery status and logs for each recipient.
  </Accordion>
</AccordionGroup>


# Send Email with Attachments
Source: https://developers.sendlayer.com/guides/send-email-with-attachments

Learn how to send emails with attachments using the SendLayer API

## Overview

SendLayer allows you to send emails with file attachments. This guide shows you how to send emails with attachments using the SendLayer API, with examples for popular programming languages.

## Prerequisites

* [Authorize your domain](https://sendlayer.com/docs/authorizing-your-domain/)
* [Create or retrieve your API key](https://sendlayer.com/docs/managing-api-keys/)
* [Install the SendLayer SDK](/quickstart/installation)

## Sending Emails with Attachments

You can attach files to your emails by including an `attachments` array in your email parameters. The SendLayer SDKs handle file encoding automatically, so you only need to provide the file path and type.

<Note>The maximum file size per email is **10 MB**, including both the email content and all attachments combined.</Note>

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  const sendlayer = new SendLayer('your-api-key');

  const params = {
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Document Attachment',
    html: '<html><body><h1>Please find the attached document</h1><p>I have attached the requested PDF file for your review.</p></body></html>',
    attachments: [
      {
        path: './path/to/document.pdf',
        type: 'application/pdf'
      }
    ]
  };

  const response = await sendlayer.Emails.send(params);
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer

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

  params = {
      "sender": "sender@example.com",
      "to": "recipient@example.com",
      "subject": "Document Attachment",
      "html": "<html><body><h1>Please find the attached document</h1><p>I have attached the requested PDF file for your review.</p></body></html>",
      "attachments": [
          {
              "path": "./path/to/document.pdf",
              "type": "application/pdf"
          }
      ]
  }

  response = sendlayer.Emails.send(**params)
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $params = [
    'from' => ['email' => 'sender@example.com', 'name' => 'Sender Name'],
    'to' => 'recipient@example.com',
    'subject' => 'Document Attachment',
    'html' => '<html><body><h1>Please find the attached document</h1><p>I have attached the requested PDF file for your review.</p></body></html>',
    'attachments' => [
      [ 'path' => './path/to/document.pdf', 'type' => 'application/pdf' ]
    ]
  ];

  $response = $sendlayer->Emails->send($params);
  ```

  ```ruby Ruby theme={null}
  require 'sendlayer'

  sendlayer = SendLayer::SendLayer.new('your-api-key')

  params = {
    from: { email: 'sender@example.com', name: 'Sender Name' },
    to: 'recipient@example.com',
    subject: 'Document Attachment',
    html: '<html><body><h1>Please find the attached document</h1><p>I have attached the requested PDF file for your review.</p></body></html>',
    attachments: [
      { path: './path/to/document.pdf', type: 'application/pdf' }
    ]
  }

  response = sendlayer.emails.send(params)
  ```

  ```go Go theme={null}
  sl := sendlayer.New("your-api-key")

  resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
    From:    sendlayer.EmailAddress{Email: "sender@example.com", Name: "Sender Name"},
    To:      "recipient@example.com",
    Subject: "Document Attachment",
    Html:    "<html><body><h1>Please find the attached document</h1><p>I have attached the requested PDF file for your review.</p></body></html>",
    Attachments: []sendlayer.Attachment{
      {Path: "./path/to/document.pdf", Type: "application/pdf"},
    },
  })
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://console.sendlayer.com/api/v1/email \
    --header 'Authorization: Bearer <apiKey>' \
    --header 'Content-Type: application/json' \
    --data '{
    "From": {
      "name": "Document Sender",
      "email": "sender@example.com"
    },
    "To": [
      {
        "name": "Recipient Name",
        "email": "recipient@example.com"
      }
    ],
    "Subject": "Document Attachment",
    "ContentType": "HTML",
    "HTMLContent": "<html><body><h1>Please find the attached document</h1><p>I have attached the requested PDF file for your review.</p></body></html>",
    "Attachments": [
      {
        "Filename": "document.pdf",
        "Content": "JVBERi0xLjQKJcOkw7zDtsO...",
        "Type": "application/pdf"
      }
    ]
  }'
  ```
</CodeGroup>

<Warning>Replace `<apiKey>` with your actual SendLayer API key in the request header. The `Content` field in the cURL example should contain the actual base64-encoded file content.</Warning>

## Multiple Attachments

You can attach multiple files to a single email by adding more objects to the `attachments` array.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const params = {
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Multiple Attachments',
    html: '<html><body><h1>Multiple Files Attached</h1><p>Please find the attached documents.</p></body></html>',
    attachments: [
      {
        path: './path/to/document.pdf',
        type: 'application/pdf'
      },
      {
        path: './path/to/image.jpg',
        type: 'image/jpeg'
      }
    ]
  };
  ```

  ```python Python theme={null}
  params = {
      "sender": "sender@example.com",
      "to": "recipient@example.com",
      "subject": "Multiple Attachments",
      "html": "<html><body><h1>Multiple Files Attached</h1><p>Please find the attached documents.</p></body></html>",
      "attachments": [
          {
              "path": "./path/to/document.pdf",
              "type": "application/pdf"
          },
          {
              "path": "./path/to/image.jpg",
              "type": "image/jpeg"
          }
      ]
  }
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $params = [
    'from' => 'sender@example.com',
    'to' => 'recipient@example.com',
    'subject' => 'Multiple Attachments',
    'html' => '<html><body><h1>Multiple Files Attached</h1><p>Please find the attached documents.</p></body></html>',
    'attachments' => [
      [ 'path' => './path/to/document.pdf', 'type' => 'application/pdf' ],
      [ 'path' => './path/to/image.jpg', 'type' => 'image/jpeg' ]
    ]
  ];
  ```

  ```ruby Ruby theme={null}
  params = {
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Multiple Attachments',
    html: '<html><body><h1>Multiple Files Attached</h1><p>Please find the attached documents.</p></body></html>',
    attachments: [
      { path: './path/to/document.pdf', type: 'application/pdf' },
      { path: './path/to/image.jpg', type: 'image/jpeg' }
    ]
  }
  ```

  ```go Go theme={null}
  params := []sendlayer.Attachment{
    {Path: "./path/to/document.pdf", Type: "application/pdf"},
    {Path: "./path/to/image.jpg", Type: "image/jpeg"},
  }
  ```
</CodeGroup>

## Local and Remote File Attachments

SendLayer SDKs support both local and remote file attachments. For local files, you'll need to provide the path to the file you intend to attach. For remote files, simply provide the URL.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const params = {
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Mixed Attachments',
    html: '<html><body><h1>Files from different sources</h1><p>Attaching both local and remote files.</p></body></html>',
    attachments: [
      {
        path: './local-document.pdf',
        type: 'application/pdf'
      },
      {
        path: 'https://example.com/remote-image.jpg',
        type: 'image/jpeg'
      }
    ]
  };
  ```

  ```python Python theme={null}
  params = {
      "sender": "sender@example.com",
      "to": "recipient@example.com",
      "subject": "Mixed Attachments",
      "html": "<html><body><h1>Files from different sources</h1><p>Attaching both local and remote files.</p></body></html>",
      "attachments": [
          {
              "path": "./local-document.pdf",
              "type": "application/pdf"
          },
          {
              "path": "https://example.com/remote-image.jpg",
              "type": "image/jpeg"
          }
      ]
  }
  ```

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  $sendlayer = new SendLayer('your-api-key');

  $params = [
    'from' => 'sender@example.com',
    'to' => 'recipient@example.com',
    'subject' => 'Mixed Attachments',
    'html' => '<html><body><h1>Files from different sources</h1><p>Attaching both local and remote files.</p></body></html>',
    'attachments' => [
      [ 'path' => './local-document.pdf', 'type' => 'application/pdf' ],
      [ 'path' => 'https://example.com/remote-image.jpg', 'type' => 'image/jpeg' ]
    ]
  ];
  ```

  ```ruby Ruby theme={null}
  params = {
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Mixed Attachments',
    html: '<html><body><h1>Files from different sources</h1><p>Attaching both local and remote files.</p></body></html>',
    attachments: [
      { path: './local-document.pdf', type: 'application/pdf' },
      { path: 'https://example.com/remote-image.jpg', type: 'image/jpeg' }
    ]
  }
  ```

  ```go Go theme={null}
  params := []sendlayer.Attachment{
    {Path: "./local-document.pdf", Type: "application/pdf"},
    {Path: "https://example.com/remote-image.jpg", Type: "image/jpeg"},
  }
  ```
</CodeGroup>

## Supported File Types

SendLayer supports a wide range of file types for attachments. Here are some common MIME types:

* **Documents**: `application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
* **Spreadsheets**: `application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
* **Images**: `image/jpeg`, `image/png`, `image/gif`
* **Text Files**: `text/plain`, `text/csv`
* **Archives**: `application/zip`, `application/x-rar-compressed`

<Note>See our [Send Email guide](/guides/send-email) for basic email sending instructions.</Note>

## FAQ

<AccordionGroup>
  <Accordion title="What is the maximum file size for attachments?">
    The maximum file size per email is **10 MB**, which includes both the email content and all attachments combined. If you need to send larger files, consider using cloud storage services and including download links in your emails.
  </Accordion>

  <Accordion title="How many files can I attach to a single email?">
    You can attach multiple files to a single email, but the total size of all attachments plus the email content must not exceed 10 MB. There is no specific limit on the number of files, only the total size limit.
  </Accordion>

  <Accordion title="What file formats are supported?">
    SendLayer supports most common file formats including PDFs, Word documents, Excel spreadsheets, images (JPEG, PNG, GIF), text files, and compressed archives. The file type should be specified using the appropriate MIME type.
  </Accordion>

  <Accordion title="How do I attach files with the SDK?">
    The SendLayer SDKs handle file encoding automatically. Simply provide the file path (for local files) or URL (for remote files) along with the MIME type. The SDK will read and encode the file for you.
  </Accordion>

  <Accordion title="Can I attach files when sending to multiple recipients?">
    Yes, you can attach files when sending to multiple recipients. The same attachment will be sent to all recipients in the email. See our [Send Email to Multiple Recipients](/guides/send-email-to-multiple-recipients) guide for more details.
  </Accordion>

  <Accordion title="What should I do if my attachment is too large?">
    If your attachment exceeds the 10 MB limit, consider compressing the file, using a cloud storage service and including a download link, or splitting the content into multiple emails with smaller attachments.
  </Accordion>
</AccordionGroup>


# SendLayer MCP Server
Source: https://developers.sendlayer.com/integrations/ai-tools/mcp-server

Learn how to use the SendLayer MCP server to send email and manage webhooks/events directly from AI tools like Cursor and Claude.

## Overview

The SendLayer MCP server exposes tools for sending email and managing webhooks/events using the SendLayer Node.js SDK. You can use it from AI tools like Cursor and Claude to run local scripts, chat with an AI model, and send results to yourself or your team without wiring up HTTP calls manually.

## What Is MCP?

MCP (Model Context Protocol) is a protocol that allows AI tools to interact with external services and data sources. It's a way to extend the capabilities of AI tools by allowing them to use external tools and data sources.

## Tools

* **send-email**: Send a message (plain text or HTML) with CC/BCC, reply-to, tags, headers, and attachments.
* **get-events**: Query events with optional filters.
* **list-webhooks**: List registered webhooks.
* **create-webhook**: Create a webhook.
* **delete-webhook**: Delete a webhook by ID.

## Prerequisites

* A SendLayer account and API key ([get your API key](https://app.sendlayer.com/))
* A verified sending domain ([authorize your domain](https://sendlayer.com/docs/authorizing-your-domain/))
* Cursor or Claude Desktop installed

## Connecting to the MCP Server

The easiest way to get started is to connect to the hosted SendLayer MCP server. No local installation is required.

### Cursor

Use the direct link below to install the MCP server in Cursor:

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=sendlayer\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3Auc2VuZGxheWVyLmNvbSIsImhlYWRlcnMiOnsieC1zZW5kbGF5ZXItYXBpLWtleSI6IllPVVJfU0VORExBWUVSX0FQSV9LRVkifX0%3D)

This will open the MCP server installation page in Cursor. Enter your SendLayer API key and click **Install**.

<img alt="Cursor MCP Server Installation" />

#### Manual Installation

If you're not using the direct link, open the command palette (`cmd`+`shift`+`p` on macOS or `ctrl`+`shift`+`p` on Windows) and choose **Cursor Settings**.

Then, select **Tools & MCP** from the left sidebar and click **New MCP server**.

<img alt="Cursor MCP Server Manual Installation" />

In the `mcp.json` file, add the following config:

```json theme={null}
{
  "mcpServers": {
    "sendlayer": {
      "type": "url",
      "url": "https://mcp.sendlayer.com",
      "headers": {
        "x-sendlayer-api-key": "YOUR_SENDLAYER_API_KEY"
      }
    }
  }
}
```

Be sure to replace `YOUR_SENDLAYER_API_KEY` with your actual SendLayer API key from `app.sendlayer.com`.

After saving the file, restart Cursor and verify the MCP server is connected. You can now use commands like “send an email to [recipient@example.com](mailto:recipient@example.com)” in Agent mode.

### Claude Code

Run the following command on your terminal to configure the MCP server:

```bash theme={null}
claude mcp add --scope user --transport http sendlayer-mcp https://mcp.sendlayer.com --header "Authorization: Bearer YOUR_SENDLAYER_API_KEY"
```

Be sure to replace `YOUR_SENDLAYER_API_KEY` with your actual SendLayer API key.

### Gemini-CLI

Open a terminal and run the following command to edit your `~/.gemini/settings.json` file:

```bash theme={null}
nano ~/.gemini/settings.json
```

Then, add the following lines to the file and save it:

```json theme={null}
{
  "mcpServers": {
    "sendlayer": {
      "httpUrl": "https://mcp.sendlayer.com",
      "headers": {
        "x-sendlayer-api-key": "YOUR_SENDLAYER_API_KEY",
        "Content-Type": "application/json"
      },
      "timeout": 5000
    }
  }
}
```

Be sure to replace `YOUR_SENDLAYER_API_KEY` with your actual SendLayer API key.

To test the connection, run the following command:

```bash theme={null}
gemini mcp list
```

You should see the `sendlayer` server in the list. You can now use the `sendlayer` server to send emails and manage webhooks/events.

### Windsurf

Open your Windsurf settings page. Then select the **Cascade** sidebar menu and click **Open MCP Marketplace**.

<img alt="Windsurf MCP Marketplace" />

Then, click the settings icon to open the `mcp_config.json` file.

<img alt="Windsurf MCP Settings" />

Once the file is open, add the following lines to the file and save it:

```json theme={null}
{
  "mcpServers": {
    "sendlayer": {
      "serverUrl": "https://mcp.sendlayer.com",
      "headers": {
        "x-sendlayer-api-key": "YOUR_SENDLAYER_API_KEY"
      }
    }
  }
}
```

Be sure to replace `YOUR_SENDLAYER_API_KEY` with your actual SendLayer API key.

## Features

* Send plain text and HTML emails
* Send emails with attachments
* Add CC and BCC recipients
* Customize the sender email (verified domains only)
* Create, list, and delete webhooks
* Retrieve and filter email events


# Installation
Source: https://developers.sendlayer.com/quickstart/installation

Learn how to install the SendLayer SDKs

## Overview

This guide shows you how to install the SendLayer SDKs for popular languages so you can start integrating quickly. We currently provide SDKs for Node.js, Python, PHP, Ruby, and Go.

## Prerequisites

Before using the SendLayer API, make sure you've:

* Authorized your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
* Created or retrieved your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Node.js

Install the SendLayer Node.js SDK using your preferred package manager.

<CodeGroup>
  ```bash npm theme={null}
  npm install sendlayer
  ```

  ```bash yarn theme={null}
  yarn add sendlayer
  ```
</CodeGroup>

#### Validate Installation

Create a file (for example, `checkInstall.js`) and run a quick import:

```javascript checkInstall.js theme={null}
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');
console.log('SendLayer initialized:', !!sendlayer);
```

<Note>Replace `'your-api-key'` with your actual API key. See our [Node.js SDK guide](/sdks/nodejs) for full usage examples.</Note>

## Python

Install the SendLayer Python SDK via `pip`:

```bash theme={null}
pip install sendlayer
```

#### Validate Installation

Create a file (for example, `check_install.py`) and run:

```python check_install.py theme={null}
from sendlayer import SendLayer

sendlayer = SendLayer('your-api-key')
print('SendLayer initialized:', bool(sendlayer))
```

<Note>Replace `'your-api-key'` with your actual API key. See our [Python SDK guide](/sdks/python) for full usage examples.</Note>

## PHP

Install the SendLayer PHP SDK with Composer:

```bash theme={null}
composer require sendlayer/sendlayer-php
```

#### Validate Installation

Create a file (for example, `checkInstall.php`) and run:

```php checkInstall.php theme={null}
<?php
require_once 'vendor/autoload.php';

use SendLayer\SendLayer;

$sendlayer = new SendLayer('your-api-key');
echo 'SendLayer initialized: ' . ($sendlayer ? 'true' : 'false');
```

<Note>Replace `'your-api-key'` with your actual API key. See our [PHP SDK guide](/sdks/php) for full usage examples.</Note>

## Ruby

Install the SendLayer Ruby SDK via RubyGems:

```bash theme={null}
gem install sendlayer
```

#### Validate Installation

Create a file (for example, `check_install.rb`) and run:

```ruby check_install.rb theme={null}
require 'sendlayer'

sendlayer = SendLayer::SendLayer.new('your-api-key')
puts "SendLayer initialized: #{!sendlayer.nil?}"
```

<Note>Replace `'your-api-key'` with your actual API key. See our [Ruby SDK guide](/sdks/ruby/send-with-ruby) for full usage examples.</Note>

## Go

Install the SendLayer Go SDK using `go get`:

```bash theme={null}
go get github.com/sendlayer/sendlayer-go
```

#### Validate Installation

Create a file (for example, `check_install.go`) and run:

```go check_install.go theme={null}
package main

import (
	"fmt"
	"github.com/sendlayer/sendlayer-go"
)

func main() {
	sl := sendlayer.New("your-api-key")
	fmt.Println("SendLayer initialized:", sl != nil)
}
```

<Note>Replace `'your-api-key'` with your actual API key. See our [Go SDK guide](/sdks/go/send-with-go) for full usage examples.</Note>

## Next Steps

* Send your first email: [Send Email](/guides/send-email)
* Add attachments: [Send Email with Attachments](/guides/send-email-with-attachments)
* Send to multiple recipients: [Send Email to Multiple Recipients](/guides/send-email-to-multiple-recipients)
* Manage webhooks: [Managing Webhooks](/guides/manage-webhooks)
* Retrieve events: [Retrieving Email Events](/guides/get-events)

## Troubleshooting

* Ensure your environment can make outbound HTTPS requests
* Verify your API key is correct and active
* If installation fails, update your package manager (`npm`, `yarn`, `pip`, or `composer`) and try again
* Check language version requirements (Node.js 16+, Python 3.8+, PHP 7.4+)


# Quickstart
Source: https://developers.sendlayer.com/quickstart/introduction

Learn how to quickly setup and use SendLayer email API to send transactional emails

## Prerequisites

Before you can use the SendLayer API, you'll need to [authorize your sending domain](https://sendlayer.com/docs/authorizing-your-domain/). This is an important step as it proves domain ownership and improves email deliverability.

After authorizing your domain, you'll need to create/retrieve your [API key](https://sendlayer.com/docs/managing-api-keys/). An API key is used to authenticate API requests.

## Installation

Run the command below to install the SendLayer SDK for your preferred programming language:

<CodeGroup>
  ```bash javascript theme={null}
  npm install sendlayer
  ```

  ```bash python theme={null}
  pip install sendlayer
  ```

  ```bash php theme={null}
  composer require sendlayer/sendlayer-php
  ```

  ```bash ruby theme={null}
  gem install sendlayer
  ```

  ```bash go theme={null}
  go get github.com/sendlayer/sendlayer-go
  ```
</CodeGroup>

## Sending an email

Once, you've installed the SDK, you can import it directly into your codebase and interact with the API. Here's an example of how to send an email using the SendLayer API:

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { SendLayer } from 'sendlayer';

  // Initialize the email client
  const sendlayer = new SendLayer('your-api-key');

  const params = {
    from: 'sender@example.com',
    to:'recipient@example.com', // or array of recipients
    subject: 'Test Email',
    text: 'This is a test email'
  }

  // Send a simple email
  const response = await sendlayer.Emails.send(params);
  ```

  ```python Python theme={null}
  from sendlayer import SendLayer

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

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

  ```php PHP theme={null}
  <?php
  require_once 'vendor/autoload.php';

  use SendLayer\SendLayer;

  // Initialize the email client with your API key
  $sendlayer = new SendLayer('your-api-key');

  // Send an email
  $response = $sendlayer->Emails->send([
    'from' => 'sender@example.com',
    'to' => 'recipient@example.com',
    'subject' => 'Test Email',
    'text' => 'This is a test email'
  ]);
  ?>
  ```

  ```ruby Ruby theme={null}
  require 'sendlayer'

  sendlayer = SendLayer::SendLayer.new('your-api-key')

  response = sendlayer.emails.send(
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Test Email',
    text: 'This is a test email'
  )
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"github.com/sendlayer/sendlayer-go"
  )

  func main() {
  	// Initialize the email client with your API key
  	sl := sendlayer.New("your-api-key")

  	// Send an email
  	resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
  		From:    "sender@example.com",
  		To:      "recipient@example.com",
  		Subject: "Test Email",
  		Text:    "This is a test email",
  	})
  	if err != nil {
  		log.Fatal(err)
  	}

  	fmt.Println("Email sent! Message ID:", resp.MessageID)
  }
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://console.sendlayer.com/api/v1/email \
    --header 'Authorization: Bearer <apiKey>' \
    --header 'Content-Type: application/json' \
    --data '{
    "From": {
      "name": "Paulie Paloma",
      "email": "paulie@example.com"
    },
    "To": [
      {
        "name": "Pattie Paloma",
        "email": "pattie@exampledomain.com"
      }
    ],
    "Subject": "This is the email subject",
    "ContentType": "HTML",
    "HTMLContent": "<html><body><p>This is a test email sent with the <a href=\"https://sendlayer.com\">SendLayer</a> API!</p></body></html>"
  }'
  ```
</CodeGroup>

<Warning>If you're using the `cURL` option, make sure to replace `<apiKey>` with your SendLayer API key in the request header.</Warning>

SendLayer API also allows you to send emails to [multiple recipients](/guides/send-email-to-multiple-recipients), include BCC and CC addresses, [attach files](/guides/send-email-with-attachments) to your email messages.

<Note>See our guide to learn more about [sending emails using SendLayer API](/guides/send-email).</Note>

## SDK reference

SendLayer offers SDK libraries for popular programming languages that simplify the process of integrating with the API. We currently offer/support the following SDKs:

<CardGroup>
  <Card title="Node.js" icon="node-js" href="/sdks/nodejs">
    Learn how to use the SendLayer's Node.js SDK
  </Card>

  <Card title="Python" icon="python" href="/sdks/python">
    Learn how to use SendLayer's Python SDK.
  </Card>

  <Card title="PHP" icon="php" href="/sdks/php">
    Learn how to use SendLayer's PHP SDK.
  </Card>

  <Card title="Ruby" icon="gem" href="/sdks/ruby/send-with-ruby">
    Learn how to use SendLayer's Ruby SDK.
  </Card>

  <Card title="Go" icon="golang" href="/sdks/go/send-with-go">
    Learn how to use SendLayer's Go SDK.
  </Card>
</CardGroup>


# Send email with Go
Source: https://developers.sendlayer.com/sdks/go/send-with-go

Learn how to send emails from a Go application using the SendLayer Go SDK.

## Prerequisites

Before getting started, you'll need to:

1. Authorize your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
2. Create and retrieve your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Installation

Install the SendLayer Go SDK using the `go get` command:

```bash theme={null}
go get github.com/sendlayer/sendlayer-go
```

## Usage

After installation, you can use the SDK modules for sending emails, managing webhooks, and retrieving email events.

### Send email in Go

Initialize the client and call `sl.Emails.Send()` with a `SendEmailRequest`.

```go sendEmail.go theme={null}
package main

import (
	"fmt"
	"log"

	"github.com/sendlayer/sendlayer-go"
)

func main() {
	// Initialize the client with your API key
	sl := sendlayer.New("your-api-key")

	// Send an email
	resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
		From:    "sender@example.com",
		To:      "recipient@example.com",
		Subject: "Test Email",
		Text:    "This is a test email",
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Email sent! Message ID:", resp.MessageID)
}
```

#### Send HTML emails in Go

To send HTML emails, set the `Html` field in the request payload.

```go sendEmail.go theme={null}
package main

import (
	"fmt"
	"log"

	"github.com/sendlayer/sendlayer-go"
)

func main() {
	sl := sendlayer.New("your-api-key")

	// Send an HTML email
	resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
		From:    "sender@example.com",
		To:      "recipient@example.com",
		Subject: "Test Email",
		Text:    "Plain text fallback",
		Html:    "<html><body><p>This is a test email sent with the <a href=\"https://sendlayer.com\">SendLayer</a> API!</p></body></html>",
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Email sent! Message ID:", resp.MessageID)
}
```

<Note>You can include both `Text` and `Html` to send plain text and HTML versions of the same email.</Note>

#### Send email to multiple recipients

Use `EmailAddress` objects to send to multiple recipients, including `Cc`, `Bcc`, and `ReplyTo`.

```go sendEmail.go theme={null}
package main

import (
	"fmt"
	"log"

	"github.com/sendlayer/sendlayer-go"
)

func main() {
	sl := sendlayer.New("your-api-key")

	// Send to multiple recipients
	resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
		From: sendlayer.EmailAddress{
			Email: "sender@example.com",
			Name:  "Sender Name",
		},
		To: []sendlayer.EmailAddress{
			{Email: "recipient1@example.com", Name: "Recipient 1"},
			{Email: "recipient2@example.com", Name: "Recipient 2"},
		},
		Subject: "Complex Email",
		Text:    "This is a test email!",
		Html:    "<p>This is a <strong>test email</strong>!</p>",
		Cc:      []sendlayer.EmailAddress{{Email: "cc@example.com", Name: "CC Recipient"}},
		Bcc:     []sendlayer.EmailAddress{{Email: "bcc@example.com", Name: "BCC Recipient"}},
		ReplyTo: sendlayer.EmailAddress{Email: "reply@example.com", Name: "Reply To"},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Email sent! Message ID:", resp.MessageID)
}
```

`From` and `To` accept either a string email or `EmailAddress` values. `Cc`, `Bcc`, and `ReplyTo` support the same flexible format.

<Note>There are limits to the number of email recipients you can add to a single request. See our [rate limiting](/api-reference/rate-limit) guide to learn more.</Note>

#### Include attachments in email

Include attachments by setting the `Attachments` field in `SendEmailRequest`.

```go sendEmail.go theme={null}
package main

import (
	"fmt"
	"log"

	"github.com/sendlayer/sendlayer-go"
)

func main() {
	sl := sendlayer.New("your-api-key")

	// Send email with attachments
	resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
		From: sendlayer.EmailAddress{Email: "sender@example.com", Name: "Sender Name"},
		To: []sendlayer.EmailAddress{
			{Email: "recipient1@example.com", Name: "Recipient"},
		},
		Subject: "Complex Email",
		Text:    "Plain text fallback",
		Html:    "<p>This is a <strong>test email</strong>!</p>",
		Attachments: []sendlayer.Attachment{
			{Path: "path/to/file.pdf", Type: "application/pdf"},
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Email sent! Message ID:", resp.MessageID)
}
```

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

Set `Path` to your local file path or hosted file URL, then set the file `Type` (MIME 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](/guides/send-email-with-attachments).

#### Email request parameters

The table below contains the supported fields in `SendEmailRequest`.

| Field         | Type                                          | Required | Description                                                                         |
| ------------- | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------- |
| `From`        | `string` or `EmailAddress`                    | Yes      | Sender email, as a plain email string or `EmailAddress` (`Email` + optional `Name`) |
| `To`          | `string`, `EmailAddress`, or `[]EmailAddress` | Yes      | Recipient email(s), as one address or multiple addresses                            |
| `Subject`     | `string`                                      | Yes      | Email subject line                                                                  |
| `Text`        | `string`                                      | Yes      | Plain text body                                                                     |
| `Html`        | `string`                                      | No       | HTML body                                                                           |
| `Cc`          | `EmailAddress` or `[]EmailAddress`            | No       | Carbon-copy recipients                                                              |
| `Bcc`         | `EmailAddress` or `[]EmailAddress`            | No       | Blind carbon-copy recipients                                                        |
| `ReplyTo`     | `EmailAddress` or `[]EmailAddress`            | No       | Reply-to recipient(s)                                                               |
| `Attachments` | `[]Attachment`                                | No       | File attachments with `Path` and MIME `Type`                                        |
| `Headers`     | `map[string]string`                           | No       | Custom email headers                                                                |
| `Tags`        | `[]string`                                    | No       | Tags for categorizing emails                                                        |

### Manage webhooks in Go

With the SendLayer Go SDK, you can create, list, and delete webhooks.

#### Create a new webhook

Call `Webhooks.Create()` with a `WebhookCreateRequest`.

```go webhooks.go theme={null}
package main

import (
	"fmt"
	"log"

	"github.com/sendlayer/sendlayer-go"
)

func main() {
	sl := sendlayer.New("your-api-key")

	// Create a webhook
	webhook, err := sl.Webhooks.Create(&sendlayer.WebhookCreateRequest{
		WebhookURL: "https://your-domain.com/webhook",
		Event:      "open",
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Webhook created! ID:", webhook.WebhookID)
}
```

The `Event` field accepts the following values:

* bounce
* click
* open
* unsubscribe
* complaint
* delivery

Example success response for new webhook:

```json theme={null}
{
   "NewWebhookID": 23718
}
```

#### Get all webhooks

To view all the webhooks you've created, use the `Webhooks.Get()` method.

```go webhooks.go theme={null}
package main

import (
	"fmt"
	"log"

	"github.com/sendlayer/sendlayer-go"
)

func main() {
	sl := sendlayer.New("your-api-key")

	// Get all webhooks
	webhooks, err := sl.Webhooks.Get()
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Webhooks:", webhooks)
}
```

Example response:

```json theme={null}
{
  "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"
    }
  ]
}
```

#### Delete a webhook

To delete a specific webhook, pass the webhook ID to `Webhooks.Delete()`.

<Warning>Deleting a webhook cannot be undone.</Warning>

```go webhooks.go theme={null}
package main

import (
	"fmt"
	"log"

	"github.com/sendlayer/sendlayer-go"
)

func main() {
	sl := sendlayer.New("your-api-key")

	// Delete a webhook
	webhookId := 23718
	err := sl.Webhooks.Delete(webhookId)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Webhook deleted successfully")
}
```

#### Webhook request parameters

The table below contains the supported inputs in the `Webhooks` module.

| Parameter    | Type     | Required     | Description                                       |
| ------------ | -------- | ------------ | ------------------------------------------------- |
| `WebhookURL` | `string` | Yes (create) | Webhook endpoint URL where SendLayer sends events |
| `Event`      | `string` | Yes (create) | Event type for the webhook subscription           |
| `webhookId`  | `int`    | Yes (delete) | Unique webhook ID to delete                       |

### Retrieve email events

Use the `Events` module to retrieve email delivery and engagement events.

#### Get all events

Initialize the client and call `Events.Get(nil)` to retrieve recent events.

```go events.go theme={null}
package main

import (
	"fmt"
	"log"

	"github.com/sendlayer/sendlayer-go"
)

func main() {
	sl := sendlayer.New("your-api-key")

	// Get all events
	events, err := sl.Events.Get(nil)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Total events:", events.TotalRecords)
}
```

Example response:

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

#### Filter events

Pass a `GetEventsRequest` to filter by date range and event type.

```go events.go theme={null}
package main

import (
	"fmt"
	"log"
	"time"

	"github.com/sendlayer/sendlayer-go"
)

func main() {
	sl := sendlayer.New("your-api-key")

	// Filter events for the last 24 hours
	endDate := time.Now()
	startDate := endDate.Add(-24 * time.Hour)
	event := "opened"

	events, err := sl.Events.Get(&sendlayer.GetEventsRequest{
		StartDate: &startDate,
		EndDate:   &endDate,
		Event:     event,
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Filtered events:", events.TotalRecords)
}
```

#### Event request parameters

The table below contains supported fields in `GetEventsRequest`.

| Field           | Type         | Required | Description                                  |
| --------------- | ------------ | -------- | -------------------------------------------- |
| `StartDate`     | `*time.Time` | No       | Start date for filtering events              |
| `EndDate`       | `*time.Time` | No       | End date for filtering events                |
| `Event`         | `string`     | No       | Filter by event type (for example, `opened`) |
| `MessageID`     | `string`     | No       | Filter by SendLayer message ID               |
| `StartFrom`     | `*int`       | No       | Starting offset for paginated event results  |
| `RetrieveCount` | `*int`       | No       | Number of records to return                  |

## Error handling

The SDK returns typed errors you can inspect with `errors.As`.

```go theme={null}
package main

import (
	"errors"
	"fmt"
	"log"

	"github.com/sendlayer/sendlayer-go"
)

func main() {
	sl := sendlayer.New("your-api-key")

	resp, err := sl.Emails.Send(&sendlayer.SendEmailRequest{
		From:    "sender@example.com",
		To:      "recipient@example.com",
		Subject: "Test Email",
		Text:    "This is a test email",
	})
	if err != nil {
		var apiErr *sendlayer.SendLayerAPIError
		var valErr *sendlayer.SendLayerValidationError
		if errors.As(err, &apiErr) {
			fmt.Println("API error:", apiErr.Message, apiErr.StatusCode)
			return
		}
		if errors.As(err, &valErr) {
			fmt.Println("Validation error:", valErr.Error())
			return
		}
		fmt.Println("Unexpected error:", err)
		return
	}

	fmt.Println("Email sent! Message ID:", resp.MessageID)
}
```

Here is an example error response:

```bash theme={null}
Error: Invalid event name - 'opened' is not a valid event name
```

## More examples

<Card title="SendLayer Go SDK" icon="github" href="https://github.com/sendlayer/sendlayer-go">
  View more details and examples on GitHub.
</Card>


# Send email with Node.js
Source: https://developers.sendlayer.com/sdks/nodejs/introduction

Learn how to install and use the SendLayer Node.js SDK.

## Prerequisites

Before getting started, you'll need to:

1. Authorize your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
2. Create and retrieve your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Installation

Install the SendLayer Node.js SDK using the command:

<CodeGroup>
  ```bash npm theme={null}
  npm install sendlayer
  ```

  ```bash yarn theme={null}
  yarn add sendlayer
  ```
</CodeGroup>

## 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 `.js` 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.

```javascript sendEmail.js theme={null}
import { SendLayer } from 'sendlayer';

// Initialize the email client with your API key
const sendlayer = new SendLayer('your-api-key');

// Send an email
const response = await sendlayer.Emails.send({
  from: 'sender@example.com',
  to: 'recipient@example.com',
  subject: 'Test Email',
  text: 'This is a test email'
});

console.log('Email sent! Message ID:', response);
```

#### Sending HTML Emails

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

```javascript sendEmail.js theme={null}
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Send an email
const response = await sendlayer.Emails.send({
  from: 'sender@example.com',
  to: 'recipient@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>'
});
```

<Note>You can include the `text` parameter to have a plain text and HTML version of your email message</Note>

#### Sending to Multiple Recipients

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

```javascript sendEmail.js theme={null}
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Send to multiple recipients
const response = await sendlayer.Emails.send({
  from: {email: 'sender@example.com', name: 'Sender Name'},
  to: [
    { email: 'recipient1@example.com', name: 'Recipient 1' },
    { email: 'recipient2@example.com', name: 'Recipient 2' }
  ],
  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' }],
  replyTo: [{ email: 'reply@example.com', name: 'Reply To' }],
});
```

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

<Note>There are limits to the number of email recipients you can add to a single request. See our [rate limiting](/api-reference/rate-limit) guide to learn more.</Note>

#### Including Attachments

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

```javascript sendEmail.js theme={null}
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

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

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

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](/guides/send-email-with-attachments).

#### Email Parameters

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

| Parameter     | Type                 | Required | Description                                                                                                                   |
| ------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `to`          | `string` or `array`  | Yes      | Email address(es) of the recipient(s). Can be a single email string or an array of objects with 'email' and 'name' keys       |
| `from`        | `string` or `object` | Yes      | Email address of the sender. Can be a single email string or an object 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`          | `string` or `array`  | No       | CC email address(es). Can be a single email string or an array of objects containing CC recipient email addresses and names   |
| `bcc`         | `string` or `array`  | No       | BCC email address(es). Can be a single email string or an array of objects containing BCC recipient email addresses and names |
| `replyTo`     | `string` or `array`  | No       | ReplyTo email address. Can be a single email string or an object containing reply-to email address and name                   |
| `tags`        | `array`              | No       | Array of strings for tagging emails                                                                                           |
| `headers`     | `object`             | No       | Object containing custom headers                                                                                              |
| `attachments` | `array`              | No       | Array of objects containing file paths and MIME types for attachments                                                         |

### Managing Webhooks

With the SendLayer Node.js 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.

```javascript webhooks.js theme={null}
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

params = {
  url: 'https://your-domain.com/webhook',
  event: 'open'
}

// Create a webhook
const webhook = await sendlayer.Webhooks.create(params);
```

The `event` parameter is constrained to the following options:

* bounce
* click
* open
* unsubscribe
* complaint
* delivery

Example success response for new webhook:

```json theme={null}
{
   "NewWebhookID": 23718
}
```

#### Getting All Webhooks

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

```javascript webhooks.js theme={null}
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Get all webhooks
const webhooks = await sendlayer.Webhooks.get();
```

Here is an example response:

```json theme={null}
{
  "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 `webhookId` that needs to be a number.

<Danger>Deleting a webhook cannot be undone. You won't be able to recover or access your webhook after deleting it.</Danger>

```javascript webhooks.js theme={null}
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Delete a webhook
const webhookId = 23718;
await sendlayer.Webhooks.delete(webhookId);
```

#### 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 |
| `webhookId` | `number` | 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.

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

```javascript events.js theme={null}
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Get all events
const events = await sendlayer.Events.get();
```

Example response:

```json theme={null}
{
  "totalRecords": 5,
  "events": [
    {
      "Event": "delivered",
      "LoggedAt": 1746340896,
      "LogLevel": "info",
      "Message": {
        "Headers": {
          "MessageId": "06e4491f-fc5a-49cb-bc57-xxxxxx",
          "From": [["", "sender@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:

```javascript events.js theme={null}
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

// Filter events for the last 4 hours
const events = await sendlayer.Events.get({
  startDate: new Date(Date.now() - 4 * 60 * 60 * 1000), // 4 hours ago
  endDate: new Date(), // current time
  event: 'opened'
});
```

#### Events Parameters

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

| Parameter       | Type     | Required | Description                                                                                                                                                             |
| --------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `startDate`     | `Date`   | No       | Start date for filtering events                                                                                                                                         |
| `endDate`       | `Date`   | 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` |
| `messageId`     | `string` | No       | Filter by the email `MessageId`                                                                                                                                         |
| `startFrom`     | `number` | No       | Specify a starting number for the email filter                                                                                                                          |
| `retrieveCount` | `number` | 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 error types (`SendLayerError`, `SendLayerAPIError`) for better error handling. You can use try/catch blocks to handle errors when sending emails:

```javascript theme={null}
import { SendLayer, SendLayerError, SendLayerAPIError } from 'sendlayer';

const sendlayer = new SendLayer('your-api-key');

try {
  const response = await sendlayer.Emails.send({
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Test Email',
    text: 'This is a test email'
  });
} catch (error) {
  if (error.name === 'SendLayerAPIError') {
    console.error('API error:', error.message);
  } else {
    console.error('Error:', error.message);
  }
}
```

Here is an example error response:

```bash theme={null}
Error: Invalid event name - 'opened' is not a valid event name
```

## More Examples

<Card title="SendLayer Node.js SDK" icon="github" href="https://github.com/SendLayer/sendlayer-node">
  View more details and examples on GitHub.
</Card>


# Send email with Express.js
Source: https://developers.sendlayer.com/sdks/nodejs/send-with-expressjs

Learn how to send emails from an Express.js server using the SendLayer Node.js SDK.

## Prerequisites

* Node.js 16 or later
* An Express 4 or Express 5 project
* Authorize your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
* Create or retrieve your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Installation

Install the SDK alongside Express and `dotenv`.

<CodeGroup>
  ```bash npm theme={null}
  npm install express sendlayer dotenv
  ```

  ```bash yarn theme={null}
  yarn add express sendlayer dotenv
  ```

  ```bash pnpm theme={null}
  pnpm add express sendlayer dotenv
  ```
</CodeGroup>

## Storing your API key

Create a `.env` file in your project root and add the key.

```bash .env theme={null}
SENDLAYER_API_KEY=your-api-key
PORT=3000
```

Add `.env` to `.gitignore` so the key never reaches version control.

## Creating the email client

Initialize the client in its own module and export it. A single instance serves every route in the application.

```javascript src/sendlayer.js theme={null}
import 'dotenv/config';
import { SendLayer } from 'sendlayer';

if (!process.env.SENDLAYER_API_KEY) {
  throw new Error('SENDLAYER_API_KEY is not set');
}

export const sendlayer = new SendLayer(process.env.SENDLAYER_API_KEY);
```

The startup check fails fast on a missing key. Without it, the first request would be the place the problem surfaces.

<Note>These examples use ES modules. Add `"type": "module"` to your `package.json`, or convert the imports to `require()` calls if your project uses CommonJS.</Note>

## Sending an email from a route

Add a POST route that reads JSON from the request body and calls `Emails.send()`.

```javascript src/server.js theme={null}
import express from 'express';
import { sendlayer } from './sendlayer.js';

const app = express();
app.use(express.json());

app.post('/api/send-email', async (req, res) => {
  const { name, email, message } = req.body;

  const response = await sendlayer.Emails.send({
    from: { email: 'sender@example.com', name: 'Acme Support' },
    to: [{ email: 'support@example.com', name: 'Support Team' }],
    replyTo: [{ email, name }],
    subject: `New message from ${name}`,
    text: message,
  });

  res.status(200).json({ messageId: response });
});

const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});
```

The `express.json()` middleware parses the request body. Without it, `req.body` is undefined.

<Note>The sender email address must match a domain you have authorized in SendLayer.</Note>

## Validating input before sending

Reject malformed requests before they reach the API. This saves a round trip and returns a clearer error to the caller.

```javascript src/routes/email.js theme={null}
import express from 'express';
import { sendlayer } from '../sendlayer.js';

const router = express.Router();

router.post('/send-email', async (req, res, next) => {
  const { email, subject, message } = req.body;

  if (!email || !subject || !message) {
    return res.status(400).json({
      error: 'The email, subject, and message fields are required.',
    });
  }

  try {
    const response = await sendlayer.Emails.send({
      from: 'sender@example.com',
      to: email,
      subject,
      text: message,
    });

    res.json({ messageId: response });
  } catch (error) {
    next(error);
  }
});

export default router;
```

Mount the router in your application file.

```javascript src/server.js theme={null}
import express from 'express';
import emailRoutes from './routes/email.js';

const app = express();
app.use(express.json());
app.use('/api', emailRoutes);
```

## Sending HTML emails

Add the `html` parameter for rich content. Include `text` as a fallback for clients that block HTML.

```javascript src/routes/welcome.js theme={null}
import express from 'express';
import { sendlayer } from '../sendlayer.js';

const router = express.Router();

router.post('/welcome', async (req, res, next) => {
  try {
    const response = await sendlayer.Emails.send({
      from: { email: 'hello@example.com', name: 'Acme' },
      to: req.body.email,
      subject: 'Welcome to Acme',
      html: `
        <html>
          <body>
            <h1>Welcome aboard</h1>
            <p>Your account is ready. <a href="https://example.com/login">Sign in</a> to get started.</p>
          </body>
        </html>
      `,
      text: 'Your account is ready. Sign in at https://example.com/login to get started.',
      tags: ['welcome-email'],
    });

    res.json({ messageId: response });
  } catch (error) {
    next(error);
  }
});

export default router;
```

The `tags` array labels the message. Tags show up in your event history, which helps you separate welcome emails from other traffic.

## Testing the endpoint

Start the developmentserver.

```bash theme={null}
node src/server.js
```

Then post a request from another terminal using cURL.

```bash theme={null}
curl --request POST \
  --url http://localhost:3000/api/send-email \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Paulie Paloma",
  "email": "paulie@example.com",
  "message": "Testing the send endpoint."
}'
```

A successful request returns the message ID:

```json theme={null}
{
  "messageId": "06e4491f-fc5a-49cb-bc57-xxxxxx"
}
```

Open the **Email logs** page in your SendLayer dashboard to confirm delivery.

## Next steps

<CardGroup>
  <Card title="Node.js SDK Reference" icon="node-js" href="/sdks/nodejs/introduction">
    Review every method and parameter in the Node.js SDK.
  </Card>

  <Card title="Managing Webhooks" icon="webhook" href="/guides/manage-webhooks">
    Create, list, and delete webhook subscriptions.
  </Card>

  <Card title="Retrieving Events" icon="list" href="/guides/get-events">
    Query delivery events for any message.
  </Card>

  <Card title="Rate Limits" icon="clock" href="/api-reference/rate-limit">
    Understand recipient and request limits.
  </Card>
</CardGroup>


# Send Email With Next.js
Source: https://developers.sendlayer.com/sdks/nodejs/send-with-nextjs

Learn how to send emails from a Next.js application using the SendLayer Node.js SDK.

## Prerequisites

* A Next.js project (version 13.4 or later for the App Router)
* Node.js 16 or later
* Authorize your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
* Create or retrieve your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Installation

Install the SendLayer Node.js SDK in your project root.

<CodeGroup>
  ```bash npm theme={null}
  npm install sendlayer
  ```

  ```bash yarn theme={null}
  yarn add sendlayer
  ```

  ```bash pnpm theme={null}
  pnpm add sendlayer
  ```
</CodeGroup>

## Storing your API key

Add your API key to `.env.local` in the project root.

```bash .env.local theme={null}
SENDLAYER_API_KEY=your-api-key
```

<Warning>Never prefix the key with `NEXT_PUBLIC_`. Any variable with that prefix ships to the browser, which exposes your credentials to every visitor.</Warning>

Add `.env.local` to your `.gitignore` file so the key stays out of version control.

## Sending an email from a route handler

Create a Route Handler at `app/api/send-email/route.js`. Next.js runs this file on the server only, so the SDK and your API key remain private.

```javascript app/api/send-email/route.js theme={null}
import { NextResponse } from 'next/server';
import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer(process.env.SENDLAYER_API_KEY);

export async function POST(request) {
  const { name, email, message } = await request.json();

  const response = await sendlayer.Emails.send({
    from: { email: 'sender@example.com', name: 'Acme Support' },
    to: [{ email: 'support@example.com', name: 'Support Team' }],
    replyTo: [{ email, name }],
    subject: `New contact form message from ${name}`,
    text: message,
  });

  return NextResponse.json({ messageId: response }, { status: 200 });
}
```

The `replyTo` field points at the person who filled in the form. Support agents can then reply directly from their inbox.

<Note>Use a `from` address on a domain you authorized in SendLayer. Sending from an unauthorized domain causes the request to fail.</Note>

## Submitting the form from a client component

Create a client component that posts JSON to the route handler.

```javascript app/contact/ContactForm.jsx theme={null}
'use client';

import { useState } from 'react';

export default function ContactForm() {
  const [status, setStatus] = useState('idle');

  async function handleSubmit(event) {
    event.preventDefault();
    setStatus('sending');

    const formData = new FormData(event.currentTarget);

    const response = await fetch('/api/send-email', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        name: formData.get('name'),
        email: formData.get('email'),
        message: formData.get('message'),
      }),
    });

    setStatus(response.ok ? 'sent' : 'error');
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" placeholder="Your name" required />
      <input name="email" type="email" placeholder="Your email" required />
      <textarea name="message" placeholder="Your message" required />
      <button type="submit" disabled={status === 'sending'}>
        {status === 'sending' ? 'Sending…' : 'Send message'}
      </button>
      {status === 'sent' && <p>Message sent.</p>}
      {status === 'error' && <p>Something went wrong. Try again.</p>}
    </form>
  );
}
```

Render the component from a page in `app/contact/page.jsx`.

```javascript app/contact/page.jsx theme={null}
import ContactForm from './ContactForm';

export default function ContactPage() {
  return <ContactForm />;
}
```

## Sending an email from a server action

A server action removes the need for a separate endpoint. Mark the file with `'use server'` and call the SDK inside the action.

```javascript app/actions/sendEmail.js theme={null}
'use server';

import { SendLayer } from 'sendlayer';

const sendlayer = new SendLayer(process.env.SENDLAYER_API_KEY);

export async function sendEmail(formData) {
  const email = formData.get('email');

  await sendlayer.Emails.send({
    from: { email: 'sender@example.com', name: 'Acme' },
    to: email,
    subject: 'Welcome to Acme',
    html: '<p>Thanks for signing up. Your account is ready.</p>',
    text: 'Thanks for signing up. Your account is ready.',
  });

  return { ok: true };
}
```

Pass the action directly to a form. Next.js posts the form data to the server and runs the action there.

```javascript app/signup/page.jsx theme={null}
import { sendEmail } from '../actions/sendEmail';

export default function SignupPage() {
  return (
    <form action={sendEmail}>
      <input name="email" type="email" placeholder="Your email" required />
      <button type="submit">Sign up</button>
    </form>
  );
}
```

## Testing the endpoint

Start the development server.

```bash theme={null}
npm run dev
```

Then post a request to the route handler using cURL.

```bash theme={null}
curl --request POST \
  --url http://localhost:3000/api/send-email \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Paulie Paloma",
  "email": "paulie@example.com",
  "message": "Testing the contact form."
}'
```

A successful request returns the message ID:

```json theme={null}
{
  "messageId": "06e4491f-fc5a-49cb-bc57-xxxxxx"
}
```

Open the **Email logs** page in your SendLayer dashboard to confirm delivery.

## Next steps

<CardGroup>
  <Card title="Node.js SDK Reference" icon="node-js" href="/sdks/nodejs/introduction">
    Review every method and parameter in the Node.js SDK.
  </Card>

  <Card title="Managing Webhooks" icon="webhook" href="/guides/manage-webhooks">
    Track opens, clicks, and bounces with webhooks.
  </Card>

  <Card title="Retrieving Events" icon="list" href="/guides/get-events">
    Query delivery events for any message.
  </Card>

  <Card title="Rate Limits" icon="clock" href="/api-reference/rate-limit">
    Understand recipient and request limits.
  </Card>
</CardGroup>


# Send email with Nuxt
Source: https://developers.sendlayer.com/sdks/nodejs/send-with-nuxt

Learn how to send emails from a Nuxt application using the SendLayer Node.js SDK.

## Prerequisites

* A Nuxt 3 or Nuxt 4 project
* Node.js 18 or later
* Authorize your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
* Create or retrieve your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Installation

Install the SDK in your project root.

<CodeGroup>
  ```bash npm theme={null}
  npm install sendlayer
  ```

  ```bash yarn theme={null}
  yarn add sendlayer
  ```

  ```bash pnpm theme={null}
  pnpm add sendlayer
  ```
</CodeGroup>

## Storing your API key

Nuxt reads private values through `runtimeConfig`. Declare the key at the top level of the config object so it stays on the server.

```javascript nuxt.config.ts theme={null}
export default defineNuxtConfig({
  runtimeConfig: {
    // Server-only. Set through NUXT_SENDLAYER_API_KEY at runtime.
    sendlayerApiKey: '',

    public: {
      // Values here are exposed to the browser. Keep the API key out.
      supportEmail: 'support@example.com',
    },
  },
});
```

Add the matching environment variable to `.env`. Nuxt maps `NUXT_SENDLAYER_API_KEY` onto `runtimeConfig.sendlayerApiKey` automatically.

```bash .env theme={null}
NUXT_SENDLAYER_API_KEY=your-api-key
```

<Warning>Keys placed under `runtimeConfig.public` ship to the browser. Only the top-level section stays private to the server.</Warning>

## Sending an email from a server route

Create a server route in `server/api/send-email.post.js`. The `.post` suffix restricts the handler to POST requests.

```javascript server/api/send-email.post.js theme={null}
import { SendLayer } from 'sendlayer';

export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event);
  const sendlayer = new SendLayer(config.sendlayerApiKey);

  const { name, email, message } = await readBody(event);

  const response = await sendlayer.Emails.send({
    from: { email: 'sender@example.com', name: 'Acme Support' },
    to: [{ email: 'support@example.com', name: 'Support Team' }],
    replyTo: [{ email, name }],
    subject: `New message from ${name}`,
    text: message,
  });

  return { messageId: response };
});
```

`readBody()` parses the incoming JSON payload, and `useRuntimeConfig(event)` reads the private key at request time.

<Note>Use a `from` address on a domain you authorized in SendLayer. Requests from an unauthorized domain fail.</Note>

## Reusing the client across routes

Create the client once in a server utility. Nitro auto-imports anything under `server/utils`, so the helper is available in every route without an import statement.

```javascript server/utils/sendlayer.js theme={null}
import { SendLayer } from 'sendlayer';

let client;

export function useSendLayer(event) {
  if (!client) {
    const config = useRuntimeConfig(event);

    if (!config.sendlayerApiKey) {
      throw new Error('NUXT_SENDLAYER_API_KEY is not set');
    }

    client = new SendLayer(config.sendlayerApiKey);
  }

  return client;
}
```

Call the helper from any server route:

```javascript server/api/welcome.post.js theme={null}
export default defineEventHandler(async (event) => {
  const sendlayer = useSendLayer(event);
  const { email } = await readBody(event);

  const response = await sendlayer.Emails.send({
    from: { email: 'hello@example.com', name: 'Acme' },
    to: email,
    subject: 'Welcome to Acme',
    html: '<p>Your account is ready. <a href="https://example.com/login">Sign in</a> to get started.</p>',
    text: 'Your account is ready. Sign in at https://example.com/login to get started.',
    tags: ['welcome-email'],
  });

  return { messageId: response };
});
```

## Calling the route from a Vue page

Use `$fetch` to post the form data. Nuxt sets the JSON content type when the body is an object.

```vue pages/contact.vue theme={null}
<script setup>
const form = reactive({ name: '', email: '', message: '' });
const status = ref('idle');

async function submit() {
  status.value = 'sending';

  try {
    await $fetch('/api/send-email', {
      method: 'POST',
      body: form,
    });
    status.value = 'sent';
  } catch (error) {
    status.value = 'error';
  }
}
</script>

<template>
  <form @submit.prevent="submit">
    <input v-model="form.name" placeholder="Your name" required />
    <input v-model="form.email" type="email" placeholder="Your email" required />
    <textarea v-model="form.message" placeholder="Your message" required />
    <button type="submit" :disabled="status === 'sending'">
      {{ status === 'sending' ? 'Sending…' : 'Send message' }}
    </button>
    <p v-if="status === 'sent'">Message sent.</p>
    <p v-if="status === 'error'">Something went wrong. Try again.</p>
  </form>
</template>
```

<Tip>Use `$fetch` for user-triggered actions such as form submissions. Reserve `useFetch` for data you load when the page renders.</Tip>

## Testing the route

Start the development development server.

```bash theme={null}
npm run dev
```

Then post a request from another terminal using cURL.

```bash theme={null}
curl --request POST \
  --url http://localhost:3000/api/send-email \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Paulie Paloma",
  "email": "paulie@example.com",
  "message": "Testing the Nuxt server route."
}'
```

A successful request returns the message ID:

```json theme={null}
{
  "messageId": "06e4491f-fc5a-49cb-bc57-xxxxxx"
}
```

Open the **Email logs** page in your SendLayer dashboard to confirm delivery.

## Next Steps

<CardGroup>
  <Card title="Node.js SDK Reference" icon="node-js" href="/sdks/nodejs/introduction">
    Review every method and parameter in the Node.js SDK.
  </Card>

  <Card title="Managing Webhooks" icon="webhook" href="/guides/manage-webhooks">
    Track opens, clicks, and bounces with webhooks.
  </Card>

  <Card title="Retrieving Events" icon="list" href="/guides/get-events">
    Query delivery events for any message.
  </Card>

  <Card title="Rate Limits" icon="clock" href="/api-reference/rate-limit">
    Understand recipient and request limits.
  </Card>
</CardGroup>


# Send email with PHP
Source: https://developers.sendlayer.com/sdks/php/introduction

Learn how to install and use the SendLayer PHP SDK.

## Prerequisites

Before getting started, you'll need to:

1. Authorize your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
2. Create and retrieve your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Installation

Install the SendLayer PHP SDK using Composer:

```bash theme={null}
composer require sendlayer/sendlayer-php
```

## Usage

After installation, you're ready to integrate the SDK into your code. The SDK includes modules for sending emails, managing webhooks, and retrieving events.

### Sending an Email

Create or edit a `.php` file. Then import and initialize the client with your API key.

```php SendEmail.php theme={null}
<?php
require_once 'vendor/autoload.php';

use SendLayer\SendLayer;

// Initialize the email client with your API key
$sendlayer = new SendLayer('your-api-key');

// Send an email
$response = $sendlayer->Emails->send([
    'from' => 'sender@example.com',
    'to' => 'recipient@example.com',
    'subject' => 'Test Email',
    'text' => 'This is a test email'
]);

```

#### Sending HTML Emails

To send HTML emails, include the `html` parameter when calling `send()`.

```php SendEmail.php theme={null}
$response = $sendlayer->Emails->send([
    'from' => 'sender@example.com',
    'to' => 'recipient@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>"
]);
```

<Note>You can include the `text` parameter to provide both plain text and HTML versions of your email.</Note>

#### Sending to Multiple Recipients

You can send emails to multiple recipients and include CC/BCC addresses.

```php SendEmail.php theme={null}
$response = $sendlayer->Emails->send([
    'from' => ['email' => 'sender@example.com', 'name' => 'Sender Name'],
    'to' => [
        ['email' => 'recipient1@example.com', 'name' => 'Recipient 1'],
        ['email' => 'recipient2@example.com', 'name' => 'Recipient 2']
    ],
    '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']],
    'replyTo' => [['email' => 'reply@example.com', 'name' => 'Reply To']]
]);
```

Each recipient field is an array of objects containing the recipient's `name` and `email`.

<Note>There are limits to the number of recipients you can add to a single request. See our [rate limiting](/api-reference/rate-limit) guide to learn more.</Note>

#### Including Attachments

You can add attachments by including the `attachments` parameter in the payload.

```php SendEmail.php theme={null}
$response = $sendlayer->Emails->send([
    'from' => ['email' => 'sender@example.com', 'name' => 'Sender Name'],
    'to' => [ ['email' => 'recipient1@example.com', 'name' => 'Recipient'] ],
    'subject' => 'Document attached',
    'html' => '<p>See attached file.</p>',
    'attachments' => [
        [
            'path' => '/path/to/document.pdf',
            'type' => 'application/pdf'
        ],
        [
            'path' => 'https://example.com/image.jpg',
            'type' => 'image/jpeg'
        ]
    ]
]);
```

<Warning>The maximum email size allowed is 10MB. This includes the message and all attachments.</Warning>

#### Email Parameters

Below are the supported parameters for sending emails with the PHP SDK.

| Parameter     | Type                | Required | Description                                                                                                  |
| ------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `to`          | `string` or `array` | Yes      | Email address(es) of the recipient(s). Can be a single string or an array of objects with `email` and `name` |
| `from`        | `string` or `array` | Yes      | Email address of the sender. Can be a single string or an object with `email` and `name`                     |
| `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`          | `array`             | No       | Array of objects for CC recipients                                                                           |
| `bcc`         | `array`             | No       | Array of objects for BCC recipients                                                                          |
| `replyTo`     | `array`             | No       | Array of objects for reply-to addresses                                                                      |
| `attachments` | `array`             | No       | Array of objects with file `path` and MIME `type`                                                            |
| `tags`        | `array`             | No       | Array of strings used to tag emails                                                                          |
| `headers`     | `array`             | No       | Associative array of custom headers                                                                          |

### Managing Webhooks

With the PHP SDK, you can create webhooks, retrieve them, and delete a specific webhook.

#### Creating a New Webhook

Initialize the client and call `Webhooks->create()` with required parameters `url` and `event`.

```php Webhooks.php theme={null}
<?php
require_once 'vendor/autoload.php';

use SendLayer\SendLayer;

$sendlayer = new SendLayer('your-api-key');

// Create a webhook
$webhook = $sendlayer->Webhooks->create([
    'url' => 'https://your-domain.com/webhook',
    'event' => 'open'
]);
```

The `event` parameter accepts the following options:

* bounce
* click
* open
* unsubscribe
* complaint
* delivery

Example success response for a new webhook:

```json theme={null}
{ "NewWebhookID": 23718 }
```

#### Getting All Webhooks

Use `Webhooks->get()` to view all webhooks you've created.

```php Webhooks.php theme={null}
$webhooks = $sendlayer->Webhooks->get();
```

Example response:

```json theme={null}
{
  "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

Use `Webhooks->delete()` with the numeric `webhookId`.

<Danger>Deleting a webhook cannot be undone.</Danger>

```php Webhooks.php theme={null}
$webhookId = 23718;
$sendlayer->Webhooks->delete($webhookId);
```

#### 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 |
| `webhookId` | `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

Initialize the client and call `Events->get()` to retrieve events.

<Note>The `Events->get()` method retrieves the top 5 events if no filters are specified.</Note>

```php Events.php theme={null}
<?php
require_once 'vendor/autoload.php';

use SendLayer\SendLayer;

$sendlayer = new SendLayer('your-api-key');

// Get all events
$events = $sendlayer->Events->get();
```

Example response:

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

#### Filtering Events

You can filter events by date range, event type, message ID, and pagination options.

```php Events.php theme={null}
// Filter events for the last 4 hours
$events = $sendlayer->Events->get([
    'startDate' => new DateTime('-4 hours'),
    'endDate' => new DateTime('now'),
    'event' => 'opened'
]);
```

#### Events Parameters

The table below lists available parameters in the `Events` module.

| Parameter       | Type                | Required | Description                                                                                                                       |
| --------------- | ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `startDate`     | `DateTime` or `int` | No       | Start date for filtering events (Unix timestamp or DateTime)                                                                      |
| `endDate`       | `DateTime` or `int` | No       | End date for filtering events (Unix timestamp or DateTime)                                                                        |
| `event`         | `string`            | No       | Filter by event type. Supported: `accepted`, `rejected`, `delivered`, `opened`, `clicked`, `unsubscribed`, `complained`, `failed` |
| `messageId`     | `string`            | No       | Filter by the email `MessageId`                                                                                                   |
| `startFrom`     | `integer`           | No       | Starting position for pagination                                                                                                  |
| `retrieveCount` | `integer`           | No       | Number of event records to retrieve (defaults to 5)                                                                               |

## Error Handling

Use try/catch blocks to handle SDK errors. The SDK provides specific exception types for different failure scenarios.

```php SendEmail.php theme={null}
<?php
require_once 'vendor/autoload.php';

use SendLayer\Exceptions\SendLayerAPIException;
use SendLayer\Exceptions\SendLayerException;

try {
    $response = $sendlayer->Emails->send([ /* ... */ ]);
} catch (SendLayerAPIException $e) {
    // API-specific error with status code and response data
    echo 'API error: ' . $e->getStatusCode() . ' - ' . $e->getMessage();
} catch (SendLayerException $e) {
    // Other SDK errors (validation, auth, network, etc.)
    echo 'Error: ' . $e->getMessage();
}
```

Here is an example error response:

```bash theme={null}
Error: Invalid event name - 'opened' is not a valid event name
```

## Exception Types

* `SendLayerException`: Base exception for all SendLayer errors
* `SendLayerAuthenticationException`: Invalid API key or authentication issues
* `SendLayerValidationException`: Invalid parameters or validation errors
* `SendLayerAPIException`: API-specific errors with status code and response data

## More Examples

<Card title="SendLayer PHP SDK" icon="github" href="https://github.com/SendLayer/sendlayer-php">
  View more details and examples on GitHub.
</Card>


# Send email with Laravel
Source: https://developers.sendlayer.com/sdks/php/send-with-laravel

Learn how to send emails from a Laravel application using the SendLayer PHP SDK.

## Prerequisites

Before getting started, you'll need to:

1. Authorize your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
2. Create and retrieve your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Installation

Install the SendLayer PHP SDK using Composer:

```bash theme={null}
composer require sendlayer/sendlayer-php
```

## Storing your API key

Create a `.env` file in your project root and add your API key:

```bash .env theme={null}
SENDLAYER_API_KEY=your-api-key
SENDLAYER_FROM_ADDRESS=sender@example.com
SENDLAYER_FROM_NAME="Acme Support"
```

Read those values through a config file rather than calling `env()` from application code. Config caching in production returns `null` for direct `env()` calls outside config files.

```php config/sendlayer.php theme={null}
<?php

return [
    'api_key' => env('SENDLAYER_API_KEY'),

    'from' => [
        'email' => env('SENDLAYER_FROM_ADDRESS', 'sender@example.com'),
        'name' => env('SENDLAYER_FROM_NAME', 'Acme'),
    ],
];
```

<Warning>Calling `env()` outside a config file breaks after you run `php artisan config:cache`. Use `config('sendlayer.api_key')` in controllers, jobs, and services.</Warning>

## Registering the client in the container

Bind the client as a singleton in `AppServiceProvider`. Laravel then builds one instance per request lifecycle and injects it wherever you type-hint it.

```php app/Providers/AppServiceProvider.php theme={null}
<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use SendLayer\SendLayer;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(SendLayer::class, function () {
            $apiKey = config('sendlayer.api_key');

            if (empty($apiKey)) {
                throw new \RuntimeException('SENDLAYER_API_KEY is not set');
            }

            return new SendLayer($apiKey);
        });
    }
}
```

The check throws on a missing key at resolution time, which surfaces the problem before an API request goes out.

## Sending an email from a controller

Type-hint the client in the constructor. Laravel resolves it from the container automatically.

```php app/Http/Controllers/ContactController.php theme={null}
<?php

namespace App\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use SendLayer\SendLayer;

class ContactController extends Controller
{
    public function __construct(private SendLayer $sendlayer)
    {
    }

    public function store(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'name' => ['required', 'string', 'max:100'],
            'email' => ['required', 'email'],
            'message' => ['required', 'string', 'max:5000'],
        ]);

        $response = $this->sendlayer->Emails->send([
            'from' => config('sendlayer.from'),
            'to' => [['email' => 'support@example.com', 'name' => 'Support Team']],
            'replyTo' => [['email' => $validated['email'], 'name' => $validated['name']]],
            'subject' => "New message from {$validated['name']}",
            'text' => $validated['message'],
        ]);

        return response()->json(['message_id' => $response]);
    }
}
```

Laravel's `validate()` method rejects malformed payloads with a `422` response before the SDK runs. The `replyTo` field points at the person who filled in the form, so support agents can reply from their inbox.

Add the route:

```php routes/api.php theme={null}
use App\Http\Controllers\ContactController;
use Illuminate\Support\Facades\Route;

Route::post('/contact', [ContactController::class, 'store']);
```

<Note>Use a `from` address on a domain you authorized in SendLayer. Requests from an unauthorized domain fail.</Note>

## Rendering email bodies with Blade

Blade views give you layouts, components, and partials.

```blade resources/views/emails/welcome.blade.php theme={null}
<h1>Welcome, {{ $name }}</h1>
<p>Your {{ $plan }} plan is active.</p>
<p><a href="{{ $loginUrl }}">Sign in to your account</a></p>
```

Render a view to a string with the `view()` helper, then pass the result as the `html` parameter.

```php app/Jobs/SendWelcomeEmail.php theme={null}
<?php

namespace App\Jobs;

use App\Models\User;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\SerializesModels;
use SendLayer\SendLayer;

class SendWelcomeEmail implements ShouldQueue
{
    use Dispatchable, SerializesModels;

    public function __construct(private User $user)
    {
    }

    public function handle(SendLayer $sendlayer): void
    {
        $html = view('emails.welcome', [
            'name' => $this->user->name,
            'plan' => $this->user->plan,
            'loginUrl' => route('login'),
        ])->render();

        $sendlayer->Emails->send([
            'from' => config('sendlayer.from'),
            'to' => [['email' => $this->user->email, 'name' => $this->user->name]],
            'subject' => "Welcome, {$this->user->name}",
            'html' => $html,
            'text' => "Welcome, {$this->user->name}. Sign in at " . route('login'),
            'tags' => ['welcome-email'],
        ]);
    }
}
```

The `tags` array labels the message. Tags appear in your event history, which helps you separate welcome emails from other traffic.

<Tip>Keep email views in their own directory. Email clients support a narrow subset of CSS, so those templates rarely share styles with your web pages.</Tip>

## Testing the endpoint

Start the development server:

```bash theme={null}
php artisan serve
```

Then post a request from another terminal:

```bash theme={null}
curl --request POST \
  --url http://localhost:8000/api/contact \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "name": "Paulie Paloma",
  "email": "paulie@example.com",
  "message": "Testing the contact endpoint."
}'
```

A successful request returns the message ID:

```json theme={null}
{
  "message_id": "06e4491f-fc5a-49cb-bc57-xxxxxx"
}
```

<Note>Include the `Accept: application/json` header. Without it, Laravel returns validation errors as a redirect rather than JSON.</Note>

Open the **Email logs** page in your SendLayer dashboard to confirm delivery.

## Next steps

<CardGroup>
  <Card title="PHP SDK Reference" icon="php" href="/sdks/php/introduction">
    Review every method and parameter in the PHP SDK.
  </Card>

  <Card title="Managing Webhooks" icon="webhook" href="/guides/manage-webhooks">
    Create, list, and delete webhook subscriptions.
  </Card>

  <Card title="Retrieving Events" icon="list" href="/guides/get-events">
    Query delivery events for any message.
  </Card>

  <Card title="Rate Limits" icon="clock" href="/api-reference/rate-limit">
    Understand recipient and request limits.
  </Card>
</CardGroup>


# Send email with Python
Source: https://developers.sendlayer.com/sdks/python/introduction

Learn how to install and use the SendLayer Python SDK.

## Prerequisites

Before getting started, you'll need to:

1. Authorize your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
2. Create and retrieve your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Installation

Install the SendLayer Python SDK using `pip`.

```bash theme={null}
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.

```python send_email.py theme={null}
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.

```python send_email.py theme={null}
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>"
)
```

<Note>You can include the `text` parameter to have a plain text and HTML version of your email message</Note>

#### Sending to multiple recipients

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

```python send_email.py theme={null}
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.

<Note>There are limits to the number of email recipients you can add to a single request. See our [rate limiting](/api-reference/rate-limit) guide to learn more.</Note>

#### Including attachments

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

```python send_email.py theme={null}
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',
    }]
)
```

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

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](/guides/send-email-with-attachments).

#### 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.

```python webhooks.py theme={null}
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:

```json theme={null}
{
   "NewWebhookID": 23718
}
```

#### Getting all webhooks

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

```python webhooks.py theme={null}
from sendlayer import SendLayer

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

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

Here is an example response:

```json theme={null}
{
  "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.

<Danger> Deleting a webhook cannot be undone. You won't be able to recover or access your webhook after deleting it.</Danger>

```python webhooks.py theme={null}
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.

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

```python events.py theme={null}
from sendlayer import SendLayer

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

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

Example response

```json theme={null}
{
  "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:

```python events.py theme={null}
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:

```python theme={null}
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:

```bash theme={null}
Error: Invalid event name - 'opened' is not a valid event name
```

## More examples

<Card title="SendLayer Python SDK" icon="github" href="https://github.com/SendLayer/sendlayer-python">
  View more details and examples on GitHub.
</Card>


# Send email with FastAPI
Source: https://developers.sendlayer.com/sdks/python/send-with-fastapi

Learn how to send emails from a FastAPI application using the SendLayer Python SDK.

## Prerequisites

* Python 3.8 or later
* A FastAPI project with an ASGI server such as Uvicorn
* Authorize your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
* Create or retrieve your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Installation

Install the SDK along with FastAPI, Uvicorn, and `pydantic-settings`.

```bash theme={null}
pip install fastapi "uvicorn[standard]" sendlayer pydantic-settings
```

## Storing your API key

Create a `.env` file in your project root.

```bash .env theme={null}
SENDLAYER_API_KEY=your-api-key
```

Load the value through a settings class. Pydantic raises an error at startup if the key is missing, which surfaces the problem before any request arrives.

```python app/config.py theme={null}
from functools import lru_cache

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env")

    sendlayer_api_key: str


@lru_cache
def get_settings() -> Settings:
    return Settings()
```

Add `.env` to `.gitignore` so the key stays out of version control.

## Creating the email client

Wrap the client in a cached factory. `lru_cache` returns the same instance on every call, which makes it a clean FastAPI dependency.

```python app/email_client.py theme={null}
from functools import lru_cache

from sendlayer import SendLayer

from app.config import get_settings


@lru_cache
def get_sendlayer() -> SendLayer:
    settings = get_settings()
    return SendLayer(settings.sendlayer_api_key)
```

## Defining the request model

Pydantic validates the payload before your code runs. `EmailStr` rejects malformed addresses, and `min_length` blocks empty fields.

```python app/schemas.py theme={null}
from pydantic import BaseModel, EmailStr, Field


class ContactRequest(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    email: EmailStr
    message: str = Field(min_length=1, max_length=5000)


class SendResponse(BaseModel):
    message_id: str
```

<Note>`EmailStr` requires the `email-validator` package. Install it with `pip install "pydantic[email]"` if it is not already present.</Note>

## Sending an email from an endpoint

Declare the endpoint with `def` rather than `async def`. FastAPI then runs it in a thread pool, so the synchronous SDK call never blocks the event loop.

```python app/main.py theme={null}
from fastapi import Depends, FastAPI
from sendlayer import SendLayer

from app.email_client import get_sendlayer
from app.schemas import ContactRequest, SendResponse

app = FastAPI(title="Acme Email API")


@app.post("/api/send-email", response_model=SendResponse)
def send_email(
    payload: ContactRequest,
    sendlayer: SendLayer = Depends(get_sendlayer),
):
    response = sendlayer.Emails.send(
        sender={"email": "sender@example.com", "name": "Acme Support"},
        to=[{"email": "support@example.com", "name": "Support Team"}],
        reply_to=[{"email": payload.email, "name": payload.name}],
        subject=f"New message from {payload.name}",
        text=payload.message,
    )

    return SendResponse(message_id=response)
```

<Warning>Do not call the SDK from an `async def` endpoint. The call is blocking, which stalls every other request handled by that worker.</Warning>

The `reply_to` field points at the person who filled in the form, so support agents can reply from their inbox.

<Note>Use a `sender` address on a domain you authorized in SendLayer. Requests from an unauthorized domain fail.</Note>

Start the server:

```bash theme={null}
uvicorn app.main:app --reload
```

## Sending in the background

For endpoints where the caller does not need the message ID, hand the send to `BackgroundTasks`. FastAPI returns the response first and runs the task afterward.

```python app/routers/signup.py theme={null}
from fastapi import APIRouter, BackgroundTasks, Depends, status
from pydantic import BaseModel, EmailStr
from sendlayer import SendLayer

from app.email_client import get_sendlayer

router = APIRouter(prefix="/api", tags=["signup"])


class SignupRequest(BaseModel):
    name: str
    email: EmailStr


def send_welcome_email(sendlayer: SendLayer, name: str, email: str) -> None:
    sendlayer.Emails.send(
        sender={"email": "hello@example.com", "name": "Acme"},
        to=email,
        subject=f"Welcome, {name}",
        html=(
            "<html><body>"
            f"<h1>Welcome, {name}</h1>"
            "<p>Your account is ready. "
            "<a href='https://example.com/login'>Sign in</a> to get started.</p>"
            "</body></html>"
        ),
        text=f"Welcome, {name}. Sign in at https://example.com/login to get started.",
        tags=["welcome-email"],
    )


@router.post("/signup", status_code=status.HTTP_202_ACCEPTED)
def signup(
    payload: SignupRequest,
    background_tasks: BackgroundTasks,
    sendlayer: SendLayer = Depends(get_sendlayer),
):
    background_tasks.add_task(send_welcome_email, sendlayer, payload.name, payload.email)
    return {"status": "accepted"}
```

Include the router in your application:

```python app/main.py theme={null}
from fastapi import FastAPI

from app.routers import signup

app = FastAPI(title="Acme Email API")
app.include_router(signup.router)
```

<Tip>Background tasks run in the same process. For high volume or retry logic, move sends to a dedicated queue such as Celery or Dramatiq.</Tip>

## Testing the endpoint

Start the server, then post a request from another terminal.

```bash theme={null}
uvicorn app.main:app --reload
```

```bash theme={null}
curl --request POST \
  --url http://localhost:8000/api/send-email \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Paulie Paloma",
  "email": "paulie@example.com",
  "message": "Testing the FastAPI endpoint."
}'
```

A successful request returns the message ID:

```json theme={null}
{
  "message_id": "06e4491f-fc5a-49cb-bc57-xxxxxx"
}
```

You can also open `http://localhost:8000/docs` and send the request from the generated Swagger interface.

<Check>Open the **Email Logs** page in your SendLayer dashboard to confirm delivery.</Check>

## Next Steps

<CardGroup>
  <Card title="Python SDK Reference" icon="python" href="/sdks/python/introduction">
    Review every method and parameter in the Python SDK.
  </Card>

  <Card title="Managing Webhooks" icon="webhook" href="/guides/manage-webhooks">
    Create, list, and delete webhook subscriptions.
  </Card>

  <Card title="Retrieving Events" icon="list" href="/guides/get-events">
    Query delivery events for any message.
  </Card>

  <Card title="Rate Limits" icon="clock" href="/api-reference/rate-limit">
    Understand recipient and request limits.
  </Card>
</CardGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why is the parameter called sender instead of from?">
    `from` is a reserved keyword in Python, so it cannot be a keyword argument. The Python SDK uses `sender` for the sending address.
  </Accordion>

  <Accordion title="Why does my endpoint return a 422 error?">
    Pydantic rejected the payload. The response body lists each failing field, so check that the request matches your request model.
  </Accordion>

  <Accordion title="How do I keep the API key out of the code?">
    Load it from the environment through a `Settings` class. Uvicorn reads the process environment, so hosting platforms can inject the value at deploy time.
  </Accordion>
</AccordionGroup>


# Send email with Flask
Source: https://developers.sendlayer.com/sdks/python/send-with-flask

Learn how to send emails from a Flask application using the SendLayer Python SDK.

## Prerequisites

* Python 3.8 or later
* A Flask 2 or Flask 3 project
* Authorize your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
* Create or retrieve your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Installation

Install the SDK along with Flask and `python-dotenv`.

```bash theme={null}
pip install flask sendlayer python-dotenv
```

## Storing your API key

Create a `.env` file in your project root.

```bash .env theme={null}
SENDLAYER_API_KEY=your-api-key
FLASK_APP=app
```

Add `.env` to `.gitignore` so the key stays out of version control.

## Creating the email client

Initialize the client once when the application starts and share it across routes. A module-level instance avoids rebuilding the client on every request.

```python app/email_client.py theme={null}
import os

from dotenv import load_dotenv
from sendlayer import SendLayer

load_dotenv()

api_key = os.environ.get("SENDLAYER_API_KEY")

if not api_key:
    raise RuntimeError("SENDLAYER_API_KEY is not set")

sendlayer = SendLayer(api_key)
```

The startup check fails fast on a missing key. Without it, the first request becomes the place the problem surfaces.

## Sending an email from a route

Add a POST route that reads JSON and calls `Emails.send()`.

```python app/__init__.py theme={null}
from flask import Flask, jsonify, request

from app.email_client import sendlayer


def create_app():
    app = Flask(__name__)

    @app.post("/api/send-email")
    def send_email():
        data = request.get_json()

        response = sendlayer.Emails.send(
            sender={"email": "sender@example.com", "name": "Acme Support"},
            to=[{"email": "support@example.com", "name": "Support Team"}],
            reply_to=[{"email": data["email"], "name": data["name"]}],
            subject=f"New message from {data['name']}",
            text=data["message"],
        )

        return jsonify({"message_id": response}), 200

    return app
```

The `reply_to` field points at the person who filled in the form, so support agents can reply from their inbox.

<Note>Use a `sender` address on a domain you authorized in SendLayer. Requests from an unauthorized domain fail.</Note>

Run the application:

```bash theme={null}
flask run
```

## Organizing routes with a blueprint

A blueprint keeps email routes separate from the rest of the application. This structure scales better once you add more endpoints.

```python app/routes/email.py theme={null}
from flask import Blueprint, jsonify, request

from app.email_client import sendlayer

email_bp = Blueprint("email", __name__, url_prefix="/api")


@email_bp.post("/send-email")
def send_email():
    data = request.get_json(silent=True) or {}

    missing = [field for field in ("email", "subject", "message") if not data.get(field)]
    if missing:
        return jsonify({"error": f"Missing required fields: {', '.join(missing)}"}), 400

    response = sendlayer.Emails.send(
        sender="sender@example.com",
        to=data["email"],
        subject=data["subject"],
        text=data["message"],
    )

    return jsonify({"message_id": response})
```

Register the blueprint in your factory:

```python app/__init__.py theme={null}
from flask import Flask

from app.routes.email import email_bp


def create_app():
    app = Flask(__name__)
    app.register_blueprint(email_bp)
    return app
```

Validating the payload first saves a round trip to the API and returns a clearer error to the caller.

## Sending HTML emails

Add the `html` parameter for rich content. Keep `text` as a fallback for clients that block HTML.

```python app/routes/welcome.py theme={null}
from flask import Blueprint, jsonify, request

from app.email_client import sendlayer

welcome_bp = Blueprint("welcome", __name__, url_prefix="/api")


@welcome_bp.post("/welcome")
def send_welcome_email():
    data = request.get_json()

    response = sendlayer.Emails.send(
        sender={"email": "hello@example.com", "name": "Acme"},
        to=data["email"],
        subject="Welcome to Acme",
        html=(
            "<html><body>"
            "<h1>Welcome aboard</h1>"
            "<p>Your account is ready. "
            "<a href='https://example.com/login'>Sign in</a> to get started.</p>"
            "</body></html>"
        ),
        text="Your account is ready. Sign in at https://example.com/login to get started.",
        tags=["welcome-email"],
    )

    return jsonify({"message_id": response})
```

The `tags` list labels the message. Tags appear in your event history, which helps you separate welcome emails from other traffic.

## Rendering emails with Jinja templates

Flask already renders Jinja templates, so you can reuse that engine for email bodies. Place the template under `templates/emails/`.

```html templates/emails/welcome.html theme={null}
<html>
  <body>
    <h1>Welcome, {{ name }}</h1>
    <p>Your {{ plan }} plan is active.</p>
    <p><a href="{{ login_url }}">Sign in to your account</a></p>
  </body>
</html>
```

Render the template, then pass the result as the `html` parameter.

```python app/routes/welcome.py theme={null}
from flask import Blueprint, jsonify, render_template, request

from app.email_client import sendlayer

welcome_bp = Blueprint("welcome", __name__, url_prefix="/api")


@welcome_bp.post("/welcome")
def send_welcome_email():
    data = request.get_json()

    html_body = render_template(
        "emails/welcome.html",
        name=data["name"],
        plan=data.get("plan", "Starter"),
        login_url="https://example.com/login",
    )

    response = sendlayer.Emails.send(
        sender={"email": "hello@example.com", "name": "Acme"},
        to=data["email"],
        subject=f"Welcome, {data['name']}",
        html=html_body,
        text=f"Welcome, {data['name']}. Sign in at https://example.com/login.",
    )

    return jsonify({"message_id": response})
```

<Tip>Keep email templates in their own folder. Email clients support a narrow subset of CSS, so those files rarely share styles with your web pages.</Tip>

## Testing the endpoint

Start the development server.

```bash theme={null}
flask run
```

Then post a request from another terminal:

```bash theme={null}
curl --request POST \
  --url http://localhost:5000/api/send-email \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "paulie@example.com",
  "subject": "Testing Flask",
  "message": "Testing the send endpoint."
}'
```

A successful request returns the message ID:

```json theme={null}
{
  "message_id": "06e4491f-fc5a-49cb-bc57-xxxxxx"
}
```

Open the **Email logs** page in your SendLayer dashboard to confirm delivery.

## Next steps

<CardGroup>
  <Card title="Python SDK Reference" icon="python" href="/sdks/python/introduction">
    Review every method and parameter in the Python SDK.
  </Card>

  <Card title="Managing Webhooks" icon="webhook" href="/guides/manage-webhooks">
    Create, list, and delete webhook subscriptions.
  </Card>

  <Card title="Retrieving Events" icon="list" href="/guides/get-events">
    Query delivery events for any message.
  </Card>

  <Card title="Rate Limits" icon="clock" href="/api-reference/rate-limit">
    Understand recipient and request limits.
  </Card>
</CardGroup>


# Send email with Rails
Source: https://developers.sendlayer.com/sdks/ruby/send-with-rails

Learn how to send emails from a Ruby on Rails application using the SendLayer Ruby SDK.

## Prerequisites

Before getting started, you'll need:

1. Ruby 3.0 or later
2. A Rails 7 or Rails 8 application
3. Authorize your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
4. Create and retrieve your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Installation

Add the gem to your `Gemfile`.

```ruby Gemfile theme={null}
gem 'sendlayer'
```

Then install it:

```bash theme={null}
bundle install
```

## Storing your API key

Rails encrypts credentials, so the key can live in the repository safely. Open the encrypted credentials file:

```bash theme={null}
bin/rails credentials:edit
```

Add the key to the file:

```yaml config/credentials.yml.enc theme={null}
sendlayer:
  api_key: your-api-key
```

Read the value through `Rails.application.credentials`:

```ruby config/initializers/sendlayer.rb theme={null}
SENDLAYER = SendLayer::SendLayer.new(
  Rails.application.credentials.dig(:sendlayer, :api_key)
)
```

The initializer runs at boot, so the client is ready before the first request.

<Note>On platforms that inject configuration through the environment, use `ENV.fetch('SENDLAYER_API_KEY')` instead. Keep `config/master.key` out of version control either way.</Note>

## Sending an email from a controller

Call the client from a controller action. The `emails.send` method accepts a hash of parameters.

```ruby app/controllers/contacts_controller.rb theme={null}
class ContactsController < ApplicationController
  def create
    response = SENDLAYER.emails.send(
      from: { email: 'sender@example.com', name: 'Acme Support' },
      to: [{ email: 'support@example.com', name: 'Support Team' }],
      reply_to: [{ email: params[:email], name: params[:name] }],
      subject: "New message from #{params[:name]}",
      text: params[:message]
    )

    render json: { message_id: response }, status: :ok
  end
end
```

Add the route:

```ruby config/routes.rb theme={null}
Rails.application.routes.draw do
  post '/contacts', to: 'contacts#create'
end
```

The `reply_to` field points at the person who filled in the form, so support agents can reply from their inbox.

<Note>Use a `from` address on a domain you authorized in SendLayer. Requests from an unauthorized domain fail.</Note>

## Moving sends to a background job

An HTTP call inside a controller action holds the request open. Active Job moves that work to a worker, so the response returns right away.

```ruby app/jobs/send_email_job.rb theme={null}
class SendEmailJob < ApplicationJob
  queue_as :mailers
  retry_on SendLayer::SendLayerAPIError, wait: 30.seconds, attempts: 5

  def perform(to:, subject:, html:, text:)
    SENDLAYER.emails.send(
      from: { email: 'hello@example.com', name: 'Acme' },
      to: to,
      subject: subject,
      html: html,
      text: text
    )
  end
end
```

Enqueue the job from the controller:

```ruby app/controllers/signups_controller.rb theme={null}
class SignupsController < ApplicationController
  def create
    user = User.create!(signup_params)

    SendEmailJob.perform_later(
      to: user.email,
      subject: "Welcome, #{user.name}",
      html: '<p>Your account is ready.</p>',
      text: 'Your account is ready.'
    )

    render json: { status: 'accepted' }, status: :accepted
  end

  private

  def signup_params
    params.require(:user).permit(:name, :email)
  end
end
```

The `retry_on` line handles transient API failures. Active Job re-runs the job with increasing delays instead of dropping the message.

<Tip>Active Job needs a backing queue in production. The default async adapter loses jobs on restart, so configure Solid Queue, Sidekiq, or another adapter.</Tip>

## Rendering email bodies with ERB templates

Rails templates give you layouts, partials, and helpers. `ActionController::Base.render` renders any template to a string outside the request cycle, which makes it a good fit for job code.

Add the template:

```erb app/views/emails/welcome.html.erb theme={null}
<h1>Welcome, <%= @user.name %></h1>
<p>Your <%= @user.plan %> plan is active.</p>
<p><%= link_to 'Sign in to your account', @login_url %></p>
```

Render the template and pass the output to the SDK:

```ruby app/jobs/welcome_email_job.rb theme={null}
class WelcomeEmailJob < ApplicationJob
  queue_as :mailers

  def perform(user_id)
    user = User.find(user_id)

    html_body = ActionController::Base.render(
      template: 'emails/welcome',
      layout: 'mailer',
      assigns: { user: user, login_url: 'https://example.com/login' }
    )

    SENDLAYER.emails.send(
      from: { email: 'hello@example.com', name: 'Acme' },
      to: [{ email: user.email, name: user.name }],
      subject: "Welcome, #{user.name}",
      html: html_body,
      text: "Welcome, #{user.name}. Sign in at https://example.com/login.",
      tags: ['welcome-email']
    )
  end
end
```

The `tags` array labels the message. Tags appear in your event history, which helps you separate welcome emails from other traffic.

<Tip>Keep email templates in a dedicated layout. Email clients support a narrow subset of CSS, so those views rarely share styles with your web pages.</Tip>

## Testing the endpoint

Start the development server:

```bash theme={null}
bin/rails server
```

Then post a request from another terminal:

```bash theme={null}
curl --request POST \
  --url http://localhost:3000/contacts \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Paulie Paloma",
  "email": "paulie@example.com",
  "message": "Testing the contact endpoint."
}'
```

A successful request returns the message ID:

```json theme={null}
{
  "message_id": "06e4491f-fc5a-49cb-bc57-xxxxxx"
}
```

Open the **Email logs** page in your SendLayer dashboard to confirm delivery.

## Next steps

<CardGroup>
  <Card title="Ruby SDK Reference" icon="gem" href="/sdks/ruby/send-with-ruby">
    Review every method and parameter in the Ruby SDK.
  </Card>

  <Card title="Managing Webhooks" icon="webhook" href="/guides/manage-webhooks">
    Create, list, and delete webhook subscriptions.
  </Card>

  <Card title="Retrieving Events" icon="list" href="/guides/get-events">
    Query delivery events for any message.
  </Card>

  <Card title="Rate Limits" icon="clock" href="/api-reference/rate-limit">
    Understand recipient and request limits.
  </Card>
</CardGroup>


# Send email with Ruby
Source: https://developers.sendlayer.com/sdks/ruby/send-with-ruby

Learn how to install and use the SendLayer Ruby SDK.

## Prerequisites

Before getting started, you'll need to:

1. Authorize your [sending domain](https://sendlayer.com/docs/authorizing-your-domain/)
2. Create and retrieve your [SendLayer API key](https://sendlayer.com/docs/managing-api-keys/)

## Installation

Install the SendLayer Ruby SDK using RubyGems:

```bash theme={null}
gem install sendlayer
```

## Usage

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

### Sending an Email in Ruby

Create a new `.rb` file or edit an existing one. Then require the `sendlayer` gem and initialize the client with your API key. Once done, you

```ruby send_email.rb theme={null}
require 'sendlayer'

# Initialize the email client with your API key
sendlayer = SendLayer::SendLayer.new('your-api-key')
```

Once done, you'll be able to call the `emails.send()` method to send emails using Ruby. The method requires 4 parameters:

* `from`: Sender email address
* `to`: Recipient email address(es)
* `subject`: The subject of your email
* `text` or `html`: This is the email content. You can send plain text or HTML messages to users

```ruby send_email.rb theme={null}
# other code snippets...

# Add email payload
params = {
  from: 'paulie@example.com',
  to: 'recipient@example.com',
  subject: 'Test Email',
  text: 'This is a test email'
}

response = sendlayer.emails.send(params)
```

#### Sending HTML Emails in Ruby

To send HTML emails, include the `html` parameter in the `send` call.

```ruby send_email.rb theme={null}
require 'sendlayer'

sendlayer = SendLayer::SendLayer.new('your-api-key')

params = {
  from: 'paulie@example.com',
  to: 'recipient@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>"
}

response = sendlayer.emails.send(params)
```

<Note>You can include the `text` parameter to have both plain text and HTML versions of your email.</Note>

#### Sending to Multiple Recipients

You can send emails to multiple recipients and include `cc`, and `bcc` email addresses.

```ruby send_email.rb theme={null}
require 'sendlayer'

sendlayer = SendLayer::SendLayer.new('your-api-key')

params = {
  from: { email: 'paulie@example.com', name: 'Paulie Paloma' },
  to: [
    { email: 'recipient1@example.com', name: 'Recipient 1' },
    { email: 'recipient2@example.com', name: 'Recipient 2' }
  ],
  subject: 'Sending Emails to Multiple Recipients',
  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' }]
}

response = sendlayer.emails.send(params)
```

Each recipient field accepts either a string email address or an array of hashes with `email` and `name` keys.

<Note>There are limits to the number of recipients you can add to a single request. See our [rate limiting](/api-reference/rate-limit) guide.</Note>

#### Including Attachments

When sending emails in Ruby with the SendLayer SDK, you can add attachments by including the `attachments` parameter in your email payload.

```ruby send_email.rb theme={null}
require 'sendlayer'

sendlayer = SendLayer::SendLayer.new('your-api-key')

params = {
  from: { email: 'paulie@example.com', name: 'Paulie Paloma' },
  to: [{ email: 'recipient1@example.com', name: 'Recipient' }],
  subject: 'Complex Email',
  html: '<p>This is a <strong>test email</strong>!</p>',
  attachments: [
    {
      path: 'path/to/file.pdf',
      type: 'application/pdf'
    }
  ]
}

response = sendlayer.emails.send(params)
```

<Warning>The maximum email size is 10MB (message plus attachments).</Warning>

The SDK handles base64 encoding of each file you attach. You simply need to specify the `path` and `type` parameters. Make sure to specify the correct MIME `type`.

You can attach multiple files to your email payload, including local and remote files.

#### Email Parameters

Below are the supported parameters for sending emails with the Ruby SDK.

| Parameter     | Type                      | Required | Description                                                       |
| ------------- | ------------------------- | -------- | ----------------------------------------------------------------- |
| `to`          | `String` or `Array<Hash>` | Yes      | Recipient email(s). String or array of `{ email, name }` hashes   |
| `from`        | `String` or `Hash`        | Yes      | Sender email. String or `{ email, name }` hash                    |
| `subject`     | `String`                  | Yes      | Subject line of the email                                         |
| `text`        | `String`                  | Yes      | Plain text version of the email content                           |
| `html`        | `String`                  | No       | HTML version of the email content                                 |
| `cc`          | `String` or `Array<Hash>` | No       | CC recipient(s). String or array of `{ email, name }` hashes      |
| `bcc`         | `String` or `Array<Hash>` | No       | BCC recipient(s). String or array of `{ email, name }` hashes     |
| `reply_to`    | `String` or `Array<Hash>` | No       | Reply-to address(es). String or array of `{ email, name }` hashes |
| `attachments` | `Array<Hash>`             | No       | Attachment objects with `path` and `type` keys                    |
| `tags`        | `Array<String>`           | No       | Tags to associate with the email                                  |
| `headers`     | `Hash`                    | No       | Custom headers as key-value pairs                                 |

### Managing Webhooks

With the SendLayer Ruby SDK, you can create webhooks, list existing webhooks, and delete a webhook.

#### Creating a New Webhook

After initializing the client, call the `webhooks.create` method and pass the required parameters. You'll need to pass the `url` and `event` parameters.

```ruby webhooks.rb theme={null}
require 'sendlayer'

sendlayer = SendLayer::SendLayer.new('your-api-key')

# Create a webhook
params = {
  url: 'https://your-domain.com/webhook',
  event: 'open'
}

webhook = sendlayer.webhooks.create(params)
```

The `event` parameter supports the following values:

* bounce
* click
* open
* unsubscribe
* complaint
* delivery

Example success response for a new webhook:

```json theme={null}
{
  "NewWebhookID": 23718
}
```

<Note>See our guide to learn more about [managing webhooks](/guides/manage-webhooks) and understanding webhook payload format.</Note>

#### Getting All Webhooks

Use `webhooks.get` to retrieve all webhooks created on your SendLayer account.

```ruby webhooks.rb theme={null}
require 'sendlayer'

sendlayer = SendLayer::SendLayer.new('your-api-key')

webhooks = sendlayer.webhooks.get
```

Example response:

```json theme={null}
{
  "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

Use `webhooks.delete(webhook_id)` to delete a webhook by its numeric ID.

<Danger>Deleting a webhook cannot be undone.</Danger>

```ruby webhooks.rb theme={null}
require 'sendlayer'

sendlayer = SendLayer::SendLayer.new('your-api-key')

webhook_id = 23718
sendlayer.webhooks.delete(webhook_id)
```

#### Webhooks Parameters

| Parameter    | Type      | Required | Description                                                                        |
| ------------ | --------- | -------- | ---------------------------------------------------------------------------------- |
| `url`        | `String`  | Yes      | Webhook endpoint URL where events will be sent                                     |
| `event`      | `String`  | Yes      | Event to listen for. One of: bounce, click, open, unsubscribe, complaint, delivery |
| `webhook_id` | `Integer` | Yes      | Unique identifier for the webhook (used for deleting a webhook)                    |

### Retrieving Email Events

You can retrieve events associated with your API key.

#### Getting All Events

Call `events.get` with no parameters to retrieve recent events.

<Note>If no filter is provided, the SDK returns the top 5 events.</Note>

```ruby events.rb theme={null}
require 'sendlayer'

sendlayer = SendLayer::SendLayer.new('your-api-key')

events = sendlayer.events.get
```

Example response:

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

#### Filtering Events

You can use optional parameters to filter results. Here's an example:

```ruby events.rb theme={null}
require 'sendlayer'
require 'time'

sendlayer = SendLayer::SendLayer.new('your-api-key')

params = {
  start_date: Time.now - (4 * 60 * 60),
  end_date: Time.now,
  event: 'opened'
}

events = sendlayer.events.get(params)
```

#### Events Parameters

| Parameter        | Type      | Required | Description                                                                                                                       |
| ---------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `start_date`     | `Time`    | No       | Start date for filtering events                                                                                                   |
| `end_date`       | `Time`    | No       | End date for filtering events                                                                                                     |
| `event`          | `String`  | No       | Filter by event type. Supported: `accepted`, `rejected`, `delivered`, `opened`, `clicked`, `unsubscribed`, `complained`, `failed` |
| `message_id`     | `String`  | No       | Filter by email `MessageId`                                                                                                       |
| `start_from`     | `Integer` | No       | Starting number for pagination                                                                                                    |
| `retrieve_count` | `Integer` | No       | Number of records to retrieve (defaults to 5)                                                                                     |

## Error Handling

The SDK provides custom exception types for better error handling.

```ruby theme={null}
require 'sendlayer'

sendlayer = SendLayer::SendLayer.new('your-api-key')

begin
  response = sendlayer.emails.send(
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Test Email',
    text: 'This is a test email'
  )
rescue SendLayer::SendLayerAPIError => e
  puts "API error: #{e.status_code} - #{e.message}"
rescue SendLayer::SendLayerError => e
  puts "Error: #{e.message}"
end
```

Example error output:

```bash theme={null}
Error: Invalid event name - 'opened' is not a valid event name
```

### Exception Types

* `SendLayer::SendLayerError`: Base exception for all SendLayer errors
* `SendLayer::SendLayerAPIError`: API-specific errors with status code and response data
* `SendLayer::SendLayerAuthenticationError`: Invalid API key or authentication issues
* `SendLayer::SendLayerValidationError`: Invalid parameters or validation errors
* `SendLayer::SendLayerNotFoundError`: Resource not found (404 errors)
* `SendLayer::SendLayerRateLimitError`: Rate limit exceeded (429 errors)
* `SendLayer::SendLayerInternalServerError`: Server errors (5xx errors)

## More Examples

<Card title="SendLayer Ruby SDK" icon="github" href="https://github.com/SendLayer/sendlayer-ruby">
  View more details and examples on GitHub.
</Card>