Add per-customer SMS and Bird Integrations for event messaging.

Attendee and speaker comms use encrypted tenant relay credentials and skip platform-key fallback and Bird wallet double-debit.

Co-authored-by: Cursor <cursoragent@cursor.com>

app/Http/Controllers/Events/AttendeeController.php

@@ -182,8 +182,8 @@ class AttendeeController extends Controller
         ]);
 
         $preview = $this->comms->preview($event, $validated['mode']);
-        if (! $preview['affordable']) {
-            return back()->with('error', 'Insufficient wallet balance. Add funds in Billing before sending.');
+        if ($preview['integrations_error'] ?? null) {
+            return back()->with('error', $preview['integrations_error']);
         }
 
         if ($preview['recipients'] === 0) {

app/Http/Controllers/Qr/IntegrationsController.php

@@ -0,0 +1,102 @@
+<?php
+
+namespace App\Http\Controllers\Qr;
+
+use App\Http\Controllers\Controller;
+use App\Services\Messaging\CustomerSmsClient;
+use App\Services\Messaging\MessagingCredentialsService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Illuminate\View\View;
+
+class IntegrationsController extends Controller
+{
+    public function edit(MessagingCredentialsService $credentials): View
+    {
+        $account = ladill_account();
+
+        return view('qr.account.integrations', [
+            'account' => $account,
+            'credential' => $credentials->forOwner((string) $account->public_id),
+        ]);
+    }
+
+    public function saveSms(Request $request, MessagingCredentialsService $credentials): RedirectResponse
+    {
+        $account = ladill_account();
+        $ownerRef = (string) $account->public_id;
+
+        $data = $request->validate([
+            'sms_api_key' => ['required', 'string', 'max:200'],
+            'sms_sender_id' => ['required', 'string', 'max:11'],
+        ]);
+
+        $result = $credentials->validateAndSaveSms(
+            $ownerRef,
+            $data['sms_api_key'],
+            $data['sms_sender_id'],
+        );
+
+        if (! ($result['ok'] ?? false)) {
+            return back()->withInput()->with('error', $result['error'] ?? 'Could not save SMS credentials.');
+        }
+
+        return back()->with('success', 'Ladill SMS connected. Outbound attendee SMS will use your key and sender ID.');
+    }
+
+    public function disconnectSms(MessagingCredentialsService $credentials): RedirectResponse
+    {
+        $account = ladill_account();
+        $credentials->disconnectSms((string) $account->public_id);
+
+        return back()->with('success', 'Ladill SMS disconnected.');
+    }
+
+    public function saveBird(Request $request, MessagingCredentialsService $credentials): RedirectResponse
+    {
+        $account = ladill_account();
+        $ownerRef = (string) $account->public_id;
+
+        $data = $request->validate([
+            'bird_api_key' => ['required', 'string', 'max:200'],
+            'bird_from_email' => ['required', 'email', 'max:255'],
+            'bird_from_name' => ['nullable', 'string', 'max:100'],
+        ]);
+
+        $result = $credentials->validateAndSaveBird(
+            $ownerRef,
+            $data['bird_api_key'],
+            $data['bird_from_email'],
+            $data['bird_from_name'] ?? null,
+        );
+
+        if (! ($result['ok'] ?? false)) {
+            return back()->withInput()->with('error', $result['error'] ?? 'Could not save Bird credentials.');
+        }
+
+        return back()->with('success', 'Ladill Bird connected. Outbound attendee email will use your key and from address.');
+    }
+
+    public function disconnectBird(MessagingCredentialsService $credentials): RedirectResponse
+    {
+        $account = ladill_account();
+        $credentials->disconnectBird((string) $account->public_id);
+
+        return back()->with('success', 'Ladill Bird disconnected.');
+    }
+
+    public function previewSenders(Request $request, CustomerSmsClient $sms): JsonResponse
+    {
+        $data = $request->validate([
+            'sms_api_key' => ['required', 'string', 'max:200'],
+        ]);
+
+        $result = $sms->senders(trim($data['sms_api_key']));
+        if (! ($result['ok'] ?? false)) {
+            return response()->json(['error' => $result['error'] ?? 'Could not load senders.'], 422);
+        }
+
+        return response()->json($result['data'] ?? []);
+    }
+}

app/Models/MessagingCredential.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Facades\Crypt;
+
+class MessagingCredential extends Model
+{
+    public const STATUS_VALID = 'valid';
+
+    public const STATUS_INVALID = 'invalid';
+
+    protected $table = 'events_messaging_credentials';
+
+    protected $fillable = [
+        'owner_ref',
+        'sms_api_key_encrypted',
+        'sms_api_key_prefix',
+        'sms_sender_id',
+        'sms_status',
+        'sms_validated_at',
+        'sms_last_error',
+        'bird_api_key_encrypted',
+        'bird_api_key_prefix',
+        'bird_from_email',
+        'bird_from_name',
+        'bird_status',
+        'bird_validated_at',
+        'bird_last_error',
+    ];
+
+    protected $hidden = [
+        'sms_api_key_encrypted',
+        'bird_api_key_encrypted',
+    ];
+
+    protected $casts = [
+        'sms_validated_at' => 'datetime',
+        'bird_validated_at' => 'datetime',
+    ];
+
+    public function hasValidSms(): bool
+    {
+        return $this->sms_status === self::STATUS_VALID
+            && filled($this->sms_api_key_encrypted)
+            && filled($this->sms_sender_id);
+    }
+
+    public function hasValidBird(): bool
+    {
+        return $this->bird_status === self::STATUS_VALID
+            && filled($this->bird_api_key_encrypted)
+            && filled($this->bird_from_email);
+    }
+
+    public function smsApiKey(): ?string
+    {
+        if (! filled($this->sms_api_key_encrypted)) {
+            return null;
+        }
+
+        try {
+            return Crypt::decryptString($this->sms_api_key_encrypted);
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+
+    public function birdApiKey(): ?string
+    {
+        if (! filled($this->bird_api_key_encrypted)) {
+            return null;
+        }
+
+        try {
+            return Crypt::decryptString($this->bird_api_key_encrypted);
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+
+    public static function encryptKey(string $plain): string
+    {
+        return Crypt::encryptString($plain);
+    }
+}

app/Services/Billing/SmsService.php

@@ -2,15 +2,32 @@
 
 namespace App\Services\Billing;
 
+use App\Services\Messaging\CustomerSmsClient;
+use App\Services\Messaging\MessagingCredentialsService;
+
 class SmsService
 {
-    public function __construct(private readonly PlatformSmsClient $platform) {}
+    private ?string $lastError = null;
 
-    public function send(string $ownerPublicId, string $to, string $message): void
+    public function __construct(
+        private readonly CustomerSmsClient $customer,
+        private readonly MessagingCredentialsService $credentials,
+    ) {}
+
+    public function lastError(): ?string
     {
+        return $this->lastError;
+    }
+
+    public function send(string $ownerPublicId, string $to, string $message): bool
+    {
+        $this->lastError = null;
+
         $phone = preg_replace('/\D+/', '', $to);
         if (strlen($phone) < 9) {
-            return;
+            $this->lastError = 'Enter a valid phone number.';
+
+            return false;
         }
 
         if (strlen($phone) === 9) {
@@ -19,6 +36,25 @@ class SmsService
             $phone = '233'.substr($phone, 1);
         }
 
-        $this->platform->send($ownerPublicId, $phone, $message);
+        $credential = $this->credentials->forOwner($ownerPublicId);
+        if (! $credential->hasValidSms()) {
+            $this->lastError = 'Connect Ladill SMS in Integrations before sending attendee SMS.';
+
+            return false;
+        }
+
+        $apiKey = $credential->smsApiKey();
+        if (! $apiKey) {
+            $this->lastError = 'SMS credentials could not be decrypted. Reconnect SMS in Integrations.';
+
+            return false;
+        }
+
+        $sent = $this->customer->send($apiKey, $phone, $message, (string) $credential->sms_sender_id);
+        if (! $sent) {
+            $this->lastError = $this->customer->lastError() ?: 'The SMS could not be sent.';
+        }
+
+        return $sent;
     }
 }

app/Services/Events/EventCommsService.php

@@ -4,8 +4,8 @@ namespace App\Services\Events;
 
 use App\Models\QrCode;
 use App\Models\QrEventRegistration;
-use App\Services\Billing\BillingClient;
 use App\Services\Billing\SmsService;
+use App\Services\Messaging\MessagingCredentialsService;
 use Illuminate\Support\Collection;
 
 class EventCommsService
@@ -21,11 +21,11 @@ class EventCommsService
     public function __construct(
         private readonly EventEmailService $email,
         private readonly SmsService $sms,
-        private readonly BillingClient $billing,
+        private readonly MessagingCredentialsService $credentials,
         private readonly EventProgrammeService $programmes,
     ) {}
 
-    /** @return array{recipients: int, emails: int, sms: int, estimated_ghs: float, affordable: bool} */
+    /** @return array{recipients: int, emails: int, sms: int, estimated_ghs: float, affordable: bool, integrations_error: ?string} */
     public function preview(QrCode $event, string $mode): array
     {
         $regs = $this->confirmedRegistrations($event);
@@ -34,14 +34,15 @@ class EventCommsService
         $smsSegments = $phones * $this->estimateSmsSegments($event, $mode);
         $estimated = round(($emails * self::EMAIL_PRICE_GHS) + ($smsSegments * self::SMS_PRICE_GHS), 2);
         $ownerRef = (string) $event->user->public_id;
-        $affordable = $estimated <= 0 || $this->billing->canAfford($ownerRef, (int) round($estimated * 100));
+        $integrationsError = $this->integrationsError($event, $mode, $emails, $phones);
 
         return [
             'recipients' => $regs->count(),
             'emails' => $emails,
             'sms' => $phones,
             'estimated_ghs' => $estimated,
-            'affordable' => $affordable,
+            'affordable' => $integrationsError === null,
+            'integrations_error' => $integrationsError,
         ];
     }
 
@@ -51,7 +52,7 @@ class EventCommsService
     public function send(QrCode $event, string $mode): array
     {
         $preview = $this->preview($event, $mode);
-        abort_unless($preview['affordable'], 402, 'Insufficient wallet balance for this send.');
+        abort_if($preview['integrations_error'] !== null, 422, $preview['integrations_error']);
 
         $programme = $this->programmeFor($event);
         $eventName = $event->content()['name'] ?? $event->label;
@@ -86,8 +87,7 @@ class EventCommsService
 
             if ($reg->attendee_phone) {
                 $message = $this->smsBody($reg, $eventName, $mode, $programmeUrl, $joinUrl);
-                if ($message !== '') {
-                    $this->sms->send($ownerRef, $reg->attendee_phone, $message);
+                if ($message !== '' && $this->sms->send($ownerRef, $reg->attendee_phone, $message)) {
                     $texted++;
                     $sent = true;
                 }
@@ -167,4 +167,35 @@ class EventCommsService
 
         return max(1, (int) ceil(strlen($sample) / self::SMS_SEGMENT_CHARS));
     }
+
+    private function integrationsError(QrCode $event, string $mode, int $emails, int $phones): ?string
+    {
+        $ownerRef = (string) $event->user->public_id;
+        $credential = $this->credentials->forOwner($ownerRef);
+        $programmeUrl = $this->programmeFor($event)?->publicUrl();
+        $joinUrl = $this->primaryJoinUrl($event);
+
+        $needsEmail = $emails > 0 && (
+            (in_array($mode, [self::MODE_PROGRAMME, self::MODE_BOTH], true) && $programmeUrl)
+            || ($mode === self::MODE_JOIN && $joinUrl !== '')
+        );
+
+        $needsSms = $phones > 0 && $this->smsBody(
+            new QrEventRegistration(['attendee_name' => 'Guest']),
+            $event->content()['name'] ?? $event->label,
+            $mode,
+            $programmeUrl,
+            $joinUrl,
+        ) !== '';
+
+        if ($needsEmail && ! $credential->hasValidBird()) {
+            return 'Connect Ladill Bird in Integrations before sending attendee email.';
+        }
+
+        if ($needsSms && ! $credential->hasValidSms()) {
+            return 'Connect Ladill SMS in Integrations before sending attendee SMS.';
+        }
+
+        return null;
+    }
 }

app/Services/Events/EventMailer.php

@@ -2,31 +2,36 @@
 
 namespace App\Services\Events;
 
-use App\Services\Billing\BillingClient;
-use Illuminate\Support\Facades\Log;
-use Illuminate\Support\Facades\Mail;
-use Illuminate\Support\Str;
+use App\Services\Messaging\CustomerEmailClient;
+use App\Services\Messaging\MessagingCredentialsService;
 
 /**
- * Sends Ladill Events transactional email via the platform mailer
- * (noreply@ladill.com — same as CRM and other Ladill apps).
+ * Sends Ladill Events transactional email to attendees and speakers via the
+ * customer's Ladill Bird relay when configured in Integrations.
  */
 class EventMailer
 {
-    public const EMAIL_PRICE_MINOR = 1;
-
     private ?string $lastError = null;
 
-    public function __construct(private readonly BillingClient $billing) {}
+    public function __construct(
+        private readonly MessagingCredentialsService $credentials,
+        private readonly CustomerEmailClient $customerEmail,
+    ) {}
 
     public function lastError(): ?string
     {
         return $this->lastError;
     }
 
+    public function isConfiguredForOwner(string $ownerPublicId): bool
+    {
+        return $this->credentials->forOwner($ownerPublicId)->hasValidBird();
+    }
+
+    /** @deprecated Use isConfiguredForOwner() — attendee email requires per-account Bird credentials. */
     public function isConfigured(): bool
     {
-        return filter_var((string) config('mail.from.address'), FILTER_VALIDATE_EMAIL) !== false;
+        return false;
     }
 
     public function send(
@@ -40,54 +45,32 @@ class EventMailer
     ): bool {
         $this->lastError = null;
 
-        if (! $this->isConfigured()) {
-            $this->lastError = 'Outbound email is not configured on this Events instance.';
+        $credential = $this->credentials->forOwner($ownerPublicId);
+        if (! $credential->hasValidBird()) {
+            $this->lastError = 'Connect Ladill Bird in Integrations before sending attendee email.';
 
             return false;
         }
 
-        if (! $this->billing->canAfford($ownerPublicId, self::EMAIL_PRICE_MINOR)) {
-            $this->lastError = 'Insufficient Ladill wallet balance. Add funds in Billing and try again.';
+        $apiKey = $credential->birdApiKey();
+        if (! $apiKey) {
+            $this->lastError = 'Bird credentials could not be decrypted. Reconnect Bird in Integrations.';
 
             return false;
         }
 
-        $reference = 'events_email:'.Str::uuid();
+        $sent = $this->customerEmail->send(
+            $apiKey,
+            (string) $credential->bird_from_email,
+            $credential->bird_from_name,
+            $to,
+            $subject,
+            $html,
+            $text,
+        );
 
-        try {
-            Mail::html($html, function ($message) use ($to, $subject, $text, $replyToEmail, $replyToName): void {
-                $message->to($to)
-                    ->subject($subject)
-                    ->from(
-                        (string) config('mail.from.address'),
-                        (string) config('mail.from.name'),
-                    );
-
-                if ($replyToEmail) {
-                    $message->replyTo($replyToEmail, $replyToName ?: null);
-                }
-
-                if ($text) {
-                    $message->text($text);
-                }
-            });
-        } catch (\Throwable $e) {
-            Log::warning('Events mail send failed', ['error' => $e->getMessage(), 'to' => $to]);
-            $this->lastError = 'The email could not be sent. Please try again.';
-
-            return false;
-        }
-
-        if (! $this->billing->debit(
-            $ownerPublicId,
-            self::EMAIL_PRICE_MINOR,
-            'smtp',
-            'events_email',
-            $reference,
-            null,
-            'Events email to '.$to,
-        )) {
-            $this->lastError = 'Insufficient Ladill wallet balance. Add funds in Billing and try again.';
+        if (! $sent) {
+            $this->lastError = $this->customerEmail->lastError() ?: 'The email could not be sent.';
 
             return false;
         }

app/Services/Events/EventSpeakerInviteService.php

@@ -226,8 +226,8 @@ class EventSpeakerInviteService
             return ['ok' => false, 'error' => 'Could not resolve the event owner account for sending email.'];
         }
 
-        if (! app(EventMailer::class)->isConfigured()) {
-            return ['ok' => false, 'error' => 'Outbound email is not configured on this Events instance.'];
+        if (! app(EventMailer::class)->isConfiguredForOwner($ownerRef)) {
+            return ['ok' => false, 'error' => 'Connect Ladill Bird in Integrations before sending speaker invitations.'];
         }
 
         $token = (string) ($speaker['invite_token'] ?? '');

app/Services/Messaging/CustomerEmailClient.php

@@ -0,0 +1,92 @@
+<?php
+
+namespace App\Services\Messaging;
+
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
+
+class CustomerEmailClient
+{
+    private ?string $lastError = null;
+
+    public function lastError(): ?string
+    {
+        return $this->lastError;
+    }
+
+    private function base(): string
+    {
+        return rtrim((string) config('smtp.customer_relay_url', 'https://ladill.com/api/smtp'), '/');
+    }
+
+    /** @return array{ok: bool, data?: array<string, mixed>, error?: string, status?: int} */
+    public function me(string $apiKey): array
+    {
+        try {
+            $res = Http::withToken($apiKey)->acceptJson()->timeout(15)
+                ->get($this->base().'/me');
+
+            if ($res->status() === 401) {
+                return ['ok' => false, 'error' => 'Invalid Bird API key.', 'status' => 401];
+            }
+
+            if ($res->failed()) {
+                return [
+                    'ok' => false,
+                    'error' => (string) ($res->json('error') ?: 'Could not validate Bird credentials.'),
+                    'status' => $res->status(),
+                ];
+            }
+
+            return ['ok' => true, 'data' => $res->json() ?? [], 'status' => $res->status()];
+        } catch (\Throwable $e) {
+            Log::warning('Customer Bird meta request failed', ['error' => $e->getMessage()]);
+
+            return ['ok' => false, 'error' => 'Could not reach Ladill Bird. Please try again.'];
+        }
+    }
+
+    public function send(
+        string $apiKey,
+        string $from,
+        ?string $fromName,
+        string $to,
+        string $subject,
+        string $html,
+        ?string $text = null,
+    ): bool {
+        $this->lastError = null;
+
+        try {
+            $res = Http::withToken($apiKey)->acceptJson()->timeout(30)
+                ->post($this->base().'/send', array_filter([
+                    'from' => $from,
+                    'from_name' => $fromName,
+                    'to' => [$to],
+                    'subject' => $subject,
+                    'html' => $html,
+                    'text' => $text,
+                ], fn ($value) => $value !== null && $value !== ''));
+
+            if ($res->status() === 402) {
+                $this->lastError = (string) ($res->json('error') ?: 'Insufficient Bird email credits. Top up Bird and try again.');
+
+                return false;
+            }
+
+            if ($res->failed()) {
+                $this->lastError = (string) ($res->json('error') ?: $res->json('message') ?: 'The email could not be sent.');
+                Log::warning('Customer email send failed', ['status' => $res->status()]);
+
+                return false;
+            }
+
+            return (bool) ($res->json('success') ?? true);
+        } catch (\Throwable $e) {
+            $this->lastError = 'Could not reach the email service. Please try again.';
+            Log::warning('Customer email send error', ['error' => $e->getMessage()]);
+
+            return false;
+        }
+    }
+}

app/Services/Messaging/CustomerSmsClient.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace App\Services\Messaging;
+
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
+
+class CustomerSmsClient
+{
+    private ?string $lastError = null;
+
+    public function lastError(): ?string
+    {
+        return $this->lastError;
+    }
+
+    private function base(): string
+    {
+        return rtrim((string) config('sms.customer_relay_url', 'https://ladill.com/api/sms'), '/');
+    }
+
+    /** @return array{ok: bool, data?: array<string, mixed>, error?: string, status?: int} */
+    public function me(string $apiKey): array
+    {
+        return $this->get($apiKey, '/me');
+    }
+
+    /** @return array{ok: bool, data?: array<string, mixed>, error?: string, status?: int} */
+    public function senders(string $apiKey): array
+    {
+        return $this->get($apiKey, '/senders');
+    }
+
+    public function send(string $apiKey, string $to, string $text, string $senderId): bool
+    {
+        $this->lastError = null;
+
+        try {
+            $res = Http::withToken($apiKey)->acceptJson()->timeout(30)
+                ->post($this->base().'/send', [
+                    'to' => $to,
+                    'text' => $text,
+                    'sender_id' => $senderId,
+                ]);
+
+            if ($res->status() === 402) {
+                $this->lastError = (string) ($res->json('error') ?: 'Insufficient SMS credit. Top up your Ladill SMS wallet and try again.');
+
+                return false;
+            }
+
+            if ($res->failed()) {
+                $this->lastError = (string) ($res->json('error') ?: $res->json('message') ?: 'The SMS could not be sent.');
+                Log::warning('Customer SMS send failed', ['status' => $res->status()]);
+
+                return false;
+            }
+
+            return (bool) ($res->json('success') ?? true);
+        } catch (\Throwable $e) {
+            $this->lastError = 'Could not reach the SMS service. Please try again.';
+            Log::warning('Customer SMS send error', ['error' => $e->getMessage()]);
+
+            return false;
+        }
+    }
+
+    /** @return array{ok: bool, data?: array<string, mixed>, error?: string, status?: int} */
+    private function get(string $apiKey, string $path): array
+    {
+        try {
+            $res = Http::withToken($apiKey)->acceptJson()->timeout(15)
+                ->get($this->base().$path);
+
+            if ($res->status() === 401) {
+                return ['ok' => false, 'error' => 'Invalid SMS API key.', 'status' => 401];
+            }
+
+            if ($res->failed()) {
+                return [
+                    'ok' => false,
+                    'error' => (string) ($res->json('error') ?: 'Could not validate SMS credentials.'),
+                    'status' => $res->status(),
+                ];
+            }
+
+            return ['ok' => true, 'data' => $res->json() ?? [], 'status' => $res->status()];
+        } catch (\Throwable $e) {
+            Log::warning('Customer SMS meta request failed', ['path' => $path, 'error' => $e->getMessage()]);
+
+            return ['ok' => false, 'error' => 'Could not reach Ladill SMS. Please try again.'];
+        }
+    }
+}

app/Services/Messaging/MessagingCredentialsService.php

@@ -0,0 +1,163 @@
+<?php
+
+namespace App\Services\Messaging;
+
+use App\Models\MessagingCredential;
+
+class MessagingCredentialsService
+{
+    public function __construct(
+        private CustomerSmsClient $sms,
+        private CustomerEmailClient $email,
+    ) {}
+
+    public function forOwner(string $ownerRef): MessagingCredential
+    {
+        return MessagingCredential::query()->firstOrCreate(
+            ['owner_ref' => $ownerRef],
+        );
+    }
+
+    /**
+     * @return array{ok: bool, error?: string, credential?: MessagingCredential, senders?: list<string>}
+     */
+    public function validateAndSaveSms(string $ownerRef, string $apiKey, string $senderId): array
+    {
+        $apiKey = trim($apiKey);
+        $senderId = trim($senderId);
+
+        if (! str_starts_with($apiKey, 'lsk_sms_live_')) {
+            return ['ok' => false, 'error' => 'SMS API keys must start with lsk_sms_live_.'];
+        }
+
+        if ($senderId === '' || strlen($senderId) > 11) {
+            return ['ok' => false, 'error' => 'Sender ID must be 1–11 characters.'];
+        }
+
+        $me = $this->sms->me($apiKey);
+        if (! ($me['ok'] ?? false)) {
+            $credential = $this->forOwner($ownerRef);
+            $credential->update([
+                'sms_status' => MessagingCredential::STATUS_INVALID,
+                'sms_last_error' => $me['error'] ?? 'Invalid SMS API key.',
+            ]);
+
+            return ['ok' => false, 'error' => $me['error'] ?? 'Invalid SMS API key.', 'credential' => $credential];
+        }
+
+        $senders = $this->sms->senders($apiKey);
+        $approved = collect($senders['data']['data'] ?? [])->pluck('sender_id')->map(fn ($id) => (string) $id)->all();
+        $defaultSender = (string) ($senders['data']['default_sender'] ?? '');
+
+        $allowed = array_values(array_unique(array_filter([...$approved, $defaultSender])));
+        if ($allowed !== [] && ! in_array($senderId, $allowed, true)) {
+            $error = 'Sender ID is not approved for this SMS key. Approved: '.implode(', ', $allowed);
+
+            $credential = $this->forOwner($ownerRef);
+            $credential->update([
+                'sms_status' => MessagingCredential::STATUS_INVALID,
+                'sms_last_error' => $error,
+            ]);
+
+            return ['ok' => false, 'error' => $error, 'credential' => $credential, 'senders' => $allowed];
+        }
+
+        $credential = $this->forOwner($ownerRef);
+        $credential->update([
+            'sms_api_key_encrypted' => MessagingCredential::encryptKey($apiKey),
+            'sms_api_key_prefix' => substr($apiKey, 0, 16),
+            'sms_sender_id' => $senderId,
+            'sms_status' => MessagingCredential::STATUS_VALID,
+            'sms_validated_at' => now(),
+            'sms_last_error' => null,
+        ]);
+
+        return ['ok' => true, 'credential' => $credential->fresh(), 'senders' => $allowed];
+    }
+
+    /**
+     * @return array{ok: bool, error?: string, credential?: MessagingCredential}
+     */
+    public function validateAndSaveBird(string $ownerRef, string $apiKey, string $fromEmail, ?string $fromName): array
+    {
+        $apiKey = trim($apiKey);
+        $fromEmail = strtolower(trim($fromEmail));
+        $fromName = trim((string) $fromName);
+
+        if (! str_starts_with($apiKey, 'lsk_live_') && ! str_starts_with($apiKey, 'lsk_acct_')) {
+            return ['ok' => false, 'error' => 'Bird API keys must start with lsk_live_ or lsk_acct_.'];
+        }
+
+        if (! filter_var($fromEmail, FILTER_VALIDATE_EMAIL)) {
+            return ['ok' => false, 'error' => 'Enter a valid from email address.'];
+        }
+
+        $me = $this->email->me($apiKey);
+        if (! ($me['ok'] ?? false)) {
+            $credential = $this->forOwner($ownerRef);
+            $credential->update([
+                'bird_status' => MessagingCredential::STATUS_INVALID,
+                'bird_last_error' => $me['error'] ?? 'Invalid Bird API key.',
+            ]);
+
+            return ['ok' => false, 'error' => $me['error'] ?? 'Invalid Bird API key.', 'credential' => $credential];
+        }
+
+        $domains = collect($me['data']['verified_domains'] ?? [])->map(fn ($d) => strtolower((string) $d))->all();
+        $fromDomain = strtolower((string) (explode('@', $fromEmail, 2)[1] ?? ''));
+        if ($domains !== [] && ! in_array($fromDomain, $domains, true)) {
+            $error = 'From email must use a verified Bird domain ('.implode(', ', $domains).').';
+            $credential = $this->forOwner($ownerRef);
+            $credential->update([
+                'bird_status' => MessagingCredential::STATUS_INVALID,
+                'bird_last_error' => $error,
+            ]);
+
+            return ['ok' => false, 'error' => $error, 'credential' => $credential];
+        }
+
+        $credential = $this->forOwner($ownerRef);
+        $credential->update([
+            'bird_api_key_encrypted' => MessagingCredential::encryptKey($apiKey),
+            'bird_api_key_prefix' => substr($apiKey, 0, 16),
+            'bird_from_email' => $fromEmail,
+            'bird_from_name' => $fromName !== '' ? $fromName : null,
+            'bird_status' => MessagingCredential::STATUS_VALID,
+            'bird_validated_at' => now(),
+            'bird_last_error' => null,
+        ]);
+
+        return ['ok' => true, 'credential' => $credential->fresh()];
+    }
+
+    public function disconnectSms(string $ownerRef): MessagingCredential
+    {
+        $credential = $this->forOwner($ownerRef);
+        $credential->update([
+            'sms_api_key_encrypted' => null,
+            'sms_api_key_prefix' => null,
+            'sms_sender_id' => null,
+            'sms_status' => null,
+            'sms_validated_at' => null,
+            'sms_last_error' => null,
+        ]);
+
+        return $credential->fresh();
+    }
+
+    public function disconnectBird(string $ownerRef): MessagingCredential
+    {
+        $credential = $this->forOwner($ownerRef);
+        $credential->update([
+            'bird_api_key_encrypted' => null,
+            'bird_api_key_prefix' => null,
+            'bird_from_email' => null,
+            'bird_from_name' => null,
+            'bird_status' => null,
+            'bird_validated_at' => null,
+            'bird_last_error' => null,
+        ]);
+
+        return $credential->fresh();
+    }
+}