README

SendLayer PHP SDK

The official PHP SDK for interacting with the SendLayer API, providing a simple and intuitive interface for sending emails, managing webhooks, and retrieving email events.

Features

Email Sending: Send transactional emails with support for HTML, text, attachments, and advanced options
Webhook Management: Create, retrieve, and delete webhooks for real-time event notifications
Event Tracking: Retrieve email events and analytics data
Error Handling: Comprehensive exception handling with specific error types
Validation: Built-in validation for email addresses, URLs, and API parameters
File Attachments: Support for both local and remote file attachments
Modern PHP: Built with PHP 7.4+ features and PSR-4 autoloading

Installation

Using Composer (Recommended)

composer require sendlayer/sendlayer-php

Manual Installation

Download the SDK
Include the autoloader in your project
Install dependencies: composer install

Quick Start

<?php

require_once 'vendor/autoload.php';

use SendLayer\SendLayer;
use SendLayer\Exceptions\SendLayerException;

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

try {
    // Send a simple email
    $response = $sendlayer->Emails->send(
        from: 'sender@example.com',
        to: 'recipient@example.com',
        subject: 'Test Email',
        text: 'This is a test email sent using the SendLayer PHP SDK'
    );
    
    echo "Email sent successfully! Message ID: " . $response['MessageID'];
    
} catch (SendLayerException $e) {
    echo "Error: " . $e->getMessage();
}

Configuration (Optional)

You can pass additional configuration options when initializing the SDK:

$config = [
    'timeout' => 30,                    // HTTP timeout in seconds
    'attachmentURLTimeout' => 30000,    // Attachment URL timeout in milliseconds
    'guzzle' => [                       // Additional Guzzle HTTP client options
        'verify' => false,              // Disable SSL verification (not recommended for production)
        'proxy' => 'http://proxy:8080'  // Use proxy
    ]
];

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

Email Sending

Basic Email

$response = $sendlayer->Emails->send(
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Welcome!',
    text: 'Welcome to our platform!'
);

HTML Email

$response = $sendlayer->Emails->send(
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Welcome!',
    html: '<h1>Welcome!</h1><p>Welcome to our platform!</p>'
);

HTML Email with Plain-Text Fallback

Pass both html and text to send a message that carries an HTML part for clients that render it and a plain-text alternative for those that don't. Recommended for deliverability.

$response = $sendlayer->Emails->send(
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Welcome!',
    text: 'Welcome to our platform!',
    html: '<h1>Welcome!</h1><p>Welcome to our platform!</p>'
);

Both parts are sent; ContentType is reported to the API as HTML whenever an HTML body is present, and as Text when only text is supplied.

Email with Sender Name

$response = $sendlayer->Emails->send(
    from: ['email' => 'sender@example.com', 'name' => 'John Doe'],
    to: 'recipient@example.com',
    subject: 'Welcome!',
    text: 'Welcome to our platform!'
);

Multiple Recipients

$response = $sendlayer->Emails->send(
    from: 'sender@example.com',
    to: ['user1@example.com', 'user2@example.com'],
    subject: 'Welcome!',
    text: 'Welcome to our platform!'
);

Email with CC and BCC

$response = $sendlayer->Emails->send(
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Welcome!',
    text: 'Welcome to our platform!',
    cc: 'cc@example.com',
    bcc: 'bcc@example.com'
);

Email with Attachments

$response = $sendlayer->Emails->send(
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Document attached',
    text: 'Please find the attached document.',
    attachments: [
        [
            'path' => '/path/to/document.pdf',
            'type' => 'application/pdf'
        ],
        [
            'path' => 'https://example.com/image.jpg',
            'type' => 'image/jpeg'
        ]
    ]
);

Email with Custom Headers and Tags

$response = $sendlayer->Emails->send(
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Welcome!',
    text: 'Welcome to our platform!',
    headers: [
        'X-Custom-Header' => 'Custom Value',
        'X-Priority' => '1'
    ],
    tags: ['welcome', 'onboarding']
);

Webhook Management

Create a Webhook

