Надсилання електронних листів за допомогою Laravel

Laravel постачається з відмінною підтримкою пошти з коробки, але вам все одно потрібен надійний сервіс доставки. Пакет Emailit Laravel інтегрується безпосередньо в поштову систему Laravel як нативний транспорт. Ваші існуючі Mailables, Notifications та виклики Mail::send() працюють без жодних змін у коді. Крім того, ви отримуєте повний доступ до API Emailit через зручний Facade.

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

У цьому посібнику ми розглянемо налаштування Emailit у Laravel-додатку та відправку електронних листів як через стандартну поштову систему Laravel, так і через Facade Emailit.

Вимоги

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

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

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

composer require emailit/emailit-laravel

Пакет автоматично реєструє свій сервіс-провайдер, тому ручна реєстрація не потрібна. Він працює з Laravel 10, 11 та 12 з коробки.

Налаштування

Додайте свій API-ключ до .env:

EMAILIT_API_KEY=your_api_key

Встановіть Emailit як поштовик за замовчуванням:

MAIL_MAILER=emailit

Додайте поштовик emailit до масиву mailers у вашому config/mail.php:

'mailers' => [
    // ...

    'emailit' => [
        'transport' => 'emailit',
    ],
],

За бажанням опублікуйте конфігураційний файл для налаштування базової URL API:

php artisan vendor:publish --tag=emailit-config

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

Відправка електронних листів через Laravel Mail

Після налаштування всі функції пошти Laravel працюють з коробки. Нічого в існуючому коді змінювати не потрібно.

Використання Mailable

Створіть клас Mailable як зазвичай:

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Queue\SerializesModels;

class WelcomeEmail extends Mailable
{
    use Queueable, SerializesModels;

    public function __construct(
        public readonly User $user,
    ) {}

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Ласкаво просимо до нашого додатку',
        );
    }

    public function content(): Content
    {
        return new Content(
            view: 'emails.welcome',
        );
    }
}

Потім відправте його:

use Illuminate\Support\Facades\Mail;
use App\Mail\WelcomeEmail;

Mail::to('user@example.com')->send(new WelcomeEmail($user));

Пошта в чергах, Markdown-листи та Notifications працюють точно так, як ви очікуєте. Emailit прозоро розташовується за поштовим рівнем Laravel, тому ви можете замінити його на будь-який існуючий транспорт, як-от SMTP, Mailgun або SES, не торкаючись коду додатку. Це дозволяє легко тестувати Emailit поряд з вашим поточним провайдером або поступово мігрувати.

Використання Facade Emailit

Для функцій, які виходять за межі того, що пропонує поштова система Laravel, таких як шаблони зі змінними, заплановані відправки або управління ресурсами API, використовуйте Emailit Facade. Він надає прямий доступ до повного Emailit PHP SDK.

Відправка електронного листа через API

use Emailit\Laravel\Facades\Emailit;

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

echo $email->id;
echo $email->status;

Відправка з шаблоном

Посилайтеся на шаблони, які ви створили в панелі керування Emailit, та передавайте динамічні змінні:

use Emailit\Laravel\Facades\Emailit;

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

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

Планування електронного листа

use Emailit\Laravel\Facades\Emailit;

$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',
]);

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

Відправка з вкладеннями

use Emailit\Laravel\Facades\Emailit;

$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',
        ],
    ],
]);

Управління ресурсами

Facade надає доступ до кожного сервісу з API Emailit, тому ви можете керувати всією своєю email-інфраструктурою з Laravel.

Домени

use Emailit\Laravel\Facades\Emailit;

$domain = Emailit::domains()->create([
    'name' => 'example.com',
    'track_loads' => true,
    'track_clicks' => true,
]);

$domain = Emailit::domains()->verify('sd_123');

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

Контакти

use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->create([
    'email' => 'user@example.com',
    'first_name' => 'Іван',
    'last_name' => 'Петренко',
]);

$contacts = Emailit::contacts()->list();

Верифікація електронної пошти

use Emailit\Laravel\Facades\Emailit;

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

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

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

Впровадження залежностей

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

use Emailit\EmailitClient;

class EmailController extends Controller
{
    public function send(EmailitClient $emailit)
    {
        $email = $emailit->emails()->send([
            'from'    => 'hello@yourdomain.com',
            'to'      => ['user@example.com'],
            'subject' => 'Привіт',
            'html'    => '<p>Вітаю!</p>',
        ]);

        return response()->json(['id' => $email->id]);
    }
}

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

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

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

use Emailit\Exceptions\AuthenticationException;
use Emailit\Exceptions\RateLimitException;
use Emailit\Exceptions\ApiErrorException;
use Emailit\Laravel\Facades\Emailit;

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

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

Всі доступні сервіси

Facade надає доступ до всього в API Emailit:

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

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

composer require emailit/emailit-laravel

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