Initial release

.gitignore

@@ -0,0 +1,5 @@
+/vendor/
+/node_modules/
+.phpunit.cache/
+.phpunit.result.cache
+composer.lock

README.md

@@ -0,0 +1,106 @@
+# LeadMail SDK for Laravel
+
+Laravel package for sending emails and verifying email addresses through the [leadMail](https://mail.leadmagnet.dev) service.
+
+## Requirements
+
+- PHP 8.2+
+- Laravel 11 or 12
+
+## Installation
+
+```bash
+composer require leadm/leadmail
+```
+
+Publish the config file:
+
+```bash
+php artisan vendor:publish --provider="LeadM\LeadMail\LeadMailServiceProvider"
+```
+
+## Configuration
+
+Add these to your `.env`:
+
+```env
+LEADMAIL_URL=https://mail.leadmagnet.dev
+LEADMAIL_TOKEN=lm_your_api_token_here
+```
+
+Optional settings:
+
+```env
+LEADMAIL_TIMEOUT=30
+LEADMAIL_VERIFY_SSL=true
+LEADMAIL_AUTO_TENANT=true
+```
+
+## Usage
+
+### Send Emails via Mail Driver
+
+Set `leadmail` as your mail driver in `.env`:
+
+```env
+MAIL_MAILER=leadmail
+```
+
+Then use Laravel's `Mail` facade as usual:
+
+```php
+Mail::to('user@example.com')->send(new WelcomeMail());
+```
+
+### Send Emails via API
+
+```php
+LeadMail::sendEmail([
+    'from' => ['email' => 'hello@yourdomain.com', 'name' => 'Your App'],
+    'to' => [['email' => 'user@example.com', 'name' => 'User']],
+    'subject' => 'Welcome!',
+    'html_body' => '<h1>Welcome to our app</h1>',
+]);
+```
+
+### Verify Email Addresses
+
+```php
+$result = LeadMail::verifyEmail('user@example.com');
+
+if ($result['data']['valid']) {
+    // Email is deliverable
+}
+```
+
+### Validation Rule
+
+Use the `leadmail_verify` rule in your form requests:
+
+```php
+public function rules(): array
+{
+    return [
+        'email' => ['required', 'email', 'leadmail_verify'],
+    ];
+}
+```
+
+### Get Allowed Sender Domains
+
+```php
+$domains = LeadMail::getDomains();
+// ['yourdomain.com', 'anotherdomain.com']
+```
+
+## Multi-Tenancy
+
+If your app uses [stancl/tenancy](https://tenancyforlaravel.com), the SDK automatically includes the current tenant ID in API requests via the `X-Tenant-Id` header. Disable this with:
+
+```env
+LEADMAIL_AUTO_TENANT=false
+```
+
+## License
+
+MIT

composer.json

@@ -0,0 +1,49 @@
+{
+    "name": "leadm/leadmail",
+    "description": "Laravel SDK for leadMail email sending and verification service",
+    "type": "library",
+    "license": "MIT",
+    "homepage": "https://github.com/leadmnik/leadmail-sdk",
+    "authors": [
+        {
+            "name": "Lead Magnet Oy",
+            "homepage": "https://leadmagnet.fi"
+        }
+    ],
+    "support": {
+        "issues": "https://github.com/leadmnik/leadmail-sdk/issues",
+        "source": "https://github.com/leadmnik/leadmail-sdk"
+    },
+    "require": {
+        "php": "^8.2",
+        "guzzlehttp/guzzle": "^7.0",
+        "illuminate/mail": "^11.0|^12.0",
+        "illuminate/support": "^11.0|^12.0"
+    },
+    "require-dev": {
+        "orchestra/testbench": "^9.0|^10.0",
+        "pestphp/pest": "^3.0|^4.0"
+    },
+    "autoload": {
+        "psr-4": {
+            "LeadM\\LeadMail\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "LeadM\\LeadMail\\Tests\\": "tests/"
+        }
+    },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "LeadM\\LeadMail\\LeadMailServiceProvider"
+            ],
+            "aliases": {
+                "LeadMail": "LeadM\\LeadMail\\LeadMailFacade"
+            }
+        }
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true
+}

