README

Creating Different Account Types

IMAP/SMTP Account

$account = EmailAccount::create([
    'email' => 'user@example.com',
    'password' => 'secure_password',
    'connection_type' => ConnectionType::IMAP,
    'imap_server' => 'imap.example.com',
    'imap_port' => 993,
    'imap_encryption' => 'ssl',
    'smtp_server' => 'smtp.example.com',
    'smtp_port' => 587,
    'smtp_encryption' => 'tls',
]);

Gmail Account

$gmailAccount = EmailAccount::create([
    'email' => 'user@gmail.com',
    'connection_type' => ConnectionType::GMAIL,
    'access_token' => $accessToken,
    'refresh_token' => $refreshToken,
]);

Outlook Account

$outlookAccount = EmailAccount::create([
    'email' => 'user@outlook.com', 
    'connection_type' => ConnectionType::OUTLOOK,
    'access_token' => $accessToken,
    'refresh_token' => $refreshToken,
]);

Account Operations

// Test connection
if ($account->testConnection()) {
    echo "✅ Connection successful!";
}

// Sync management
$account->enableSync();
$account->disableSync();

// Get statistics
$stats = $account->getStats();
echo "📧 Total: {$stats['total_messages']}";
echo "🔵 Unread: {$stats['unread_messages']}";

Creating and Organizing Folders

// Create main folder
$folder = EmailAccountFolder::create([
    'email_account_id' => $account->id,
    'name' => 'Important',
    'display_name' => 'Important Messages',
    'syncable' => true,
]);

// Create subfolder
$subFolder = EmailAccountFolder::create([
    'email_account_id' => $account->id,
    'parent_id' => $folder->id,
    'name' => 'Urgent',
    'display_name' => 'Urgent Items',
]);

// Browse hierarchy
$rootFolders = $account->folders()->whereNull('parent_id')->get();
foreach ($rootFolders as $folder) {
    echo "📁 {$folder->name}\n";
    foreach ($folder->children as $child) {
        echo "   └─ 📁 {$child->name}\n";
    }
}

Basic Email Composition

$client = $account->createClient();

// Simple email
$message = $client->compose()
    ->to('user@example.com')
    ->subject('Meeting Tomorrow')
    ->text('Don\'t forget our meeting at 2 PM tomorrow.')
    ->send();

