Email channel: forwarding and IMAP/SMTP

Open in

View as Markdown

Open in ChatGPT Open in Claude

Conversa Labs

Last updated on Oct 13, 2026

Overview

The Email channel turns incoming emails into conversations inside the platform. Your team replies from the same panel as every other conversation, with per-contact history, assignment, internal notes and automations — no need to open a separate email client.

There are two ways to connect: by forwarding (you redirect emails to an address generated by the platform) or by IMAP/SMTP (the platform reads from and sends through your own mailbox directly). Pick whichever fits your operation best.

When the Branded Email Templates feature is enabled on the account, you can also define a branded email layout — the HTML that wraps the body of the reply sent to the customer. That layout can apply to the whole account or be different for each email inbox, so every inbox replies with its own visual identity.

Prerequisites

An administrator profile to create the email inbox.
A dedicated support email address (for example, support@yourcompany.com).
For IMAP/SMTP mode: your mailbox server details (host, port, username and password or app password) and IMAP/SMTP access enabled at your provider.
For the branded layout: the Branded Email Templates feature enabled on the account. It ships disabled by default and is turned on account by account.

Step by step

Under Settings → Inboxes, create a new inbox and choose Email.
Enter the name and the support email address.
Choose the connection mode:
- Forwarding: the platform generates a receiving address. In your email provider, set up a forwarding rule from your support address to that generated address. That generated address only appears when the installation is set up to receive email; if it is not, the platform states that IMAP/SMTP is required and no email is processed without it.
- IMAP/SMTP: enter the incoming (IMAP) and outgoing (SMTP) server details.
Save and send a test email to the support address.
Confirm the email shows up as a new conversation in the inbox and reply from there.
(Optional) Open Settings → Account → Branded emails to set the account layout, or Settings → Inboxes → your email inbox → Configuration → Branded emails to customize that inbox.
Check the displayed layout source. Choose Customize inherited layout to start from the inherited HTML, keep {{ content_for_layout }}, then select Preview draft and Save layout. When the source is no layout saved, there is no HTML to inherit: the editor starts from a minimal layout that holds only the marker.
Reply to a test conversation and check the received email to confirm the layout was applied.

Inheritance, preview and unsaved changes

Use inherited layout clears the editor as a draft. The change takes effect only after Save layout; an inbox then inherits the account layout or, when the account has none, the installation layout. When no layout is saved at any of those levels, the displayed source is no layout saved: the reply is sent without a layout, and the preview shows exactly that. Discard changes asks for confirmation and restores the saved version. A failed save keeps your draft and shows the validation error. Leaving the page with unsaved changes asks before discarding it.

The preview uses the same Liquid renderer as reply emails, with synthetic message content and people. It does not send mail or modify the saved template. External images, scripts, links and forms are blocked in the preview; check the actual received email to validate the final appearance. Existing layouts configured through the API are preserved. API integrations may still use the account layout endpoint (with optional inbox_id) or the existing inbox update endpoint.

Settings & options

Connection mode: forwarding or IMAP/SMTP, as chosen at creation.
Outgoing server (SMTP): used to send replies from the platform with your address.
Signature and identity: configure how your name and address appear to the recipient.
Conversation threading: replies on the same subject/thread are grouped into one conversation.
Branded email layout: the HTML that wraps the reply body. The platform always looks for the layout in this order — inbox → account → installation — and uses the first one it finds. So an inbox without its own layout inherits the account's.
Per-inbox scope: only email inboxes accept their own layout. The inbox layout is returned by the inbox API only to administrators and only while the feature is enabled.
Removing the layout: send the same branded_email_layout field blank (or with the value null). The inbox falls back to the account's layout, or to the installation's.

Use cases

Centralize email support alongside WhatsApp, website and social channels.
Route messages from a corporate address (support@, sales@) to the right team.
Apply automations and auto-assignment to incoming emails.
Serve several brands from one account, with one email inbox and one visual layout per brand.

Tips, limits & best practices

Prefer a dedicated support address so it doesn't mix with a personal inbox.
On providers with two-step verification, use an app password for IMAP/SMTP.
Test both sending and receiving before sharing the address with customers.
The layout HTML must contain the {{ content_for_layout }} marker — that is exactly where the reply body is inserted. Without the marker the platform refuses to save it.
The layout is validated as Liquid and can use the platform's message variables, among them contact (for example, {{ contact.name }}), agent, inbox, account, conversation and brand.
The layout body accepts at most 256 KB.
The inbox layout applies only to conversation replies sent by email. The account layout is the account's base email layout: with the feature on, it also wraps the platform's other emails that use the standard layout, such as agent notifications. To change only how customer replies look, use the per-inbox layout.
After upgrading the platform, Branded Email Templates is left disabled on every account: it reuses the former insert_article_in_reply feature, and the upgrade migration disables the new feature on every account where it appeared enabled. Turn it back on wherever you use the layout.

Troubleshooting

Emails don't arrive: review the forwarding rule or the IMAP details; check the destination's spam folder.
Can't send replies: verify SMTP host, port and credentials, and that the provider allows sending from external apps.
Duplicate conversations: make sure only one forwarding rule is active for the address. Validation messages appear in the dashboard language of the person editing (or in the account language when that person has not chosen one). The texts below are the English ones.
"Branded email templates feature is not enabled": the feature is off on this account. Enable it and try again.
"Branded email layouts require an email inbox": you tried to save a layout on an inbox that is not an email inbox. Use the account layout instead. Through the inbox update endpoint the text is "Branded email layout is only supported for email inboxes".
"Body must include {{ content_for_layout }}": the marker is missing from the HTML you sent.
"Body has invalid Liquid syntax": review the {{ }} braces and {% %} blocks in the HTML. The technical detail after the colon comes from the Liquid parser.
The email arrived without the layout: confirm the feature is enabled on the account, that a layout is saved (on the inbox, the account or the installation) and that the inbox is an email one. With no layout saved, the editor shows the source no layout saved and the reply goes out without a layout.