Receive email over IMAP

Turn inbound email into support conversations on a self-hosted Quackback instance by polling a mailbox over IMAP, with no public webhook endpoint needed.

Turn inbound email into support conversations on a self-hosted instance by having Quackback poll a mailbox over IMAP, with no public webhook endpoint needed. Customer emails and replies land as conversation messages, the same as with a provider webhook.

Note: This article covers the self-hosted IMAP transport. For the email channel itself (threading, agent replies, routing), see Set up the email channel.

IMAP or a provider webhook?

Quackback supports two ways to receive inbound email:

	Provider webhook	IMAP polling
Setup	Configure a provider (for example Resend inbound) and point its webhook at your instance	Point Quackback at any mailbox you already control
Requires	A public HTTPS endpoint reachable from the provider	Outbound access to your IMAP host only
Latency	Near-instant	Up to about 60 seconds (poll interval)

If your instance isn't publicly reachable, or you already have a support mailbox and don't want to route it through a third-party inbound-email provider, use IMAP.

Configure the poller

Set these variables and restart:

EMAIL_INBOUND_PROVIDER=imap
IMAP_HOST=imap.example.com
IMAP_PORT=993
[email protected]
IMAP_PASSWORD=your-mailbox-password
IMAP_TLS=true
IMAP_MAILBOX=INBOX

Variable	Default	Notes
`EMAIL_INBOUND_PROVIDER`	unset	Must be `imap` to enable the poller
`IMAP_HOST`	required	No default
`IMAP_PORT`	`993` (TLS) or `143` (plaintext)
`IMAP_USER`	required	No default
`IMAP_PASSWORD`	required	No default
`IMAP_TLS`	`true`	Set to `false` for a plaintext connection
`IMAP_MAILBOX`	`INBOX`	Mailbox to poll

Warning: EMAIL_INBOUND_PROVIDER, IMAP_HOST, IMAP_USER, and IMAP_PASSWORD are all required together. Leave any one unset and the poller never connects. There's no error; it just stays off.

Sending is configured separately: your team's replies still go out through your one outbound provider (SMTP, Amazon SES, or Resend). See Configure email delivery.

How it works

A background worker polls the mailbox for unseen messages roughly every 60 seconds, parses each one, and creates a conversation or threads it into an existing one. Messages that are ingested, or deliberately dropped as spam or unroutable, are marked as seen. A message that fails because of a temporary error is left unseen so the next poll retries it.

Tip: The poller only runs where QUACKBACK_ROLE is worker or all. If you've split web and worker replicas, make sure a worker replica is running, or inbound mail is never picked up.

Replies from your team route back to the customer by matching the In-Reply-To and References threading headers. If you also configure EMAIL_INBOUND_DOMAIN and EMAIL_INBOUND_SIGNING_SECRET for the webhook path, replies additionally route by plus-address. The two inbound methods can run together.

Verify it works

Send a test email to the configured mailbox, then check that it appears as a new conversation within about a minute. If it doesn't:

Confirm QUACKBACK_ROLE isn't web on every replica.
Check the logs for imap inbound not configured (a required variable is missing) or a connection error.
Confirm the email channel is enabled in Admin > Settings > Channels.