// Rich HTML email
$message = $client->compose()
    ->to('user@example.com')
    ->cc('manager@example.com')
    ->bcc('archive@example.com')
    ->subject('Project Update')
    ->html('
        <h2>Project Status Update</h2>
        <p>The project is <strong>on track</strong> for completion.</p>
        <ul>
            <li>✅ Phase 1: Complete</li>
            <li>🔄 Phase 2: In Progress</li>
            <li>⏳ Phase 3: Planned</li>
        </ul>
    ')
    ->attach('/path/to/report.pdf')
    ->send();

Using Templates

$template = PredefinedMailTemplate::find(1);
$message = $client->compose()
    ->to('customer@example.com')
    ->fromTemplate($template)
    ->variables([
        'customer_name' => 'John Doe',
        'order_number' => 'ORD-12345',
        'delivery_date' => '2025-01-15'
    ])
    ->send();

Reading Messages

// Get recent unread messages
$messages = $account->messages()
    ->unread()
    ->orderBy('date', 'desc')
    ->take(10)
    ->get();

foreach ($messages as $message) {
    echo "📧 {$message->subject}\n";
    echo "👤 From: {$message->from_address}\n";
    echo "📅 Date: {$message->date}\n\n";
}

Message Operations

$message = EmailAccountMessage::find($messageId);

// Status operations
$message->markAsRead();
$message->markAsUnread();

// Organization
$message->moveToFolder($importantFolder);
$message->addToFolders([$folder1, $folder2]);

// Lifecycle management
$message->archive();
$message->trash();
$message->restore();
$message->purge(); // Permanent delete

Working with Content

// Get message content
$htmlBody = $message->getHtmlBody();
$textBody = $message->getTextBody();

// Handle attachments
foreach ($message->attachments as $attachment) {
    echo "📎 {$attachment->name} ({$attachment->size} bytes)\n";
    
    // Download attachment
    $content = $attachment->getContent();
    file_put_contents("/downloads/{$attachment->name}", $content);
}

Creating Templates

$template = PredefinedMailTemplate::create([
    'name' => 'Order Confirmation',
    'subject' => 'Order {{order_number}} Confirmed',
    'html_body' => '
        <h1>Order Confirmed! 🎉</h1>
        <p>Hello {{customer_name}},</p>
        <p>Your order <strong>#{{order_number}}</strong> has been confirmed.</p>
        <p>Expected delivery: {{delivery_date}}</p>
    ',
    'text_body' => 'Hello {{customer_name}}, your order #{{order_number}} is confirmed. Delivery: {{delivery_date}}',
    'is_shared' => true,
]);

Using Template Variables

$processedTemplate = $template->process([
    'customer_name' => 'Sarah Johnson',
    'order_number' => 'ORD-789',
    'delivery_date' => 'January 20, 2025'
]);

// Result:
// Subject: "Order ORD-789 Confirmed"
// Body: "Hello Sarah Johnson, your order #ORD-789 is confirmed..."

Scheduling Emails

$scheduledEmail = ScheduledEmail::create([
    'email_account_id' => $account->id,
    'to' => 'customer@example.com',
    'subject' => 'Weekly Newsletter',
    'html_body' => '<h1>This Week in Tech</h1>...',
    'scheduled_at' => Carbon::now()->addWeek(),
    'data' => ['newsletter_id' => 456],
]);

Processing Scheduled Emails

// In your scheduled job (e.g., daily)
$dueEmails = ScheduledEmail::dueForSend()->get();

foreach ($dueEmails as $email) {
    try {
        $email->send();
        echo "✅ Sent: {$email->subject}\n";
    } catch (Exception $e) {
        echo "❌ Failed: {$e->getMessage()}\n";
    }
}

Automatic Link Tracking

// Links in emails are automatically tracked
$message = $client->compose()
    ->to('user@example.com')
    ->subject('Check out our new features!')
    ->html('
        <p>Visit our <a href="https://example.com/features">new features page</a></p>
        <p>Read the <a href="https://example.com/blog/update">latest blog post</a></p>
    ')
    ->send();

Analyzing Click Data

$message = EmailAccountMessage::find($messageId);

// Get all clicks
$clicks = $message->linkClicks;

foreach ($clicks as $click) {
    echo "🔗 URL: {$click->url}\n";
    echo "📅 Clicked: {$click->clicked_at}\n";
    echo "🌍 IP: {$click->ip_address}\n";
    echo "💻 Browser: {$click->user_agent}\n\n";
}

// Statistics
$totalClicks = $message->linkClicks()->count();
$uniqueClicks = $message->linkClicks()->distinct('ip_address')->count();
echo "📊 Total clicks: {$totalClicks} | Unique: {$uniqueClicks}";

Mass Message Management

// Get messages to process
$messages = $account->messages()
    ->where('subject', 'like', '%newsletter%')
    ->get();

// Bulk operations
$account->moveMessagesToFolder($messages, $newsletterFolder);
$account->markMessagesAsRead($messages);
$account->deleteMessages($messages);

Sync Management

use Turahe\MailClient\Services\EmailAccountMessageSyncService;

$syncService = app(EmailAccountMessageSyncService::class);

// Full account sync
$syncService->syncAccount($account);

// Incremental sync (faster)
$lastSync = $account->last_synced_at;
$syncService->syncAccountIncremental($account, $lastSync);

// Sync specific folder only
$syncService->syncFolder($folder);

// Connection management
$account->testConnection(): bool
$account->createClient(): Client

// Sync control
$account->enableSync(): void
$account->disableSync(): void
$account->isSyncDisabled(): bool

// Statistics
$account->getStats(): array
$account->getUnreadCount(): int

// Token management (OAuth accounts)
$account->refreshAccessToken(): void
$account->isTokenExpired(): bool

// Status management
$message->markAsRead(): void
$message->markAsUnread(): void
$message->isRead(): bool

// Organization
$message->moveToFolder(EmailAccountFolder $folder): void
$message->addToFolders(array $folders): void
$message->removeFromFolder(EmailAccountFolder $folder): void

// Lifecycle
$message->archive(): void
$message->trash(): void
$message->restore(): void
$message->purge(): void

// Content access
$message->getHtmlBody(): string
$message->getTextBody(): string
$message->hasAttachments(): bool

// Template processing
$template->process(array $variables): array
$template->getProcessedSubject(array $variables): string
$template->getProcessedBody(array $variables): string

// Sharing
$template->makeShared(): void
$template->makePrivate(): void
$template->isShared(): bool

Problem: Connection timeout errors

// Solution: Increase timeout settings
'imap_timeout' => 60,  // seconds
'smtp_timeout' => 30,  // seconds

Problem: SSL certificate errors

// Solution: Disable SSL verification (development only)
'imap_options' => [
    'ssl' => [
        'verify_peer' => false,
        'verify_peer_name' => false,
    ]
]

Problem: Memory exhaustion with large attachments

// Solution 1: Increase memory limit
ini_set('memory_limit', '512M');

// Solution 2: Use streaming
$attachment->streamToFile('/path/to/destination');

// Solution 3: Process in chunks
$account->messages()->chunk(50, function ($messages) {
    // Process 50 messages at a time
});

Problem: Expired access tokens

// Solution: Automatic token refresh
if ($account->isTokenExpired()) {
    $account->refreshAccessToken();
}

// Or handle in exception
try {
    $client->getMessages();
} catch (UnauthorizedException $e) {
    $account->refreshAccessToken();
    $client->getMessages(); // Retry
}