[ADVAPP-2304]: Introduce a health indicator on email and other email addresses on the holistic profile

app-modules/prospect/database/migrations/2026_01_21_154229_convert_prospect_email_addresses_address_to_citext.php

@@ -0,0 +1,50 @@
+<?php
+
+/*
+<COPYRIGHT>
+
+    Copyright © 2016-2026, Canyon GBS LLC. All rights reserved.
+
+    Advising App™ is licensed under the Elastic License 2.0. For more details,
+    see https://github.com/canyongbs/advisingapp/blob/main/LICENSE.
+
+    Notice:
+
+    - You may not provide the software to third parties as a hosted or managed
+      service, where the service provides users with access to any substantial set of
+      the features or functionality of the software.
+    - You may not move, change, disable, or circumvent the license key functionality
+      in the software, and you may not remove or obscure any functionality in the
+      software that is protected by the license key.
+    - You may not alter, remove, or obscure any licensing, copyright, or other notices
+      of the licensor in the software. Any use of the licensor’s trademarks is subject
+      to applicable law.
+    - Canyon GBS LLC respects the intellectual property rights of others and expects the
+      same in return. Canyon GBS™ and Advising App™ are registered trademarks of
+      Canyon GBS LLC, and we are committed to enforcing and protecting our trademarks
+      vigorously.
+    - The software solution, including services, infrastructure, and code, is offered as a
+      Software as a Service (SaaS) by Canyon GBS LLC.
+    - Use of this software implies agreement to the license terms and conditions as stated
+      in the Elastic License 2.0.
+
+    For more information or inquiries please visit our website at
+    https://www.canyongbs.com or contact us via email at legal@canyongbs.com.
+
+</COPYRIGHT>
+*/
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+
+return new class () extends Migration {
+    public function up(): void
+    {
+        DB::statement('ALTER TABLE prospect_email_addresses ALTER COLUMN address TYPE citext');
+    }
+
+    public function down(): void
+    {
+        DB::statement('ALTER TABLE prospect_email_addresses ALTER COLUMN address TYPE VARCHAR(255)');
+    }
+};

app-modules/prospect/src/Models/Prospect.php

@@ -60,6 +60,7 @@
 use AdvisingApp\Prospect\Database\Factories\ProspectFactory;
 use AdvisingApp\Prospect\Filament\Resources\Prospects\ProspectResource;
 use AdvisingApp\Prospect\Observers\ProspectObserver;
+use AdvisingApp\StudentDataModel\Enums\EmailHealthStatus;
 use AdvisingApp\StudentDataModel\Models\Contracts\Educatable;
 use AdvisingApp\StudentDataModel\Models\Student;
 use AdvisingApp\Task\Models\Task;
@@ -445,7 +446,13 @@ public function educatablePipelineStages(): MorphToMany
 
     public function canReceiveEmail(): bool
     {
-        return filled($this->primaryEmailAddress?->address) && (! $this->primaryEmailAddress->bounced()->exists());
+        if (blank($this->primaryEmailAddress?->address)) {
+            return false;
+        }
+
+        $healthStatus = $this->primaryEmailAddress->getHealthStatus();
+
+        return $healthStatus === EmailHealthStatus::Healthy;
     }
 
     public function canReceiveSms(): bool

app-modules/prospect/src/Models/ProspectEmailAddress.php

@@ -38,7 +38,10 @@
 
 use AdvisingApp\Audit\Models\Concerns\Auditable as AuditableTrait;
 use AdvisingApp\Prospect\Observers\ProspectEmailAddressObserver;
+use AdvisingApp\StudentDataModel\Enums\EmailAddressOptInOptOutStatus;
+use AdvisingApp\StudentDataModel\Enums\EmailHealthStatus;
 use AdvisingApp\StudentDataModel\Models\BouncedEmailAddress;
+use AdvisingApp\StudentDataModel\Models\EmailAddressOptInOptOut;
 use App\Models\BaseModel;
 use Illuminate\Database\Eloquent\Attributes\ObservedBy;
 use Illuminate\Database\Eloquent\Concerns\HasVersion4Uuids as HasUuids;
@@ -77,4 +80,28 @@ public function bounced(): HasOne
     {
         return $this->hasOne(BouncedEmailAddress::class, 'address', 'address');
     }
+
+    /**
+     * @return HasOne<EmailAddressOptInOptOut, $this>
+     */
+    public function optedOut(): HasOne
+    {
+        return $this->hasOne(EmailAddressOptInOptOut::class, 'address', 'address');
+    }
+
+    public function getHealthStatus(): EmailHealthStatus
+    {
+        // Check in order: Bounced > OptedOut > Healthy
+        if ($this->bounced()->exists()) {
+            return EmailHealthStatus::Bounced;
+        }
+
+        $optOutRecord = $this->optedOut()->first();
+
+        if ($optOutRecord && $optOutRecord->status === EmailAddressOptInOptOutStatus::OptedOut) {
+            return EmailHealthStatus::OptedOut;
+        }
+
+        return EmailHealthStatus::Healthy;
+    }
 }

app-modules/prospect/tests/Tenant/Unit/ProspectCanReceiveEmailTest.php

