Temp Mail

How It Works

The Temp Mail system uses catch-all email domains. Here's the flow:

1. Admin Setup: The administrator configures one or more domains (e.g., tmpmail.yoursite.com) with catch-all MX records pointing to a mail server, then enters the IMAP credentials in the admin panel.
2. User Generates Address: A user clicks "Generate New" and receives a random address like x8k2m9p4@tmpmail.yoursite.com.
3. Emails Arrive: When someone sends an email to that address, the catch-all mail server receives it. MailTrixy's background sync job polls the IMAP inbox every 2 minutes.
4. Messages Displayed: The sync job matches the incoming email's recipient to the user's temp address and stores it. The message appears in the user's Temp Mail inbox within 2 minutes.
5. Auto-Expiry: After the configured lifetime (e.g., 1 hour, 24 hours, 7 days), the address is automatically deactivated and its messages are deleted by a cleanup job running every 15 minutes.

User Guide

Generating a Temp Email Address

1. Navigate to Temp Mail from the sidebar menu.
2. Click the "Generate New" button.
3. Optionally select a specific domain (if multiple are available) and add a label (e.g., "Newsletter test").
4. Click "Generate". Your new disposable address appears immediately.

Using Your Temp Address

• Copy: Click the "Copy Address" button to copy the full email address to your clipboard.
• Use it anywhere: Paste it into sign-up forms, newsletter subscriptions, online services, or anywhere you need a temporary email.
• Wait for emails: Messages sent to your temp address appear in the inbox within 2 minutes (the sync interval).
• Refresh: Click the refresh button to manually check for new messages.

Reading Messages

• Click on any temp address in the address bar to view its inbox.
• Click on a message in the list to read it in the viewer panel.
• Messages display the full HTML content, sender information, date, and any attachments.
• Attachments can be viewed and downloaded from the message viewer.

Managing Addresses

• Delete: Click the "Delete" button to immediately remove an address and all its messages.
• History: Click "History" to view previously used (expired) addresses.
• Expiry Countdown: Each address shows a colored indicator and remaining time:
  • Green = More than 1 hour remaining
  • Yellow = Less than 1 hour remaining
  • Red = Expired

Note: Once an address expires, it is deactivated and will no longer receive emails. Expired addresses and their messages are permanently deleted during the next cleanup cycle.

Plan Limits

Temp Mail is controlled by three plan-level settings that administrators configure in Admin > Plans > Edit Plan:

If a user reaches their address limit, they must wait for an existing address to expire (or delete one manually) before generating a new one.

API Endpoints

Temp Mail is accessible via the REST API for programmatic access. All endpoints require auth:sanctum with the temp-mail ability scope.

Example: Create Address

curl -X POST https://yoursite.com/api/v1/temp-mail/addresses \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "Test signup", "domain_id": 1}'

Response

{
  "data": {
    "uuid": "a1b2c3d4-...",
    "address": "x8k2m9p4@tmpmail.yoursite.com",
    "label": "Test signup",
    "expires_at": "2026-04-02T12:00:00Z"
  }
}

Admin Setup Guide

Prerequisites

• A domain you control (e.g., tmpmail.yoursite.com)
• DNS access to set MX records for that domain
• A mail server with catch-all enabled (any email to *@tmpmail.yoursite.com gets caught)
• IMAP credentials for the catch-all mailbox

Step 1: Configure DNS

Add an MX record for your temp mail domain pointing to your mail server:

tmpmail.yoursite.com.  IN  MX  10  mail.yoursite.com.

Then configure the mail server to accept all emails for *@tmpmail.yoursite.com (catch-all) and deliver them to a single IMAP mailbox.

Step 2: Add Domain in Admin Panel

1. Navigate to Admin > Temp Mail.
2. Click "Add Domain".
3. Fill in the domain details:
   • Domain: tmpmail.yoursite.com
   • Display Name: "Temp Mail"
   • IMAP Host: Your mail server hostname
   • IMAP Port: 993 (SSL) or 143 (TLS)
   • IMAP Username/Password: Catch-all mailbox credentials
   • Encryption: SSL or TLS
   • Default Lifetime: 24 hours (fallback if plan has no limit)
4. Click "Test Connection" to verify IMAP connectivity.
5. Toggle the domain to "Active".

Step 3: Configure Plan Limits

1. Navigate to Admin > Plans and edit each plan.
2. In the Feature Access tab, enable the "Temp Mail" toggle.
3. In the Resource Limits tab, set:
   • Temp Mail Addresses: Number of active addresses per workspace (e.g., 5)
   • Temp Mail Lifetime: Maximum lifetime in hours (e.g., 24)
4. Save the plan.

Step 4: Global Settings (Optional)

In Admin > Temp Mail > Settings tab, configure:

• Temp Mail Enabled: Master kill switch for the entire feature.
• Default Lifetime: Fallback lifetime if the plan has no specific limit.
• Auto-Cleanup After: Number of days after expiry to permanently delete addresses (default: 30).
• Blocked Keywords: Comma-separated list of local-part keywords to block (e.g., "admin, postmaster, abuse").

Background Commands

Temp Mail relies on two scheduled commands that run automatically via the Laravel scheduler:

These commands are automatically included in the scheduler. Ensure your server has the cron job configured:

* * * * * cd /path/to/mailtrixy && php artisan schedule:run >> /dev/null 2>&1

Manual Commands

# Force sync all domains immediately
php artisan mailtrixy:sync-temp-mail --force

# Sync a specific domain
php artisan mailtrixy:sync-temp-mail --domain=1

# Preview cleanup without deleting
php artisan mailtrixy:cleanup-temp-mail --dry-run

# Run cleanup
php artisan mailtrixy:cleanup-temp-mail

Security Considerations

• IMAP Credentials: All IMAP credentials are encrypted at rest using Laravel's encryption (AES-256-CBC). They are never exposed in the admin UI after saving.
• Workspace Isolation: Each temp address is scoped to a workspace. Users in one workspace cannot see or access addresses from another workspace.
• Message Deduplication: The sync service checks the Message-ID header to prevent duplicate messages from being stored.
• Blocked Patterns: Admins can block specific local-part keywords (like "admin", "postmaster") to prevent abuse.
• Auto-Cleanup: Expired addresses and their messages are automatically deleted, ensuring no stale data accumulates.
• Plan Enforcement: Address generation enforces plan limits atomically to prevent race conditions.

Troubleshooting

Messages Not Appearing

• Verify the domain's IMAP connection by clicking "Test Connection" in admin.
• Check if the domain status is "Active" (not "Error" or "Inactive").
• Run php artisan mailtrixy:sync-temp-mail --force manually.
• Check storage/logs/laravel.log for sync errors.
• Verify the catch-all is configured correctly on the mail server.

Address Generation Fails

• Check if the user's plan has temp_mail enabled.
• Check if the user has reached their temp_mail_addresses limit.
• Verify at least one domain is active in Admin > Temp Mail.
• Check the global Temp Mail Enabled setting is ON.

Domain Shows "Error" Status

• The IMAP connection failed. Check the error message shown on the domain card.
• Common causes: wrong credentials, firewall blocking IMAP port, SSL certificate issues.
• Fix the credentials and click "Test Connection" to verify, then toggle back to "Active".