Invio di Email con PHP

L'invio di email da PHP ha tradizionalmente significato lottare con mail(), configurare server SMTP o includere dipendenze pesanti. L'SDK PHP di Emailit ti offre un'alternativa pulita e moderna. Puoi inviare email transazionali, gestire domini, verificare indirizzi e gestire webhook, tutto attraverso un semplice client API.

PHP rimane uno dei linguaggi più utilizzati per lo sviluppo web, e l'invio di email è un requisito fondamentale per quasi ogni applicazione PHP. Che tu stia costruendo un prodotto SaaS, un e-commerce o un sistema di gestione dei contenuti, la consegna affidabile delle email è essenziale per l'onboarding degli utenti, il reset delle password, le conferme d'ordine e le campagne di marketing. Invece di affidarsi alla funzione integrata mail() di PHP, che offre controllo limitato e nessuna garanzia di consegna, utilizzare un'API email dedicata assicura che i tuoi messaggi raggiungano effettivamente la casella di posta.

In questa guida ti mostreremo come installare l'SDK e utilizzarlo per inviare email da qualsiasi applicazione PHP.

Requisiti

• PHP 8.1 o superiore
• Un account Emailit con una chiave API
• Composer

Installazione

Installa l'SDK tramite Composer:

composer require emailit/emailit-php

L'SDK PHP di Emailit è disponibile come pacchetto Composer, quindi si integra perfettamente in qualsiasi progetto PHP che utilizza Composer per la gestione delle dipendenze. Non è necessario includere file manualmente o utilizzare autoloader personalizzati.

Inizializzare il client

Crea un'istanza del client con la tua chiave API:

require 'vendor/autoload.php';

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

Puoi trovare la tua chiave API nella dashboard di Emailit sotto Chiavi API.

Inviare un'email di base

Inviare un'email richiede una singola chiamata al metodo:

$email = $emailit->emails()->send([
    'from'    => 'hello@tuodominio.com',
    'to'      => ['utente@esempio.com'],
    'subject' => 'Ciao da Emailit',
    'html'    => '<h1>Benvenuto!</h1><p>Grazie per esserti registrato.</p>',
]);

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

Tutti i metodi del servizio restituiscono oggetti risorsa tipizzati con accesso diretto alle proprietà, così sai sempre esattamente con cosa stai lavorando.

Rispetto all'utilizzo della funzione nativa mail() di PHP, inviare email tramite API ti offre tracciamento della consegna, gestione dei rimbalzi e informazioni dettagliate sullo stato per ogni messaggio. Non devi preoccuparti di configurare Sendmail o Postfix sul tuo server, e ottieni una consegna affidabile su tutti i principali provider email come Gmail, Outlook e Yahoo.

Inviare con un template

Se hai creato un template nella dashboard di Emailit, puoi referenziarlo tramite slug e passare variabili:

$email = $emailit->emails()->send([
    'from'      => 'hello@tuodominio.com',
    'to'        => 'utente@esempio.com',
    'template'  => 'email_benvenuto',
    'variables' => [
        'nome'    => 'Mario Rossi',
        'azienda' => 'Acme S.r.l.',
    ],
]);

I template mantengono il contenuto delle tue email fuori dal codice e permettono ai non-sviluppatori di aggiornare i testi senza un deploy. Questo è particolarmente utile per email transazionali come messaggi di benvenuto, link per il reset della password, ricevute di fatture e notifiche di spedizione dove il design e il testo cambiano più spesso del codice che le attiva.

Inviare con allegati

Allega file passando contenuto codificato in base64:

$email = $emailit->emails()->send([
    'from'        => 'fatture@tuodominio.com',
    'to'          => 'cliente@esempio.com',
    'subject'     => 'La tua Fattura #12345',
    'html'        => '<p>Trovi in allegato la tua fattura.</p>',
    'attachments' => [
        [
            'filename'     => 'fattura.pdf',
            'content'      => base64_encode(file_get_contents('fattura.pdf')),
            'content_type' => 'application/pdf',
        ],
    ],
]);

