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>'
);

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();
}

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
SendLayerNotFoundException: Resource not found (404 errors)
SendLayerRateLimitException: Rate limit exceeded (429 errors)
SendLayerInternalServerException: Server errors (5xx errors)

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.0 or higher
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

Maintainers

Details