Step 2: Data models and migrations (Email, EmailBody, factories)

app/Models/Email.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+class Email extends Model
+{
+    /** @use HasFactory<\Database\Factories\EmailFactory> */
+    use HasFactory;
+
+    protected $table = 'emails';
+
+    protected $fillable = [
+        'unique_id_hash',
+        'recipient_email',
+        'recipient_name',
+        'sender_email',
+        'sender_name',
+        'domain',
+        'subject',
+        'preview',
+        'attachments_json',
+        'attachment_size',
+        'is_read',
+        'received_at',
+    ];
+
+    /**
+     * Get the attributes that should be cast.
+     *
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'attachments_json' => 'array',
+            'attachment_size' => 'integer',
+            'is_read' => 'boolean',
+            'received_at' => 'datetime',
+        ];
+    }
+
+    /**
+     * Scope: filter emails by recipient address.
+     */
+    public function scopeForRecipient(Builder $query, string $email): Builder
+    {
+        return $query->where('recipient_email', $email);
+    }
+
+    /**
+     * Scope: filter emails by domain.
+     */
+    public function scopeForDomain(Builder $query, string $domain): Builder
+    {
+        return $query->where('domain', $domain);
+    }
+
+    /**
+     * Scope: filter unread emails only.
+     */
+    public function scopeUnread(Builder $query): Builder
+    {
+        return $query->where('is_read', false);
+    }
+}

app/Models/EmailBody.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Models;
+
+use MongoDB\Laravel\Eloquent\Model;
+
+class EmailBody extends Model
+{
+    protected $connection = 'mongodb';
+
+    protected $collection = 'recent_email_bodies';
+
+    protected $fillable = [
+        'unique_id_hash',
+        'body_text',
+        'body_html',
+    ];
+}

database/factories/EmailBodyFactory.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Database\Factories;
+
+use App\Models\EmailBody;
+
+class EmailBodyFactory
+{
+    /**
+     * Create a new EmailBody instance with the given attributes.
+     *
+     * @param  array<string, mixed>  $attributes
+     */
+    public static function make(array $attributes = []): EmailBody
+    {
+        return new EmailBody(array_merge([
+            'unique_id_hash' => hash('sha256', fake()->uuid()),
+            'body_text' => fake()->paragraphs(3, true),
+            'body_html' => '<p>'.implode('</p><p>', fake()->paragraphs(3)).'</p>',
+        ], $attributes));
+    }
+
+    /**
+     * Create and persist a new EmailBody instance.
+     *
+     * @param  array<string, mixed>  $attributes
+     */
+    public static function create(array $attributes = []): EmailBody
+    {
+        $body = static::make($attributes);
+        $body->save();
+
+        return $body;
+    }
+}

database/factories/EmailFactory.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace Database\Factories;
+
+use App\Models\Email;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\Email>
+ */
+class EmailFactory extends Factory
+{
+    protected $model = Email::class;
+
+    /**
+     * Define the model's default state.
+     *
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        $domain = fake()->domainName();
+        $bodyText = fake()->paragraphs(3, true);
+
+        return [
+            'unique_id_hash' => hash('sha256', fake()->uuid()),
+            'recipient_email' => fake()->userName().'@'.$domain,
+            'recipient_name' => fake()->name(),
+            'sender_email' => fake()->safeEmail(),
+            'sender_name' => fake()->name(),
+            'domain' => $domain,
+            'subject' => fake()->sentence(6),
+            'preview' => mb_substr($bodyText, 0, 500),
+            'attachments_json' => [],
+            'attachment_size' => 0,
+            'is_read' => false,
+            'received_at' => fake()->dateTimeBetween('-7 days', 'now'),
+        ];
+    }
+
+    /**
+     * Mark the email as read.
+     */
+    public function read(): static
+    {
+        return $this->state(fn (array $attributes) => [
+            'is_read' => true,
+        ]);
+    }
+
+    /**
+     * Add attachments to the email.
+     */
+    public function withAttachments(int $count = 1): static
+    {
+        return $this->state(function (array $attributes) use ($count) {
+            $attachments = [];
+            $totalSize = 0;
+
+            for ($i = 0; $i < $count; $i++) {
+                $size = fake()->numberBetween(1024, 5242880);
+                $totalSize += $size;
+                $attachments[] = [
+                    'filename' => fake()->word().'.'.fake()->fileExtension(),
+                    'mimeType' => fake()->mimeType(),
+                    'size' => $size,
+                    's3_path' => 'mail-attachments/'.now()->format('Y/m/d').'/'.fake()->sha256().'_'.fake()->word().'.pdf',
+                ];
+            }
+
+            return [
+                'attachments_json' => $attachments,
+                'attachment_size' => $totalSize,
+            ];
+        });
+    }
+}

database/migrations/2026_03_05_081922_create_emails_table.php

@@ -0,0 +1,44 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('emails', function (Blueprint $table) {
+            $table->id();
+            $table->char('unique_id_hash', 64);
+            $table->string('recipient_email');
+            $table->string('recipient_name')->default('');
+            $table->string('sender_email');
+            $table->string('sender_name')->default('');
+            $table->string('domain');
+            $table->string('subject', 500)->default('');
+            $table->string('preview', 500)->default('');
+            $table->json('attachments_json')->nullable();
+            $table->unsignedBigInteger('attachment_size')->default(0);
+            $table->boolean('is_read')->default(false);
+            $table->timestamp('received_at')->nullable();
+            $table->timestamps();
+
+            $table->unique('unique_id_hash', 'idx_unique_hash');
+            $table->index('recipient_email', 'idx_recipient');
+            $table->index('domain', 'idx_domain');
+            $table->index('created_at', 'idx_created_at');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('emails');
+    }
+};

routes/api.php

@@ -0,0 +1,3 @@
+<?php
+
+// Webhook routes will be added in Step 3