$response = $sendlayer->Webhooks->create(
    url: 'https://your-domain.com/webhook',
    event: 'delivery'
);

Get All Webhooks

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

Delete a Webhook

$sendlayer->Webhooks->delete(webhookId: 123);

Event Tracking

Get All Events

$events = $sendlayer->Events->get();

Get Events with Filters

$events = $sendlayer->Events->get(
    startDate: new DateTime('2024-01-01'),
    endDate: new DateTime('2024-01-31'),
    event: 'delivered',
    retrieveCount: 50
);

Get Events for Specific Message

$events = $sendlayer->Events->get(
    messageId: 'message-id-here'
);

Error Handling

The SDK provides specific exception types for different error scenarios:

use SendLayer\Exceptions\SendLayerException;

try {
    $response = $sendlayer->Emails->send(/* ... */);
} catch (SendLayerException $e) {
    // Handle other SendLayer errors
    echo "Error: " . $e->getMessage();
}

When the API returns errors, the SDK preserves them on the exception's $errors property as the raw Errors entries from the response (each with a numeric Code and a Message):

try {
    $response = $sendlayer->Emails->send(/* ... */);
} catch (SendLayerException $e) {
    echo $e->getMessage();          // e.g. "Recipient email is suppressed"

    foreach ($e->errors as $error) {
        echo $error['Code'];        // e.g. 14
        echo $error['Message'];     // e.g. "Recipient email is suppressed"
    }

    // Branch on a specific SendLayer error code:
    if (in_array(14, array_column($e->errors, 'Code'), true)) {
        // recipient suppressed
    }
}

$errors is declared on the base SendLayerException, so it is available on every exception type. It is an empty array when the SDK raises the error locally (client-side validation, connection failures) and when the API returns a body that isn't the JSON Errors shape, so guard with empty($e->errors) before relying on it.

getMessage() returns the API's message text verbatim for the specific exception types listed below, joining multiple messages with ; . The one exception is SendLayerAPIException, which prefixes its message with API Error {status}: . When the response body isn't JSON, the message falls back to the HTTP reason phrase (e.g. Bad Request).

The numeric Code values are a fixed set defined by the API — see the SendLayer error codes reference for the full table (14 = recipient suppressed, 17 = email quota reached, 32 = domain not activated, and so on).

Exception Types

SendLayerException: Base exception for all SendLayer errors
SendLayerAuthenticationException: Invalid API key or authentication issues
SendLayerValidationException: Invalid parameters or validation errors
SendLayerAPIException: any status not covered by the types above, exposing the public $statusCode (int) and $response (array, the decoded response body)
SendLayerNotFoundException: Resource not found (404 errors)
SendLayerRateLimitException: Rate limit exceeded (429 errors)
SendLayerInternalServerException: Internal server error (500 responses only; other 5xx statuses raise SendLayerAPIException)

getCode() carries the HTTP status code of the response, with one caveat: a 422 response raises a SendLayerValidationException whose code is 400, since both statuses map to that type. Match on the exception class, or on the Code values in $errors, rather than on getCode() when you need to tell them apart.

Supported Events

Webhook Events

bounce: Email bounced
click: Link was clicked
open: Email was opened
unsubscribe: User unsubscribed
complaint: User marked as spam
delivery: Email was delivered

Event Tracking Events

accepted: Email was accepted by the server
rejected: Email was rejected
delivered: Email was delivered
opened: Email was opened
clicked: Link was clicked
unsubscribed: User unsubscribed
complained: User marked as spam
failed: Email delivery failed

Requirements

PHP 7.4 or higher
Guzzle HTTP Client 7.x or 8.x
JSON extension
cURL extension (recommended)

License

This SDK is licensed under the MIT License. See the LICENSE file for details.

Support

For support, please contact:

Email: support@sendlayer.com
Documentation: https://developers.sendlayer.com
GitHub Issues: https://github.com/sendlayer/sendlayer-php/issues

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Changelog

See CHANGELOG.md for a list of changes and version history.

sendlayer / sendlayer-php

Package info

Security

Statistics