Mailrelay Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require arrogance/mailrelay-bundle ^1.0
   

   Register the bundle in config/bundles.php (Laravel 5.4+):

   Arrogance\MailrelayBundle\ArroganceMailrelayBundle::class => ['env' => 'prod'],
   

2. Configuration: Add to .env:

   MAILRELAY_API_KEY=your_api_key_here
   MAILRELAY_ACCESS_POINT=yourUser.ip-zone.com
   

   Or in config/arrogance_mailrelay.php:

   return [
       'api_key' => env('MAILRELAY_API_KEY'),
       'access_point' => env('MAILRELAY_ACCESS_POINT'),
   ];
   

3. First Use Case: Send a basic email via a service:

   use Arrogance\MailrelayBundle\Email\Email;
   use Arrogance\MailrelayBundle\MailrelayClient;
   
   $client = app(MailrelayClient::class);
   $email = (new Email())
       ->addEmail('recipient@example.com', 'Recipient Name')
       ->setSubject('Test Email')
       ->setHtml('<p>Hello from Laravel!</p>')
       ->setFromId(1); // Replace with your Mailrelay contact ID
   
   $response = $client->sendMail($email);
   

Implementation Patterns

Core Workflows

1. Email Composition: Use the Email class to build emails programmatically:

   $email = (new Email())
       ->addEmail('user@example.com', 'User')
       ->addCc('manager@example.com')
       ->setSubject('Weekly Report')
       ->setHtml(view('emails.report')->render())
       ->setReplyId(2); // Optional reply-to contact ID
   

2. Tracking & Analytics: Leverage Mailrelay’s built-in tracking via getEmailStats():

   $stats = $client->getEmailStats($email->getId());
   // Access opens, clicks, bounces, etc.
   

3. Bulk Emails: Use setPackageId() for bulk campaigns:

   $email->setPackageId(123); // Predefined Mailrelay package
   

4. Templating Integration: Combine with Laravel’s Blade:

   $email->setHtml(view('emails.welcome', ['user' => $user])->render());
   

Integration Tips

• Service Container: Bind the client to Laravel’s container in AppServiceProvider:

  $this->app->bind(MailrelayClient::class, function ($app) {
      return new MailrelayClient(
          $app['config']['arrogance_mailrelay.api_key'],
          $app['config']['arrogance_mailrelay.access_point']
      );
  });
  

• Queue Jobs: Dispatch emails asynchronously:

  use Arrogance\MailrelayBundle\Jobs\SendMailJob;
  
  SendMailJob::dispatch($email)->onQueue('mailrelay');
  

• Event Listeners: Hook into Mailrelay’s webhooks for real-time updates:

  // config/arrogance_mailrelay.php
  'webhook' => [
      'url' => route('mailrelay.webhook'),
      'events' => ['open', 'click', 'bounce'],
  ];
  

Gotchas and Tips

Pitfalls

1. API Key Security:

   • Never hardcode api_key in config files. Use Laravel’s .env.
   • Restrict Mailrelay API access via IP whitelisting.

2. Contact IDs:

   • setFromId(), setReplyId(), etc., require valid Mailrelay contact IDs. Fetch these via Mailrelay’s dashboard or API:

     $contacts = $client->getContacts();
     

3. Rate Limits:

   • Mailrelay enforces sending limits. Monitor via $client->getSendingStats().

4. HTML Emails:

   • Ensure HTML content is properly escaped to avoid rendering issues. Use Laravel’s e() helper or htmlspecialchars().

5. Deprecated Methods:

   • The bundle is archived; some methods may lack documentation. Check the wiki for updates.

Debugging

• Enable Logging: Add to config/arrogance_mailrelay.php:

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

  Logs will appear in storage/logs/laravel.log.

• Response Handling: Validate Mailrelay’s response structure:

  $response = $client->sendMail($email);
  if ($response->getStatus() !== 200) {
      throw new \RuntimeException($response->getError());
  }
  

Extension Points

1. Custom Email Classes: Extend Email to add domain-specific methods:

   class CustomEmail extends Email {
       public function setTransactionalTemplate(string $template) {
           $this->setHtml(view("emails.$template")->render());
           return $this;
       }
   }
   

2. Webhook Handling: Create a controller to process Mailrelay webhooks:

   public function handleWebhook(Request $request) {
       $client->processWebhook($request->all());
   }
   

3. Fallback SMTP: Implement a fallback to Laravel’s default mailer if Mailrelay fails:

   try {
       $client->sendMail($email);
   } catch (\Exception $e) {
       Mail::send([], [], function ($message) use ($email) {
           $message->to($email->getEmails()[0])
                   ->subject($email->getSubject())
                   ->html($email->getHtml());
       });
   }
   

4. Testing: Use Laravel’s MailFake for unit tests:

   public function testMailrelayIntegration() {
       $this->partialMock(MailrelayClient::class, function ($mock) {
           $mock->shouldReceive('sendMail')->andReturn(new Response(200, []));
       });
   }