Send email with PHP

Quickstart#

1. Install the SDK

   Nothing to install: the examples use PHP’s cURL extension, which most PHP builds include. Check that it is loaded:

   bash

   php -m | grep -i curl   # prints "curl" when the extension is available

2. Initialize the client

   php

   $apiKey = getenv('POSTSTACK_API_KEY');
   $baseUrl = 'https://api.poststack.dev';

3. Send an email

   php

   <?php
   $apiKey = getenv('POSTSTACK_API_KEY');
   
   $payload = json_encode([
       'from' => 'hello@yourdomain.com',
       'to' => ['user@example.com'],
       'subject' => 'Hello from PHP!',
       'html' => '<h1>Welcome!</h1>',
   ]);
   
   $ch = curl_init('https://api.poststack.dev/emails');
   curl_setopt_array($ch, [
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_POST => true,
       CURLOPT_POSTFIELDS => $payload,
       CURLOPT_HTTPHEADER => [
           'Authorization: Bearer ' . $apiKey,
           'Content-Type: application/json',
       ],
   ]);
   
   $response = curl_exec($ch);
   $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
   
   echo $status, ' ', $response;   // 202 {"id":"em_..."}

4. Handle errors

   php

   <?php
   
   class PoststackException extends RuntimeException {
       public int $statusCode;
       public ?string $requestId;
       public function __construct(int $statusCode, string $message, ?string $requestId = null) {
           parent::__construct($message);
           $this->statusCode = $statusCode;
           $this->requestId = $requestId;
       }
   }
   
   function send_email(array $payload, int $attempts = 3): array {
       $apiKey = getenv('POSTSTACK_API_KEY');
       // One key for every attempt: a retry after a lost response replays the
       // original send instead of delivering a second copy.
       $idempotencyKey = bin2hex(random_bytes(16));
   
       for ($i = 0; $i < $attempts; $i++) {
           $ch = curl_init('https://api.poststack.dev/emails');
           curl_setopt_array($ch, [
               CURLOPT_RETURNTRANSFER => true,
               CURLOPT_POST => true,
               CURLOPT_TIMEOUT => 10,
               CURLOPT_POSTFIELDS => json_encode($payload),
               CURLOPT_HTTPHEADER => [
                   'Authorization: Bearer ' . $apiKey,
                   'Content-Type: application/json',
                   'Idempotency-Key: ' . $idempotencyKey,
               ],
           ]);
           $response = curl_exec($ch);
           $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
           if ($response === false) {          // network error or timeout
               sleep(2 ** $i);
               continue;
           }
   
           if ($status >= 200 && $status < 300) {
               return json_decode($response, true);
           }
           if ($status === 429 || $status >= 500) {
               sleep(2 ** $i);
               continue;
           }
           throw new PoststackException($status, (string) $response);
       }
       throw new RuntimeException('send_email retries exhausted');
   }

Framework integrations#

Common pitfalls#

FAQ#

Reference#

The docs this guide builds on:

• SDKs — every official client, its retries and idempotency keys
• SMTP relay — hosts, ports, TLS modes and the X-PostStack-* headers
• Emails API — every send field, attachments, scheduling and batch sends
• Templates — stored templates with variables
• Webhooks — event types, payloads and signature verification
• Suppressions — what happens to an address after a hard bounce or complaint

Next steps