@@ -0,0 +1,144 @@
+<?php
+
+/*
+<COPYRIGHT>
+
+    Copyright © 2016-2026, Canyon GBS LLC. All rights reserved.
+
+    Advising App™ is licensed under the Elastic License 2.0. For more details,
+    see https://github.com/canyongbs/advisingapp/blob/main/LICENSE.
+
+    Notice:
+
+    - You may not provide the software to third parties as a hosted or managed
+      service, where the service provides users with access to any substantial set of
+      the features or functionality of the software.
+    - You may not move, change, disable, or circumvent the license key functionality
+      in the software, and you may not remove or obscure any functionality in the
+      software that is protected by the license key.
+    - You may not alter, remove, or obscure any licensing, copyright, or other notices
+      of the licensor in the software. Any use of the licensor’s trademarks is subject
+      to applicable law.
+    - Canyon GBS LLC respects the intellectual property rights of others and expects the
+      same in return. Canyon GBS™ and Advising App™ are registered trademarks of
+      Canyon GBS LLC, and we are committed to enforcing and protecting our trademarks
+      vigorously.
+    - The software solution, including services, infrastructure, and code, is offered as a
+      Software as a Service (SaaS) by Canyon GBS LLC.
+    - Use of this software implies agreement to the license terms and conditions as stated
+      in the Elastic License 2.0.
+
+    For more information or inquiries please visit our website at
+    https://www.canyongbs.com or contact us via email at legal@canyongbs.com.
+
+</COPYRIGHT>
+*/
+
+use AdvisingApp\Prospect\Models\Prospect;
+use AdvisingApp\Prospect\Models\ProspectEmailAddress;
+use AdvisingApp\StudentDataModel\Models\BouncedEmailAddress;
+use AdvisingApp\StudentDataModel\Models\EmailAddressOptInOptOut;
+
+use function PHPUnit\Framework\assertFalse;
+use function PHPUnit\Framework\assertTrue;
+
+it('returns true when prospect has a healthy primary email address', function () {
+    $prospect = Prospect::factory()->create();
+
+    $emailAddress = ProspectEmailAddress::factory()
+        ->for($prospect)
+        ->create(['address' => 'healthy@example.com']);
+
+    $prospect->primaryEmailAddress()->associate($emailAddress);
+    $prospect->save();
+    $prospect->refresh();
+
+    assertTrue($prospect->canReceiveEmail());
+});
+
+it('returns false when prospect has no primary email address', function () {
+    $prospect = Prospect::factory()->create();
+
+    // Remove the primary email that was auto-created by the factory
+    $prospect->primary_email_id = null;
+    $prospect->save();
+    $prospect->refresh();
+
+    assertFalse($prospect->canReceiveEmail());
+});
+
+it('returns false when prospect primary email address is bounced', function () {
+    $prospect = Prospect::factory()->create();
+
+    $emailAddress = ProspectEmailAddress::factory()
+        ->for($prospect)
+        ->create(['address' => 'bounced@example.com']);
+
+    BouncedEmailAddress::factory()->create([
+        'address' => $emailAddress->address,
+    ]);
+
+    $prospect->primaryEmailAddress()->associate($emailAddress);
+    $prospect->save();
+    $prospect->refresh();
+
+    assertFalse($prospect->canReceiveEmail());
+});
+
+it('returns false when prospect primary email address is opted out', function () {
+    $prospect = Prospect::factory()->create();
+
+    $emailAddress = ProspectEmailAddress::factory()
+        ->for($prospect)
+        ->create(['address' => 'optedout@example.com']);
+
+    EmailAddressOptInOptOut::factory()
+        ->optedOut()
+        ->create(['address' => $emailAddress->address]);
+
+    $prospect->primaryEmailAddress()->associate($emailAddress);
+    $prospect->save();
+    $prospect->refresh();
+
+    assertFalse($prospect->canReceiveEmail());
+});
+
+it('returns true when prospect primary email address is opted in', function () {
+    $prospect = Prospect::factory()->create();
+
+    $emailAddress = ProspectEmailAddress::factory()
+        ->for($prospect)
+        ->create(['address' => 'optedin@example.com']);
+
+    EmailAddressOptInOptOut::factory()
+        ->optedIn()
+        ->create(['address' => $emailAddress->address]);
+
+    $prospect->primaryEmailAddress()->associate($emailAddress);
+    $prospect->save();
+    $prospect->refresh();
+
+    assertTrue($prospect->canReceiveEmail());
+});
+
+it('returns false when prospect primary email is both bounced and opted out', function () {
+    $prospect = Prospect::factory()->create();
+
+    $emailAddress = ProspectEmailAddress::factory()
+        ->for($prospect)
+        ->create(['address' => 'both@example.com']);
+
+    BouncedEmailAddress::factory()->create([
+        'address' => $emailAddress->address,
+    ]);
+
+    EmailAddressOptInOptOut::factory()
+        ->optedOut()
+        ->create(['address' => $emailAddress->address]);
+
+    $prospect->primaryEmailAddress()->associate($emailAddress);
+    $prospect->save();
+    $prospect->refresh();
+
+    assertFalse($prospect->canReceiveEmail());
+});

