Postmark Mailer Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require symfony/mailer symfony/postmark-mailer
   

   Add to config/mail.php:

   'transport' => [
       'postmark' => [
           'server' => env('POSTMARK_SERVER_TOKEN'),
       ],
   ],
   

2. First Use Case Inject Symfony\Component\Mailer\MailerInterface into a controller/service:

   use Symfony\Component\Mailer\MailerInterface;
   use Symfony\Component\Mailer\Envelope;
   
   public function sendWelcomeEmail(MailerInterface $mailer)
   {
       $email = (new Email())
           ->from('noreply@example.com')
           ->to('user@example.com')
           ->subject('Welcome!')
           ->html('<h1>Hello!</h1>');
   
       $mailer->send($email);
   }
   

3. Environment Setup Set POSTMARK_SERVER_TOKEN in .env:

   POSTMARK_SERVER_TOKEN=your_token_here
   

Implementation Patterns

Common Workflows

1. Transactional Emails Use for password resets, notifications, and alerts:

   $mailer->send((new Email())
       ->to($user->email)
       ->subject('Reset Password')
       ->text('Click here to reset: ' . route('password.reset', ['token' => $token]))
   );
   

2. Templates & Variables Leverage Postmark’s templates with dynamic content:

   $email = (new Email())
       ->to('user@example.com')
       ->subject('Your Order Confirmation')
       ->html('<p>Order #{{orderId}} confirmed!</p>', [
           'orderId' => $order->id,
       ]);
   

3. Attachments & Inline Images

   $email = (new Email())
       ->attachFromPath('/path/to/file.pdf')
       ->embed($mailer->embedFromPath('/path/to/image.png'))
       ->html('<img src="cid:embedded-image">');
   

4. Bulk Emails Use MailerInterface::send() in batches with foreach loops:

   foreach ($users as $user) {
       $mailer->send((new Email())
           ->to($user->email)
           ->subject('Weekly Digest')
           ->html($digestHtml)
       );
   }
   

5. Async Processing Queue emails with Laravel’s queue system:

   use Illuminate\Bus\Queueable;
   use Illuminate\Contracts\Queue\ShouldQueue;
   
   class SendWelcomeEmail implements ShouldQueue
   {
       use Queueable;
   
       public function handle(MailerInterface $mailer)
       {
           $mailer->send((new Email())->to('user@example.com')->subject('Welcome!'));
       }
   }
   

Gotchas and Tips

Pitfalls

1. Token Security

   • Never hardcode POSTMARK_SERVER_TOKEN in code. Always use .env.
   • Restrict token permissions in Postmark dashboard to only necessary actions (e.g., send, templates).

2. Template Mismatches

   • Postmark templates use {{variable}} syntax. Laravel’s Email class uses PHP arrays for replacements. Ensure consistency:

     // Correct: Matches Postmark template syntax
     $email->html('<p>{{name}}</p>', ['name' => 'John']);
     

3. Rate Limits

   • Postmark has sending limits. Monitor usage via Postmark dashboard or webhooks.

4. Debugging

   • Enable Symfony Mailer’s debug mode in config/mail.php:

     'debug' => env('MAIL_DEBUG', false),
     

   • Check logs for failed sends:

     tail -f storage/logs/laravel.log | grep "PostmarkTransport"
     

5. Character Encoding

   • Ensure subject/body text is UTF-8 encoded to avoid corruption in emails.

Tips

1. Webhook Integration Use Postmark’s delivery notifications to track opens/clicks:

   // In a Laravel controller
   public function handlePostmarkWebhook(Request $request)
   {
       $event = $request->input('Event');
       if ($event === 'Delivery') {
           // Log or process delivery data
       }
   }
   

2. Testing Use Postmark’s sandbox mode (via token) or Laravel’s MailFake for testing:

   // config/mail.php (for testing)
   'transport' => [
       'postmark' => [
           'server' => env('POSTMARK_SANDBOX_TOKEN'),
       ],
   ],
   

3. Performance

   • Batch emails to avoid hitting rate limits:

     $mailer->send($email1);
     $mailer->send($email2);
     // ... up to 100 emails per batch (Postmark's recommended limit)
     

4. Custom Headers Add headers for tracking or custom logic:

   $email = (new Email())
       ->to('user@example.com')
       ->getHeaders()->addTextHeader('X-Custom-ID', $user->id);
   

5. Fallback Transport Configure a fallback transport in config/mail.php for high availability:

   'transport' => [
       'postmark' => [
           'server' => env('POSTMARK_TOKEN'),
       ],
       'fallback' => [
           'dsn' => env('MAILER_DSN_FALLBACK'),
       ],
   ],