Надсилання електронної пошти за допомогою PHP

Надсилання електронних листів з PHP традиційно означало боротьбу з mail(), налаштування SMTP-серверів або підключення важких залежностей. Emailit PHP SDK пропонує вам чисту, сучасну альтернативу. Ви можете надсилати транзакційні листи, керувати доменами, перевіряти адреси та обробляти вебхуки — все через простий API-клієнт.

PHP залишається однією з найпоширеніших мов для веб-розробки, а надсилання електронних листів є основною вимогою майже для кожного PHP-додатка. Чи створюєте ви SaaS-продукт, інтернет-магазин або систему управління контентом — надійна доставка листів є критично важливою для реєстрації користувачів, скидання паролів, підтвердження замовлень та маркетингових кампаній. Замість покладання на вбудовану функцію PHP mail(), яка пропонує обмежений контроль і не гарантує доставку, використання спеціалізованого email API забезпечує, що ваші повідомлення дійсно потраплять до поштової скриньки.

У цьому посібнику ми розглянемо встановлення SDK та його використання для надсилання листів з будь-якого PHP-додатка.

Вимоги

• PHP 8.1 або вище
• Обліковий запис Emailit з API-ключем
• Composer

Встановлення

Встановіть SDK через Composer:

composer require emailit/emailit-php

Emailit PHP SDK доступний як пакет Composer, тому він безперешкодно інтегрується в будь-який PHP-проект, що використовує Composer для управління залежностями. Немає потреби в ручному підключенні файлів або власних автозавантажувачах.

Ініціалізація клієнта

Створіть екземпляр клієнта з вашим API-ключем:

require 'vendor/autoload.php';

$emailit = Emailit::client('your_api_key');

Ваш API-ключ можна знайти в панелі керування Emailit у розділі API Keys.

Надсилання базового листа

Надсилання листа потребує лише одного виклику методу:

$email = $emailit->emails()->send([
    'from'    => 'hello@yourdomain.com',
    'to'      => ['user@example.com'],
    'subject' => 'Привіт від Emailit',
    'html'    => '<h1>Ласкаво просимо!</h1><p>Дякуємо за реєстрацію.</p>',
]);

echo $email->id;     // em_abc123...
echo $email->status; // pending

Усі методи сервісу повертають типізовані об'єкти ресурсів з прямим доступом до властивостей, тому ви завжди точно знаєте, з чим працюєте.

Порівняно з використанням нативної функції PHP mail(), надсилання листів через API дає вам відстеження доставки, обробку відмов та детальну інформацію про статус кожного повідомлення. Вам не потрібно турбуватися про налаштування Sendmail або Postfix на вашому сервері, і ви отримуєте надійну доставку через усіх основних постачальників електронної пошти, таких як Gmail, Outlook та Yahoo.

Надсилання з шаблоном

Якщо ви створили шаблон у панелі керування Emailit, ви можете посилатися на нього за слагом та передавати змінні:

$email = $emailit->emails()->send([
    'from'      => 'hello@yourdomain.com',
    'to'        => 'user@example.com',
    'template'  => 'welcome_email',
    'variables' => [
        'name'    => 'Іван Петренко',
        'company' => 'ТОВ "Приклад"',
    ],
]);

Шаблони дозволяють тримати вміст ваших листів поза кодовою базою та дають можливість не-розробникам оновлювати текст без розгортання. Це особливо корисно для транзакційних листів, таких як вітальні повідомлення, посилання для скидання паролів, квитанції рахунків та сповіщення про доставку, де дизайн та формулювання змінюються частіше, ніж код, який їх запускає.

Надсилання з вкладеннями

Прикріпляйте файли, передаючи вміст, закодований у base64:

$email = $emailit->emails()->send([
    'from'        => 'invoices@yourdomain.com',
    'to'          => 'customer@example.com',
    'subject'     => 'Ваш рахунок №12345',
    'html'        => '<p>Будь ласка, знайдіть ваш рахунок у вкладенні.</p>',
    'attachments' => [
        [
            'filename'     => 'invoice.pdf',
            'content'      => base64_encode(file_get_contents('invoice.pdf')),
            'content_type' => 'application/pdf',
        ],
    ],
]);

Ви можете прикріпляти PDF-файли, зображення, електронні таблиці або будь-які інші типи файлів. Це зазвичай використовується для надсилання рахунків, звітів або згенерованих документів безпосередньо з вашого PHP-додатка без необхідності окремого посилання для завантаження.

Планування листа на пізніше

Передайте мітку часу scheduled_at для надсилання в майбутньому:

$email = $emailit->emails()->send([
    'from'         => 'reminders@yourdomain.com',
    'to'           => 'user@example.com',
    'subject'      => 'Нагадування про зустріч',
    'html'         => '<p>Ваша зустріч завтра о 14:00.</p>',
    'scheduled_at' => '2026-04-10T09:00:00Z',
]);