app-modules/prospect/tests/Tenant/Unit/ProspectEmailAddressHealthStatusTest.php

@@ -0,0 +1,129 @@
+<?php
+
+/*
+<COPYRIGHT>
+
+    Copyright © 2016-2026, Canyon GBS LLC. All rights reserved.
+
+    Advising App™ is licensed under the Elastic License 2.0. For more details,
+    see https://github.com/canyongbs/advisingapp/blob/main/LICENSE.
+
+    Notice:
+
+    - You may not provide the software to third parties as a hosted or managed
+      service, where the service provides users with access to any substantial set of
+      the features or functionality of the software.
+    - You may not move, change, disable, or circumvent the license key functionality
+      in the software, and you may not remove or obscure any functionality in the
+      software that is protected by the license key.
+    - You may not alter, remove, or obscure any licensing, copyright, or other notices
+      of the licensor in the software. Any use of the licensor’s trademarks is subject
+      to applicable law.
+    - Canyon GBS LLC respects the intellectual property rights of others and expects the
+      same in return. Canyon GBS™ and Advising App™ are registered trademarks of
+      Canyon GBS LLC, and we are committed to enforcing and protecting our trademarks
+      vigorously.
+    - The software solution, including services, infrastructure, and code, is offered as a
+      Software as a Service (SaaS) by Canyon GBS LLC.
+    - Use of this software implies agreement to the license terms and conditions as stated
+      in the Elastic License 2.0.
+
+    For more information or inquiries please visit our website at
+    https://www.canyongbs.com or contact us via email at legal@canyongbs.com.
+
+</COPYRIGHT>
+*/
+
+use AdvisingApp\Prospect\Models\Prospect;
+use AdvisingApp\Prospect\Models\ProspectEmailAddress;
+use AdvisingApp\StudentDataModel\Enums\EmailHealthStatus;
+use AdvisingApp\StudentDataModel\Models\BouncedEmailAddress;
+use AdvisingApp\StudentDataModel\Models\EmailAddressOptInOptOut;
+
+use function PHPUnit\Framework\assertEquals;
+
+it('returns healthy status for email address with no issues', function () {
+    $prospect = Prospect::factory()->create();
+
+    $emailAddress = ProspectEmailAddress::factory()
+        ->for($prospect)
+        ->create(['address' => 'healthy@example.com']);
+
+    assertEquals(EmailHealthStatus::Healthy, $emailAddress->getHealthStatus());
+});
+
+it('returns bounced status when email address has bounced', function () {
+    $prospect = Prospect::factory()->create();
+
+    $emailAddress = ProspectEmailAddress::factory()
+        ->for($prospect)
+        ->create(['address' => 'bounced@example.com']);
+
+    BouncedEmailAddress::factory()->create([
+        'address' => $emailAddress->address,
+    ]);
+
+    assertEquals(EmailHealthStatus::Bounced, $emailAddress->getHealthStatus());
+});
+
+it('returns opted out status when email address is opted out', function () {
+    $prospect = Prospect::factory()->create();
+
+    $emailAddress = ProspectEmailAddress::factory()
+        ->for($prospect)
+        ->create(['address' => 'optedout@example.com']);
+
+    EmailAddressOptInOptOut::factory()
+        ->optedOut()
+        ->create(['address' => $emailAddress->address]);
+
+    assertEquals(EmailHealthStatus::OptedOut, $emailAddress->getHealthStatus());
+});
+
+it('returns healthy status when email address is opted in', function () {
+    $prospect = Prospect::factory()->create();
+
+    $emailAddress = ProspectEmailAddress::factory()
+        ->for($prospect)
+        ->create(['address' => 'optedin@example.com']);
+
+    EmailAddressOptInOptOut::factory()
+        ->optedIn()
+        ->create(['address' => $emailAddress->address]);
+
+    assertEquals(EmailHealthStatus::Healthy, $emailAddress->getHealthStatus());
+});
+
+it('prioritizes bounced status over opted out status', function () {
+    $prospect = Prospect::factory()->create();
+
+    $emailAddress = ProspectEmailAddress::factory()
+        ->for($prospect)
+        ->create(['address' => 'both@example.com']);
+
+    // Create both bounced and opted out records
+    BouncedEmailAddress::factory()->create([
+        'address' => $emailAddress->address,
+    ]);
+
+    EmailAddressOptInOptOut::factory()
+        ->optedOut()
+        ->create(['address' => $emailAddress->address]);
+
+    // Should return Bounced because it has higher priority
+    assertEquals(EmailHealthStatus::Bounced, $emailAddress->getHealthStatus());
+});
+
+it('is case insensitive when checking health status', function () {
+    $prospect = Prospect::factory()->create();
+
+    $emailAddress = ProspectEmailAddress::factory()
+        ->for($prospect)
+        ->create(['address' => 'Test@Example.com']);
+
+    BouncedEmailAddress::factory()->create([
+        'address' => 'test@example.com',
+    ]);
+
+    assertEquals(EmailHealthStatus::Bounced, $emailAddress->getHealthStatus());
+});