Meo Mai Moi

Appearance

Email Configuration Guide ​

This guide explains how to set up and use email configurations for Meo Mai Moi.

Quick Setup ​

bash
# Set up configurations with your credentials
php artisan email:setup \
  --smtp-username=your-email@gmail.com \
  --smtp-password=your-app-password \
  --mailgun-api-key=key-your-actual-api-key \
  --activate=smtp

# Or set up without credentials (update later in admin panel)
php artisan email:setup

Using Database Seeder ​

bash
php artisan db:seed --class=EmailConfigurationSeeder

Configuration Details ​

SMTP and Mailgun configurations can be pre-configured with:

  • Domain: your sending domain
  • From Email: your sender address
  • From Name: Meo Mai Moi
  • Test Email: a monitored test recipient

SMTP Configuration ​

  • Host: smtp.gmail.com
  • Port: 587
  • Encryption: tls
  • Username: Your Gmail address
  • Password: Your Gmail app password

Mailgun Configuration ​

  • Domain: your Mailgun sending domain
  • Endpoint: api.mailgun.net
  • API Key: Your Mailgun API key

Admin Panel Usage ​

Accessing Email Configurations ​

  1. Go to /admin/email-configurations
  2. View, edit, or create new configurations
  3. Test configurations using the "Send Test Email" button

Testing Email Configurations ​

  1. Both SMTP and Mailgun now require a Test Email Address
  2. Test emails are sent to the configured test address by default
  3. All test emails now appear in /admin/email-logs

Viewing Email Logs ​

  1. Go to /admin/email-logs
  2. View all sent emails including test emails
  3. Check delivery status and error messages
  4. Retry failed emails if needed

Email Status Lifecycle ​

Email logs track the full delivery lifecycle with Mailgun webhook integration:

  • pending: Initial state when queued
  • accepted: Mailgun has accepted the email for delivery (replaces legacy "sent" status)
  • delivered: Email successfully delivered to recipient's mail server
  • opened: Recipient opened the email (tracking pixel)
  • clicked: Recipient clicked a link in the email
  • unsubscribed: Recipient unsubscribed via Mailgun
  • complained: Recipient marked email as spam
  • failed: Permanent delivery failure

Additional tracking fields:

  • opened_at, clicked_at, unsubscribed_at, complained_at, permanent_fail_at

Idempotency Protection ​

Email verification notifications use idempotency to prevent duplicate sends:

  • Default window: 30 seconds (configurable via EMAIL_VERIFICATION_IDEMPOTENCY_SECONDS)
  • Applied at: notification channel, registration response, resend endpoint
  • See config/notifications.php for configuration

Mailgun Webhook Setup ​

Configure webhook in Mailgun dashboard to track delivery events:

POST /webhooks/mailgun

Required events: delivered, opened, clicked, unsubscribed, complained, permanent_fail

Webhook requests are rejected unless the Mailgun signing key is configured and the request contains a valid, fresh signature. Invalid signature attempts are logged with a sanitized failure reason (missing_signing_key, missing_signature_fields, expired_signature_timestamp, or signature_mismatch) to make delivery/debugging issues visible without logging the raw signature payload.

New Features ​

Test Email Address for Mailgun ​

  • Mailgun configurations now have a "Test Email Address" field
  • Consistent experience between SMTP and Mailgun
  • Required for sending test emails

Test Emails in Email Logs ​

  • All test emails are now logged in the database
  • Visible in the admin panel at /admin/email-logs
  • Proper status tracking (pending → sent/failed)
  • Error messages for failed test emails

Troubleshooting ​

Test Email Not Received ​

  1. Check /admin/email-logs for delivery status
  2. Verify the test email address is correct
  3. Check spam folder
  4. Ensure email configuration is valid and active

Database Connection Issues ​

If you see database connection errors:

  1. Ensure your database is running
  2. Check your .env file database settings
  3. Run php artisan migrate if needed

Gmail SMTP Issues ​

  1. Use an App Password, not your regular password
  2. Enable 2-factor authentication first
  3. Generate App Password in Google Account settings

Mailgun Issues ​

  1. Verify your domain is properly configured in Mailgun
  2. Check your API key is correct and active
  3. Ensure your domain is verified in Mailgun dashboard

Commands Reference ​

bash
# Setup email configurations
php artisan email:setup

# Setup with credentials
php artisan email:setup --smtp-username=email@gmail.com --smtp-password=password

# Setup and activate SMTP
php artisan email:setup --activate=smtp

# Setup and activate Mailgun
php artisan email:setup --activate=mailgun

# Run email configuration seeder
php artisan db:seed --class=EmailConfigurationSeeder

# Check migration status
php artisan migrate:status

# Run migrations
php artisan migrate

Security Notes ​

  • Never commit real credentials to version control
  • Use environment variables for sensitive data
  • Regularly rotate API keys and passwords
  • Use App Passwords for Gmail SMTP