Puoi allegare PDF, immagini, fogli di calcolo o qualsiasi altro tipo di file. Questo è comunemente utilizzato per inviare fatture, report o documenti generati direttamente dalla tua applicazione PHP senza richiedere un link di download separato.

Programmare un'email per dopo

Passa un timestamp scheduled_at per inviare in una data futura:

$email = $emailit->emails()->send([
    'from'         => 'promemoria@tuodominio.com',
    'to'           => 'utente@esempio.com',
    'subject'      => 'Promemoria Appuntamento',
    'html'         => '<p>Il tuo appuntamento è domani alle 14:00.</p>',
    'scheduled_at' => '2026-04-10T09:00:00Z',
]);

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

Le email programmate possono essere cancellate prima dell'invio:

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

La programmazione è utile per comunicazioni sensibili al tempo come promemoria di appuntamenti, avvisi di rinnovo abbonamenti e campagne drip dove il momento dell'invio è importante quanto il contenuto stesso.

Elencare e gestire le email inviate

Recupera un elenco paginato delle tue email:

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

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

Riprova un'email fallita:

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

Avere piena visibilità sulle tue email inviate, il loro stato di consegna e la possibilità di riprovare i fallimenti ti dà un livello di controllo che la funzione mail() di PHP semplicemente non può fornire. Questo è fondamentale per applicazioni dove ogni email conta, come ricevute transazionali, link di verifica account e codici di autenticazione a due fattori.

Verificare gli indirizzi email prima dell'invio

Riduci i rimbalzi verificando gli indirizzi in anticipo:

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

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

La verifica email è una best practice per proteggere la tua reputazione di mittente. Inviare a indirizzi email non validi o temporanei aumenta il tuo tasso di rimbalzo, che può attivare filtri antispam e danneggiare la deliverability su tutto il tuo dominio. Verificando gli indirizzi prima dell'invio, mantieni bassi i tassi di rimbalzo e intatta la tua reputazione.

Gestire eventi webhook

L'SDK include classi di eventi tipizzate e verifica della firma per i webhook. Questo ti permette di reagire agli eventi di consegna in tempo reale:

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 => gestisciConsegna($event),
    $event instanceof EmailBounced   => gestisciRimbalzo($event),
    default                          => log("Non gestito: {$event->type}"),
};

I webhook permettono alla tua applicazione PHP di rispondere istantaneamente quando un'email viene consegnata, rimbalza, aperta o cliccata. Questo è essenziale per costruire flussi di lavoro event-driven come aggiornare un CRM quando un messaggio viene consegnato, avvisare il team di supporto sui rimbalzi o tracciare metriche di engagement per le tue campagne email.

Gestione degli errori

L'SDK lancia eccezioni tipizzate così puoi gestire ogni caso di errore con precisione:

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

try {
    $emailit->emails()->send([...]);
} catch (AuthenticationException $e) {
    // Chiave API non valida (401)
} catch (RateLimitException $e) {
    // Troppe richieste (429)
} catch (UnprocessableEntityException $e) {
    // Validazione fallita (422)
} catch (ApiErrorException $e) {
    // Qualsiasi altro errore API
    echo $e->getHttpStatus();
}

Una gestione appropriata degli errori assicura che la tua applicazione si degradi elegantemente quando qualcosa va storto. Le eccezioni di rate limit, per esempio, possono essere gestite con una strategia di retry, mentre gli errori di autenticazione dovrebbero attivare un alert così puoi ruotare la tua chiave API.

Oltre le email

L'SDK ti dà accesso all'intera API di Emailit, non solo all'invio. Puoi gestire domini, chiavi API, audience, iscritti, template, soppressioni, contatti ed eventi, tutto da PHP:

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

Questo rende l'SDK PHP di Emailit un toolkit completo per l'infrastruttura email. Invece di utilizzare librerie o servizi separati per la gestione dei domini, liste di contatti e invio email, puoi gestire tutto attraverso un singolo client PHP coerente.

Inizia subito

Installa l'SDK e invia la tua prima email in meno di un minuto:

composer require emailit/emailit-php

Consulta la documentazione completa dell'SDK su GitHub, o vai al Riferimento API per i dettagli su ogni endpoint.