Tutoriál
Odesílání e-mailů z PHP
Odesílejte e-maily z jakékoli aplikace v PHP přes SDK emailit/emailit-php, čisté cURL, nebo přes SMTP s PHPMailerem, a ověřujte podpisy webhooků Emailitu.
Tento návod popisuje odesílání e-mailů z aplikace v PHP bez frameworku: přes oficiální SDK emailit/emailit-php, čisté cURL, nebo přes SMTP s PHPMailerem. Ukazuje také endpoint pro webhooky, který ověřuje podpisy. Používáte Laravel? Řiďte se místo toho návodem pro Laravel.
Předpoklady
- PHP 8.1 nebo novější a Composer.
- Ověřená odesílací doména, například
acme.com. - API klíč. Stačí klíč jen pro odesílání omezený na vaši doménu.
- Dokud váš workspace nemá produkční přístup, můžete odesílat jen na e-mailové adresy účtů členů workspace.
Nainstalujte SDK
composer require emailit/emailit-phpSDK používá pro HTTP knihovnu Guzzle, kterou Composer nainstaluje za vás.
Nastavte API klíč
Nastavte klíč jako proměnnou prostředí ve webovém serveru, poolu PHP-FPM nebo v administraci hostingu a načítejte ho za běhu:
export EMAILIT_API_KEY=secret_••••••••••••••••••••••••••••••••$apiKey = getenv('EMAILIT_API_KEY');Pokud načítáte soubor .env balíčkem jako vlucas/phpdotenv, držte tento soubor mimo kořenový adresář webu a mimo správu verzí.
Odešlete e-mail
require __DIR__.'/vendor/autoload.php';
$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));
$email = $emailit->emails()->send([
'from' => 'Acme <hello@acme.com>',
'to' => 'ada@example.com',
'subject' => 'Your receipt from Acme',
'html' => '<p>Thanks for your order.</p>',
'text' => 'Thanks for your order.',
]);
echo $email->id; // em_…Stejné volání přijímá cc, bcc, reply_to, attachments, template s variables, scheduled_at a tracking. Pokud chcete připojit soubor, zakódujte ho v Base64:
$email = $emailit->emails()->send([
'from' => 'Acme Billing <billing@acme.com>',
'to' => 'ada@example.com',
'subject' => 'Invoice INV-1042',
'html' => '<p>Your invoice is attached.</p>',
'attachments' => [[
'filename' => 'INV-1042.pdf',
'content' => base64_encode(file_get_contents(__DIR__.'/INV-1042.pdf')),
'content_type' => 'application/pdf',
]],
]);Všechna pole najdete na stránce Odeslání e-mailu a limity na stránce Přílohy.
Ošetřete chyby
use Emailit\Exceptions\ApiErrorException;
use Emailit\Exceptions\AuthenticationException;
use Emailit\Exceptions\RateLimitException;
use Emailit\Exceptions\UnprocessableEntityException;
try {
$emailit->emails()->send($message);
} catch (AuthenticationException $e) {
// 401: the API key is missing or invalid
} catch (RateLimitException $e) {
// 429: wait and retry
} catch (UnprocessableEntityException $e) {
// 422: for example, the from domain isn't verified
} catch (ApiErrorException $e) {
error_log('Emailit error '.$e->getHttpStatus().': '.$e->getMessage());
}Odesílejte bez SDK
Pokud nemůžete použít Composer, volejte API přes cURL:
$ch = curl_init('https://api.emailit.com/v2/emails');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('EMAILIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'from' => 'Acme <hello@acme.com>',
'to' => 'ada@example.com',
'subject' => 'Your receipt from Acme',
'html' => '<p>Thanks for your order.</p>',
]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) {
throw new RuntimeException("Emailit returned $status: $body");
}
$email = json_decode($body, true); // $email['id'] is the em_ IDOdesílání přes SMTP
Funguje jakákoli e-mailová knihovna pro PHP, která podporuje SMTP. S PHPMailerem (composer require phpmailer/phpmailer):
use PHPMailer\PHPMailer\PHPMailer;
require __DIR__.'/vendor/autoload.php';
$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = 'smtp.emailit.com';
$mail->Port = 587;
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->SMTPAuth = true;
$mail->Username = 'emailit';
$mail->Password = getenv('EMAILIT_API_KEY');
$mail->setFrom('hello@acme.com', 'Acme');
$mail->addAddress('ada@example.com');
$mail->Subject = 'Your receipt from Acme';
$mail->isHTML(true);
$mail->Body = '<p>Thanks for your order.</p>';
$mail->AltBody = 'Thanks for your order.';
$mail->send();Se Symfony Mailerem použijte DSN smtp://emailit:API_KEY@smtp.emailit.com:587. Pro implicitní TLS použijte port 465 (PHPMailer::ENCRYPTION_SMTPS); pokud váš hosting blokuje port 587, zkuste 2525 nebo 2587. Viz Nastavení SMTP.
Přijímejte webhooky
Vytvořte webhook, který míří na váš endpoint, a jeho tajný klíč uložte do EMAILIT_WEBHOOK_SECRET. Surové tělo požadavku čtěte z php://input a ověřte ho dřív, než mu začnete věřit:
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EMAILIT_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_EMAILIT_TIMESTAMP'] ?? '';
$secret = getenv('EMAILIT_WEBHOOK_SECRET');
$expected = hash_hmac('sha256', $timestamp.'.'.$payload, $secret);
if (abs(time() - (int) $timestamp) > 300 || ! hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
// The body is a JSON array of up to 100 events.
foreach (json_decode($payload, true) as $event) {
if ($event['type'] === 'email.bounced') {
$address = $event['data']['object']['to'];
// Stop emailing $address.
}
}
http_response_code(200);Do 30 sekund odpovězte s 2xx; cokoli jiného se opakuje. Viz Ověření podpisu webhooků.
Tipy pro produkční provoz
- Používejte jednoho klienta pro celý požadavek nebo worker, místo abyste ho vytvářeli pro každý e-mail.
- Odesílejte na pozadí. Při hromadném odesílání řaďte zprávy do fronty a odesílejte je z workeru, aby stránky zůstaly rychlé a vy jste se drželi pod svými limity odesílání (ve výchozím stavu 2 e-maily za sekundu).
- Zajistěte bezpečné opakování. Pokud po vypršení časového limitu požadavek opakujete, pošlete přes cURL hlavičku
Idempotency-Key, aby se e-mail neodeslal dvakrát. Viz Idempotentní požadavky. - Držte klíče mimo kořenový adresář webu. Nikdy necommitujte klíče ani soubory
.enva pro každou aplikaci používejte samostatný klíč.