Email handoff

When the agent should not answer an email itself, it hands the conversation to your team. Email handoff is not a live transfer. The agent sends two emails:

To your handoff inbox: a case bundle with the customer’s details, a summary of the conversation, a suggested reply, and the full thread attached. Your team edits the suggested reply and sends it from their own inbox or helpdesk.
To the customer: a message in their existing thread saying that a member of the team will reply.

Handoff is configured per environment on the Handoffs tab of Channels > Email, and triggered from a function that returns an email_integration handoff.

When the agent hands off

An email is handed off when:

Your function triggers it. For example, the email is a complaint, refund request or regulated query, the customer asks for a person, or the knowledge base cannot answer it. See Trigger a handoff from a function.
It has attachments the agent cannot take. If attachments are turned off, or any file breaks the attachment rules, the email goes straight to your team. When attachments are on, the agent accepts up to five PDF, JPEG or PNG files of up to 5 MB each.
It is larger than 10 MB.

Emails handed off because of attachments or size skip the agent entirely. Your handoff inbox receives a notice with the customer’s address, the subject, the message text and a list of the attachments, but not the files themselves. Keep a copy of incoming mail in your own inbox so your team can open the originals.

Configure handoff in Agent Studio

Open Channels > Email > Handoffs and pick the environment in the top right. You need an email address in that environment before you can edit its handoff settings.

Human handoff template

This card controls the case bundle your team receives.

Setting	Description
Handoff inbox	The address that receives handed-off emails. It must be monitored. To route handoffs into Zendesk, Salesforce Service Cloud or another helpdesk, use an inbound address from that tool
Include in handoff	The fields shown in the bundle. Choose any of Customer first name, Customer email, Case subject, Conversation summary and Suggested reply. All are on by default and at least one must stay on
Greeting	How the bundle opens: Customer first name, No greeting or Custom

Email preview shows the bundle with sample data as you change these settings.

A mistyped handoff address is the most common setup problem. Check it by triggering a handoff in Sandbox and confirming the case arrives.

Customer handoff message

Handoff message to customers is the text the customer receives in their thread when the agent hands off. Write it in your own voice. If you leave it empty, the customer receives:

Thanks for your message — we’re connecting you with a human agent who will reply to this email shortly.

A function can replace this message for a single handoff with notify_message.

What your team receives

The case bundle arrives at the handoff inbox:

Subject: the customer’s own subject line, unchanged, so the case files next to the original thread.
Body: the heading New escalation case, then the fields you selected under Include in handoff, then any custom fields under Additional details.
Attachment: the full conversation as full-transcript.eml.
Reply-To: the customer’s address, so replying to the bundle reaches the customer directly.

The platform writes the Conversation summary and Suggested reply with your agent’s language model, from what the customer and the agent said. The suggested reply is written from your team’s point of view, in the customer’s language, with placeholders such as [insert X information here] where the agent does not know a detail. Function outputs and internal instructions are never included. If generation fails, the bundle is still sent without those two fields.

Trigger a handoff from a function

Return a handoff payload with email_integration from a function, then call that function from the topics, rules or flow steps that should hand off.

def handoff_to_human(conv: Conversation, reason: str):
    return {
        "handoff": {
            "text_chat": {
                "email_integration": {
                    "custom_fields": {
                        "Handoff reason": reason,
                        "Membership number": conv.state.get("membership_number", ""),
                    },
                },
            },
        },
    }

Field	Required	Description
`custom_fields`	No	Extra rows shown under Additional details, such as an order number, booking reference or the handoff reason. Keys are shown as labels exactly as written and rows are sorted by key, so use display-ready names. Up to 20 rows; keys over 64 characters and values over 512 characters are truncated
`notify_message`	No	Replaces the Customer handoff message for this handoff. Sent exactly as written

Pass an empty object, "email_integration": {}, to hand off with the default bundle and customer message. You do not need to write the summary or suggested reply. The platform generates both and replaces any value a function passes for them.

Best practices

Tell the agent when to hand off. In your rules, list the cases that must always reach a person, such as complaints, refunds, disputes, legal threats and requests for a human, and the reason to pass for each.
Send reasons as custom fields. A Handoff reason row lets your team triage the inbox without opening each case.
Keep chat and voice phrasing out of email. If you clone rules from a voice or chat project, remove phrases such as “I’ll put you through” or “thanks for calling”.
Review handoffs regularly. Every handed-off conversation is visible in Conversation Review. Recurring handoff topics are candidates for new knowledge base content.

Configuring a mailbox

Connect your support address and set up DNS

Email overview

How the email channel works and its current limitations

Chat handoff integrations

Hand off webchat and SMS conversations to a live agent

Tools

Write the function that triggers the handoff

Get started

Wren

Analytics

Conversations

Behavior

Knowledge

Flows

Tools

Extend with code

Testing

Real-time config

Voice

Messaging

Integrations

Deployments

Widgets

Account

When the agent hands off

Configure handoff in Agent Studio

Human handoff template

Customer handoff message

What your team receives

Trigger a handoff from a function

Best practices

Configuring a mailbox

Email overview

Chat handoff integrations

Tools

​When the agent hands off

​Configure handoff in Agent Studio

​Human handoff template

​Customer handoff message

​What your team receives

​Trigger a handoff from a function

​Best practices

​Related pages

Configuring a mailbox

Email overview

Chat handoff integrations

Tools

When the agent hands off

Configure handoff in Agent Studio

Human handoff template

Customer handoff message

What your team receives

Trigger a handoff from a function

Best practices

Related pages