config/leadmail.php

@@ -0,0 +1,55 @@
+<?php
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | LeadMail Service URL
+    |--------------------------------------------------------------------------
+    |
+    | The base URL of your leadMail service instance.
+    |
+    */
+    'url' => env('LEADMAIL_URL', 'https://mail.leadmagnet.dev'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | API Token
+    |--------------------------------------------------------------------------
+    |
+    | The bearer token for authenticating with the leadMail API.
+    | Generate this in the leadMail admin dashboard.
+    |
+    */
+    'token' => env('LEADMAIL_TOKEN'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Request Timeout
+    |--------------------------------------------------------------------------
+    |
+    | Maximum number of seconds to wait for API responses.
+    |
+    */
+    'timeout' => env('LEADMAIL_TIMEOUT', 30),
+
+    /*
+    |--------------------------------------------------------------------------
+    | SSL Verification
+    |--------------------------------------------------------------------------
+    |
+    | Whether to verify SSL certificates. Disable only for local development.
+    |
+    */
+    'verify_ssl' => env('LEADMAIL_VERIFY_SSL', true),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Auto Tenant Detection
+    |--------------------------------------------------------------------------
+    |
+    | When enabled and stancl/tenancy is installed, automatically sends the
+    | current tenant's key as the X-Tenant-Id header on every request.
+    |
+    */
+    'auto_tenant' => env('LEADMAIL_AUTO_TENANT', true),
+];

src/LeadMailClient.php

@@ -0,0 +1,133 @@
+<?php
+
+namespace LeadM\LeadMail;
+
+use GuzzleHttp\Client;
+use GuzzleHttp\Exception\GuzzleException;
+use Illuminate\Support\Facades\Log;
+
+class LeadMailClient
+{
+    protected Client $http;
+
+    public function __construct(
+        protected readonly string $baseUrl,
+        protected readonly string $token,
+        protected readonly int $timeout = 30,
+        protected readonly bool $verifySsl = true,
+        protected readonly bool $autoTenant = true,
+    ) {
+        $this->http = new Client([
+            'base_uri' => rtrim($this->baseUrl, '/').'/api/v1/',
+            'timeout' => $this->timeout,
+            'verify' => $this->verifySsl,
+        ]);
+    }
+
+    /**
+     * Send an email through the leadMail service.
+     *
+     * @param  array{from: array, to: array, cc?: array, bcc?: array, reply_to?: array, subject: string, html_body?: string, text_body?: string, attachments?: array, metadata?: array, options?: array}  $data
+     * @return array{success: bool, data: array{log_id: int, status: string}}
+     *
+     * @throws GuzzleException
+     */
+    public function sendEmail(array $data): array
+    {
+        $response = $this->http->post('emails/send', [
+            'headers' => $this->headers(),
+            'json' => $data,
+        ]);
+
+        return json_decode($response->getBody()->getContents(), true);
+    }
+
+    /**
+     * Get the allowed sender domains for this client app.
+     *
+     * @return string[]
+     *
+     * @throws GuzzleException
+     */
+    public function getDomains(): array
+    {
+        $response = $this->http->get('domains', [
+            'headers' => $this->headers(),
+        ]);
+
+        $data = json_decode($response->getBody()->getContents(), true);
+
+        return $data['data']['domains'] ?? [];
+    }
+
+    /**
+     * Verify an email address through the leadMail service.
+     *
+     * @return array{success: bool, data: array{email: string, valid: bool, status: string, reason: ?string, cached: bool}}
+     */
+    public function verifyEmail(string $email, bool $allowDisposable = false): array
+    {
+        try {
+            $response = $this->http->post('emails/verify', [
+                'headers' => $this->headers(),
+                'json' => [
+                    'email' => $email,
+                    'allow_disposable' => $allowDisposable,
+                ],
+            ]);
+
+            return json_decode($response->getBody()->getContents(), true);
+        } catch (GuzzleException $e) {
+            Log::warning('LeadMail verification failed, failing open', [
+                'email' => $email,
+                'error' => $e->getMessage(),
+            ]);
+
+            return [
+                'success' => true,
+                'data' => [
+                    'email' => $email,
+                    'valid' => true,
+                    'status' => 'unknown',
+                    'reason' => null,
+                    'cached' => false,
+                ],
+            ];
+        }
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    protected function headers(): array
+    {
+        $headers = [
+            'Authorization' => 'Bearer '.$this->token,
+            'Accept' => 'application/json',
+            'Content-Type' => 'application/json',
+        ];
+
+        if ($this->autoTenant && $this->hasTenancy()) {
+            $tenantId = $this->resolveTenantId();
+            if ($tenantId !== null) {
+                $headers['X-Tenant-Id'] = $tenantId;
+            }
+        }
+
+        return $headers;
+    }
+
+    protected function hasTenancy(): bool
+    {
+        return class_exists(\Stancl\Tenancy\Tenancy::class);
+    }
+
+    protected function resolveTenantId(): ?string
+    {
+        if (! function_exists('tenancy') || ! tenancy()->initialized) {
+            return null;
+        }
+
+        return (string) tenant()->getTenantKey();
+    }
+}

src/LeadMailFacade.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace LeadM\LeadMail;
+
+use Illuminate\Support\Facades\Facade;
+
+/**
+ * @method static array sendEmail(array $data)
+ * @method static string[] getDomains()
+ * @method static array verifyEmail(string $email, bool $allowDisposable = false)
+ *
+ * @see \LeadM\LeadMail\LeadMailClient
+ */
+class LeadMailFacade extends Facade
+{
+    protected static function getFacadeAccessor(): string
+    {
+        return LeadMailClient::class;
+    }
+}

src/LeadMailServiceProvider.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace LeadM\LeadMail;
+
+use Illuminate\Support\Facades\Mail;
+use Illuminate\Support\Facades\Validator;
+use Illuminate\Support\ServiceProvider;
+use LeadM\LeadMail\Rules\LeadMailVerify;
+
+class LeadMailServiceProvider extends ServiceProvider
+{
+    public function register(): void
+    {
+        $this->mergeConfigFrom(__DIR__.'/../config/leadmail.php', 'leadmail');
+
+        $this->app->singleton(LeadMailClient::class, function () {
+            return new LeadMailClient(
+                baseUrl: config('leadmail.url'),
+                token: config('leadmail.token', ''),
+                timeout: config('leadmail.timeout', 30),
+                verifySsl: config('leadmail.verify_ssl', true),
+                autoTenant: config('leadmail.auto_tenant', true),
+            );
+        });
+    }
+
+    public function boot(): void
+    {
+        if ($this->app->runningInConsole()) {
+            $this->publishes([
+                __DIR__.'/../config/leadmail.php' => config_path('leadmail.php'),
+            ], 'leadmail-config');
+        }
+
+        Mail::extend('leadmail', function () {
+            return new LeadMailTransport(
+                $this->app->make(LeadMailClient::class),
+            );
+        });
+
+        Validator::extend('leadmail_verify', function (string $attribute, mixed $value) {
+            $rule = $this->app->make(LeadMailVerify::class);
+            $passed = true;
+
+            $rule->validate($attribute, $value, function () use (&$passed) {
+                $passed = false;
+            });
+
+            return $passed;
+        }, 'The :attribute email address could not be verified.');
+    }
+}

src/LeadMailTransport.php

@@ -0,0 +1,105 @@
+<?php
+
+namespace LeadM\LeadMail;
+
+use Symfony\Component\Mailer\SentMessage;
+use Symfony\Component\Mailer\Transport\AbstractTransport;
+use Symfony\Component\Mime\Address;
+use Symfony\Component\Mime\Email;
+use Symfony\Component\Mime\MessageConverter;
+
+class LeadMailTransport extends AbstractTransport
+{
+    public function __construct(
+        protected readonly LeadMailClient $client,
+    ) {
+        parent::__construct();
+    }
+
+    protected function doSend(SentMessage $message): void
+    {
+        $email = MessageConverter::toEmail($message->getOriginalMessage());
+
+        $payload = $this->buildPayload($email);
+
+        $result = $this->client->sendEmail($payload);
+
+        if (isset($result['data']['log_id'])) {
+            $message->getOriginalMessage()->getHeaders()->addTextHeader(
+                'X-LeadMail-Log-Id',
+                (string) $result['data']['log_id'],
+            );
+        }
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    protected function buildPayload(Email $email): array
+    {
+        $payload = [
+            'from' => $this->formatAddress($email->getFrom()[0] ?? null),
+            'to' => array_map(fn (Address $a) => $this->formatAddress($a), $email->getTo()),
+            'subject' => $email->getSubject() ?? '',
+        ];
+
+        if ($email->getCc()) {
+            $payload['cc'] = array_map(fn (Address $a) => $this->formatAddress($a), $email->getCc());
+        }
+
+        if ($email->getBcc()) {
+            $payload['bcc'] = array_map(fn (Address $a) => $this->formatAddress($a), $email->getBcc());
+        }
+
+        if ($email->getReplyTo()) {
+            $replyTo = $email->getReplyTo()[0];
+            $payload['reply_to'] = $this->formatAddress($replyTo);
+        }
+
+        if ($email->getHtmlBody()) {
+            $payload['html_body'] = $email->getHtmlBody();
+        }
+
+        if ($email->getTextBody()) {
+            $payload['text_body'] = $email->getTextBody();
+        }
+
+        $attachments = [];
+        foreach ($email->getAttachments() as $attachment) {
+            $attachments[] = [
+                'content' => base64_encode($attachment->getBody()),
+                'filename' => $attachment->getFilename() ?? 'attachment',
+                'mime_type' => $attachment->getMediaType().'/'.$attachment->getMediaSubtype(),
+            ];
+        }
+
+        if ($attachments) {
+            $payload['attachments'] = $attachments;
+        }
+
+        return $payload;
+    }
+
+    /**
+     * @return array{email: string, name?: string}
+     */
+    protected function formatAddress(?Address $address): array
+    {
+        if ($address === null) {
+            return ['email' => ''];
+        }
+
+        $result = ['email' => $address->getAddress()];
+
+        if ($address->getName()) {
+            $result['name'] = $address->getName();
+        }
+
+        return $result;
+    }
+
+    public function __toString(): string
+    {
+        return 'leadmail';
+    }
+}

src/Rules/LeadMailVerify.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace LeadM\LeadMail\Rules;
+
+use Closure;
+use Illuminate\Contracts\Validation\ValidationRule;
+use LeadM\LeadMail\LeadMailClient;
+
+class LeadMailVerify implements ValidationRule
+{
+    public function __construct(
+        protected readonly LeadMailClient $client,
+        protected readonly bool $allowDisposable = false,
+    ) {}
+
+    public function validate(string $attribute, mixed $value, Closure $fail): void
+    {
+        if (! is_string($value) || ! filter_var($value, FILTER_VALIDATE_EMAIL)) {
+            $fail('The :attribute must be a valid email address.');
+
+            return;
+        }
+
+        try {
+            $result = $this->client->verifyEmail($value, $this->allowDisposable);
+
+            if (! ($result['data']['valid'] ?? true)) {
+                $reason = $result['data']['reason'] ?? 'verification failed';
+                $fail("The :attribute email address is not deliverable ({$reason}).");
+            }
+        } catch (\Throwable) {
+            // Fail open — if the verification service is down, allow the email through
+        }
+    }
+}