​
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

​
Retrieving All Events

To get started, you can retrieve all events associated with your account. By default, this returns the most recent 5 events. 
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);
Replace <apiKey> with your actual SendLayer API key in the request header.

​
Example Response

When you retrieve events, you’ll receive data in this format: 
{
  "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. 
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
});

​
Filter by Event Type

You can filter events by type. Here is an example: 
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'
});
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. 
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'
});

​
Pagination and Result Limits

Control how many events to retrieve and implement pagination. 
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
});

​
Combining Filters

You can combine multiple filters to get very specific results. 
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
});

​
Available Parameters

The events API supports the following parameters for filtering and pagination:
ParameterTypeRequiredDescription
startDatenumberNoUnix timestamp for the start of the date range
endDatenumberNoUnix timestamp for the end of the date range
eventstringNoFilter by event type (accepted, rejected, failed, delivered, opened, clicked, unsubscribed, complained)
messageIdstringNoFilter by specific email Message ID
startFromnumberNoStarting position for pagination (default: 0)
retrieveCountnumberNoNumber of events to retrieve (default: 5)

​
Event Data Structure

Each event contains detailed information about what happened to your email: 
{
  "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

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.
For real-time monitoring, check every few minutes. For batch processing, hourly or daily checks are usually sufficient.
All timestamps are in Unix timestamp format (seconds since epoch) and are in UTC timezone.