Resend Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require resend/resend-laravel
   

2. Configure API Key Add to .env:

   RESEND_API_KEY=re_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   

3. First Email Use the facade directly:

   use Resend\Laravel\Facades\Resend;
   
   Resend::emails()->send([
       'from' => 'acme@resend.dev',
       'to' => 'user@example.com',
       'subject' => 'Welcome!',
       'html' => '<p>Hello!</p>',
   ]);
   

First Use Case: Mailable Integration

Replace Laravel's default mailer in config/mail.php:

'default' => env('MAIL_MAILER', 'resend'),
'resend' => [
    'transport' => 'resend',
],

Set MAIL_MAILER=resend in .env and use Laravel's Mailable classes as usual:

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

Implementation Patterns

Core Workflows

1. Direct API Calls Use the facade for non-Mailable emails:

   Resend::emails()->send([
       'from' => 'noreply@acme.com',
       'to' => ['user1@example.com', 'user2@example.com'],
       'subject' => 'Monthly Report',
       'html' => view('emails.report')->render(),
       'attachments' => [
           ['filename' => 'report.pdf', 'content' => file_get_contents('path/to/report.pdf')],
       ],
   ]);
   

2. Mailable Integration Extend Laravel's Mailable class:

   class WelcomeMail extends Mailable {
       public function build() {
           return $this->subject('Welcome!')
               ->markdown('emails.welcome')
               ->with(['name' => 'John'])
               ->attach('path/to/file.pdf');
       }
   }
   

3. Webhook Handling Register the middleware in app/Http/Kernel.php:

   protected $middleware = [
       // ...
       \Resend\Laravel\Http\Middleware\VerifyWebhookSignature::class,
   ];
   

   Handle events in a controller:

   public function handleWebhook(Request $request) {
       $event = $request->resend_event;
       if ($event->type === 'email.delivered') {
           // Update database
       }
   }
   

Advanced Patterns

1. Idempotency Keys Prevent duplicate sends:

   Resend::emails()->send([
       // ... email data ...
       'idempotency_key' => 'unique-key-123',
   ]);
   

2. Tags & Metadata Categorize emails for analytics:

   Resend::emails()->send([
       // ... email data ...
       'tags' => ['newsletter', 'welcome'],
       'metadata' => ['user_id' => 123],
   ]);
   

3. Inline Attachments Embed images in HTML:

   $email = Resend::emails()->send([
       'from' => 'acme@resend.dev',
       'to' => 'user@example.com',
       'html' => '<img src="cid:logo">',
       'attachments' => [
           ['content_id' => 'logo', 'content' => file_get_contents('logo.png')],
       ],
   ]);
   

Gotchas and Tips

Common Pitfalls

1. API Key Validation

   • Ensure RESEND_API_KEY is set and valid. Test with:

     Resend::api()->verifyApiKey();
     

   • Throws Resend\Exceptions\ApiKeyInvalidException if invalid.

2. Attachment Headers

   • Custom headers (e.g., Content-Disposition) may be stripped. Use the attach() method in Mailable:

     $this->attach('file.pdf', [
         'as' => 'custom-name.pdf',
         'mime' => 'application/pdf',
     ]);
     

3. Webhook Signatures

   • Always use VerifyWebhookSignature middleware to validate Resend's signatures.
   • Debug failed signatures with:

     $request->resend_signature; // Check raw signature
     $request->resend_timestamp; // Verify timestamp
     

4. Rate Limits

   • Resend enforces rate limits. Handle Resend\Exceptions\RateLimitException gracefully:

     try {
         Resend::emails()->send([...]);
     } catch (\Resend\Exceptions\RateLimitException $e) {
         Log::warning('Rate limited. Retrying in 60s...');
         sleep(60);
         retry();
     }
     

Debugging Tips

1. Enable Verbose Logging Add to config/resend.php:

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

   Logs API requests/responses to storage/logs/resend.log.

2. Inspect Sent Emails Use the sent method to fetch recent emails:

   $emails = Resend::emails()->sent()->get();
   dd($emails[0]->id); // Debug email ID
   

3. Test Webhooks Locally Use ngrok to expose a local endpoint:

   ngrok http 8000
   

   Configure Resend webhook URL to https://your-ngrok-url.ngrok.io/webhook.

Extension Points

1. Custom Transport Extend ResendTransport for custom logic:

   class CustomResendTransport extends \Resend\Laravel\Transport\ResendTransport {
       public function send(SentMessage $message) {
           // Modify payload before sending
           $payload = $this->preparePayload($message);
           $payload['custom_field'] = 'value';
           return parent::send($message);
       }
   }
   

   Bind in AppServiceProvider:

   Mail::extend('custom_resend', function () {
       return new CustomResendTransport();
   });
   

2. Event Listeners Listen for Resend events (e.g., email.sent):

   Resend::emails()->sent(function ($email) {
       // Log or process sent email
   });
   

3. Configuration Publishing Publish the config for customization:

   php artisan vendor:publish --provider="Resend\Laravel\ResendServiceProvider" --tag="resend-config"
   

   Modify config/resend.php to override defaults (e.g., API endpoint).