echo $email->status;       // scheduled
echo $email->scheduled_at; // 2026-04-10T09:00:00Z

Заплановані листи можна скасувати до їх надсилання:

$emailit->emails()->cancel('em_abc123');

Планування корисне для чутливих до часу комунікацій, таких як нагадування про зустрічі, сповіщення про продовження підписки та поетапні кампанії, де час надсилання має таке ж значення, як і сам вміст.

Перегляд та управління надісланими листами

Отримайте посторінковий список ваших листів:

$emails = $emailit->emails()->list(['page' => 1, 'limit' => 10]);

foreach ($emails as $email) {
    echo $email->id . ' - ' . $email->status . "\n";
}

Повторіть спробу надсилання невдалого листа:

$emailit->emails()->retry('em_abc123');

Повна видимість ваших надісланих листів, їх статусу доставки та можливість повторювати невдалі спроби дає вам рівень контролю, який функція PHP mail() просто не може забезпечити. Це критично важливо для додатків, де кожен лист має значення, наприклад транзакційні квитанції, посилання для підтвердження облікового запису та коди двофакторної автентифікації.

Перевірка адрес електронної пошти перед надсиланням

Зменшіть кількість відмов, перевіряючи адреси заздалегідь:

$result = $emailit->emailVerifications()->verify([
    'email' => 'test@example.com',
]);

echo $result->status; // valid
echo $result->score;  // 0.95
echo $result->risk;   // low

Перевірка електронної пошти є найкращою практикою для захисту вашої репутації відправника. Надсилання на недійсні або одноразові адреси електронної пошти збільшує ваш показник відмов, що може спрацювати спам-фільтри та зашкодити доставляємості по всьому вашому домену. Перевіряючи адреси перед надсиланням, ви підтримуєте низькі показники відмов та зберігаєте свою репутацію.

Обробка подій вебхуків

SDK включає типізовані класи подій та перевірку підпису для вебхуків. Це дозволяє вам реагувати на події доставки в реальному часі:

use Emailit\WebhookSignature;
use Emailit\Events\EmailDelivered;
use Emailit\Events\EmailBounced;

$event = WebhookSignature::verify(
    file_get_contents('php://input'),
    $_SERVER['HTTP_X_EMAILIT_SIGNATURE'],
    $_SERVER['HTTP_X_EMAILIT_TIMESTAMP'],
    'your_webhook_signing_secret'
);

match (true) {
    $event instanceof EmailDelivered => handleDelivered($event),
    $event instanceof EmailBounced   => handleBounce($event),
    default                          => log("Необроблено: {$event->type}"),
};

Вебхуки дозволяють вашому PHP-додатку миттєво реагувати, коли лист доставлено, відхилено, відкрито або клікнуто. Це важливо для створення керованих подіями робочих процесів, таких як оновлення CRM при доставці повідомлення, сповіщення команди підтримки про відмови або відстеження метрик залученості для ваших email-кампаній.

Обробка помилок

SDK викидає типізовані винятки, тому ви можете точно обробляти кожен випадок помилки:

use Emailit\Exceptions\AuthenticationException;
use Emailit\Exceptions\RateLimitException;
use Emailit\Exceptions\UnprocessableEntityException;
use Emailit\Exceptions\ApiErrorException;

try {
    $emailit->emails()->send([...]);
} catch (AuthenticationException $e) {
    // Недійсний API-ключ (401)
} catch (RateLimitException $e) {
    // Забагато запитів (429)
} catch (UnprocessableEntityException $e) {
    // Валідація не пройшла (422)
} catch (ApiErrorException $e) {
    // Будь-яка інша помилка API
    echo $e->getHttpStatus();
}

Правильна обробка помилок забезпечує коректну деградацію вашого додатка при виникненні проблем. Винятки обмеження швидкості, наприклад, можна обробити стратегією повторних спроб, тоді як помилки автентифікації повинні викликати сповіщення, щоб ви могли оновити свій API-ключ.

Більше, ніж листи

SDK надає доступ до повного API Emailit, не лише надсилання. Ви можете керувати доменами, API-ключами, аудиторіями, підписниками, шаблонами, придушеннями, контактами та подіями — все з PHP:

$domain = $emailit->domains()->create(['name' => 'example.com']);
$contact = $emailit->contacts()->create(['email' => 'user@example.com']);
$templates = $emailit->templates()->list();

Це робить Emailit PHP SDK повним набором інструментів для email-інфраструктури. Замість використання окремих бібліотек або сервісів для управління доменами, списків контактів та надсилання листів, ви можете обробляти все через єдиний, послідовний PHP-клієнт.

Почніть роботу

Встановіть SDK та надішліть свій перший лист менш ніж за хвилину:

composer require emailit/emailit-php

Ознайомтеся з повною документацією SDK на GitHub або перейдіть до Довідника API для деталей про кожну кінцеву точку.