Email

Introduction

The Email connector reads inbound mail from an IMAP mailbox and sends replies via SMTP. It uses its own credentials, separate from your Laravel app's mail configuration, so it doesn't interfere with anything else. It's powered by directorytree/imapengine-laravel.

Setup

Run the connector wizard:

php artisan laraclaw:setup-connector email

It asks for IMAP and SMTP credentials and writes:

LARACLAW_EMAIL_ENABLED=true

LARACLAW_IMAP_HOST=imap.gmail.com
LARACLAW_IMAP_PORT=993
LARACLAW_IMAP_ENCRYPTION=ssl
LARACLAW_IMAP_USERNAME=you@example.com
LARACLAW_IMAP_PASSWORD=...

LARACLAW_SMTP_HOST=smtp.gmail.com
LARACLAW_SMTP_PORT=587
LARACLAW_SMTP_ENCRYPTION=tls
LARACLAW_SMTP_USERNAME=you@example.com
LARACLAW_SMTP_PASSWORD=...
LARACLAW_SMTP_FROM_ADDRESS=you@example.com
LARACLAW_SMTP_FROM_NAME=Laraclaw

Trusted Senders

The wizard also asks which email addresses the bot should reply to, defaulting to the owner's email. Each address becomes a laraclaw_accounts row mapping that email to the owner. Mail from any other sender is dropped during validation.

To add another trusted sender later, re-run the wizard, or insert directly:

Account::create([
    'user_id' => $ownerUserId,
    'connector' => 'email',
    'account' => 'other@example.com',
]);

DKIM and SPF

The Email connector has no webhook to verify — it polls IMAP. The trust boundary is the sender's From: header, and the only protection against forging it is DKIM and SPF. By default, every incoming message must pass at least one of them, even if the From: address is in laraclaw_accounts. Failures are logged and the message is dropped.

You may disable this in .env:

LARACLAW_EMAIL_VERIFY_SENDER_DKIM_AND_SPF=false

!WARNING Disabling DKIM and SPF verification makes it possible for someone to spoof a trusted sender. Only do this if you control the inbound mail server and trust its filtering. Laraclaw does not check DMARC alignment, so a message that passes DKIM/SPF for a different domain than the From: header will still be accepted.

Threading

Conversations are keyed per sender address. Every message from the same trusted address lands in the same Thread, regardless of subject line. Replies set the In-Reply-To and References headers so most email clients render the exchange as a single conversation, and the reply subject is prefixed with Re: if it isn't already.

Running the IMAP Listener

Inbound mail is delivered by imap:watch, a long-running command from imapengine that polls the inbox and dispatches events:

php artisan imap:watch default --with=headers,body

In production, run it under a process supervisor so it restarts on failure.

Attachments

Inbound attachments are saved under inbound/{message_uuid}/ on the attachments disk. Outbound attachments produced by tools are attached to the SMTP message before sending.