> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Implementation method ## Overview After [activating](/docs/channels/email/email-configuration#activate) email in your AI Agent, [setting up Handoffs](/docs/channels/email/email-configuration/email-handoffs), and testing your email setup to ensure it's working properly, you can implement email so your AI Agent can start addressing your customer inquiries. > **Note** > > A single AI Agent can be configured with multiple email addresses, each represented as a separate email channel. Any address you configure on your AI Agent should be different from the support email addresses used by your human agent team, to avoid forwarding in-flight human-team conversations back to the AI Agent. ## Use cases Implementation methods support different email automation scenarios. * **Direct customer emails**: Forward emails sent directly to your support address to your AI Agent for immediate response. * **Contact form submissions**: Use the [Email API](#api) to route form submissions from Zendesk or Salesforce to your AI Agent. * **Ticket backlog processing**: Send existing support tickets to your AI Agent via Email API for automated resolution. * **Hybrid automation**: Combine Direct Email and Email API to maximize your AI Agent's coverage across all inquiry sources. ## Capabilities & configuration Email implementation supports two main methods that can be used independently or together. * **Direct email**: Forward emails [from your support address](#direct-email) to your AI Agent as soon as customers send them. Supports custom forwarding rules and spam filtering. * **Email API**: Send inquiries [programmatically](#api) from contact forms, ticket backlogs, or other systems. Supports passing metadata to create metavariables for AI Agent configuration. ## Quick start Get started with email implementation in a few steps. For detailed instructions, see [Implementation & usage](#forward). Choose your implementation method: Direct email, Email API, or both. Configure your [Bring Your Own Domain](/docs/channels/email/email-configuration/byo-domain) email address. Set up [email forwarding](/docs/channels/email/email-configuration/email-deployment) to your AI Agent's Ada email address. Test your implementation before going live. ## Implementation & usage\[#forward] Configure your email implementation using one or both methods below. ### Direct email\[#direct-email] With this method of implementation, customers will send inquiries to your support email, inquiries will be forwarded to your AI Agent, and your AI Agent will respond from your support email address. ![](/_fern-files/_img/036b6ea75513310988785e18cab8870146c0a9c6f98d33cdd1e145343c314dfc.webp) | Benefits | Things to consider | | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | You can set custom forwarding rules, routing only a percentage of your conversations to your AI Agent | Unless you have percentage-based routing rules in your forwarding setup, 100% of the emails that your customers send to your support email address will be forwarded to your AI Agent to respond to. | | You can set up spam filtering as part of your forwarding rules, so you can prevent spam conversations from being forwarded to your AI Agent. | If you have multiple support email addresses, configure each as a separate email channel through the Bring Your Own Domain flow. Your AI Agent will respond from whichever address the end user originally contacted. | | | If forwarding is active for an address that isn't configured as an inbox — either the inbox hasn't been added yet, or it was deleted while forwarding remained on — the AI Agent still replies. It uses one of the other addresses configured on the AI Agent, with BYOD addresses preferred over the Ada-provisioned address. | | | If you don't set up DNS records in your domain configurations, your AI Agent will respond to your customers from its Ada-provided email address (not your support email). | | | If at any time you wish to stop your AI Agent from handling responses, you can stop forwarding emails to it. | | | Make sure the support email address you use for your AI Agent is publicly available to your customers. | ### Email API\[#api] The Email API allows you to send support inquiries from sources like ticket backlogs, or contact form submissions to Ada for automation. Upon receiving these inquiries, your AI Agent will reply to end users directly in their inbox to continue the conversation and drive resolution autonomously. ![](/_fern-files/_img/ba674debfc04668605946d42445ecdf5140440b2e212128b6ab5bef29be7dc30.webp) Review the benefits and Considerations of the Email API below to determine if this is the right method of email implementation for you.
Benefits Things to consider
You can control the number and type of contact form inquiries that get sent to your AI Agent to resolve, using tagging, submission topic dropdowns, or volume configurations built into your agent platform. Your AI Agent will reach out to the customer's email address that was provided in the contact form. Subsequent back-and-forth will occur in an email thread. These back-and-forth occurring over email don't get synced into your agent platform.
You can also pass metadata through the Email API. Passing metadata creates metavariables in the dashboard that you can leverage to configure your AI Agent (e.g., making rules based on an informational field you pass). Attachments sent through the Email API follow the [attachment handling](/docs/channels/email/email-configuration/email-handoffs/attachment-handling) setting of the inbox your AI Agent replies from. With the default setting, your AI Agent hands off every inquiry that has an attachment to a human agent.
You can pass the files that end users attach to a contact form through the Email API. Send the request as `multipart/form-data` , with up to 10 files and 30 MB in total. Because email forwarding is required for this implementation option, if it's also the email that you use for direct email inquiries, those will also get routed to your AI Agent to resolve. If you wish to omit direct emails from your AI Agent's scope to resolve, consider setting up a different email address for contact form handling, and don't expose that address publicly to customers to reach out to. The same DNS record/forwarding instructions apply to the setup for this separate email address.
> **Warning** > > **Zendesk web form email verification:** Zendesk requires email verification for anonymous help center requests. If you use Zendesk web forms with the Email API, end users will see a prompt — *"Request not yet submitted. Please check your email to verify and submit your request."* — and must verify their email before the ticket reaches the active queue. Your AI Agent will not receive the submission until verification is complete. See [Zendesk's announcement](https://support.zendesk.com/hc/en-us/articles/10360295453082) for details. #### Getting started with the Email API The Email API is an implementation of Ada's Conversations API for the native Email channel. To use it, you'll need either a form provider (such as Zendesk) or your own system that can make a `POST` API call when an email inquiry should be sent to Ada for automation. This call sends the form submission or email content to your AI Agent through the dedicated Email endpoint. 1. Make sure you have an [Email API key](/reference/introduction/authentication#generate-an-ada-api-key) in the Ada Dashboard. 2. Choose the email address you want the AI Agent to use when replying to end users for this implementation. * If you haven't already, configure the address in the **Bring your own domain** section of the **Email** configuration page. You can configure multiple addresses on the same AI Agent — pick the one that matches this Email API integration. 3. Set up your API call with the required fields: * **Endpoint URL**: Make POST calls to this endpoint, replacing `{bothandle}` with your AI Agent's handle. `https://{bothandle}.ada.support/api/v2/conversations/email` > **Tip** > > Your AI Agent handle can be found in the upper left corner of your dashboard, above the left navigation bar. * **Authentication key**: The key you [generated](#email-api-key) in the Ada Dashboard. * **Payload for the call**: The payload for the call is the email content or form submission that should be sent to Ada for email automation. For example: ```json { "name": "FirstName LastName", "reply_to": "user@mail.com", "reply_as": "help@company.com", "cc": ["ccuser1@example.com", "ccuser2@example.com"], "subject": "Email subject", "text": "Email body", "metadata": { "ticket_id": "1001" } } ``` For details, review this [section](../../../reference/conversations/create-email-conversation#request). * **Attachments (optional)**: To include the files an end user attached, send the call as `multipart/form-data` instead of JSON. Put the JSON payload in a part named `data`. Add one part named `attachments` for each file. A request can include up to 10 files and 30 MB in total. For example: ```bash curl -X POST "https://{bothandle}.ada.support/api/v2/conversations/email" \ -H "Authorization: Bearer {api_key}" \ -F 'data={"name": "FirstName LastName", "reply_to": "user@mail.com", "subject": "Email subject", "text": "Email body"};type=application/json' \ -F "attachments=@screenshot.png" \ -F "attachments=@invoice.pdf" ``` Your AI Agent handles the files according to the [attachment handling](/docs/channels/email/email-configuration/email-handoffs/attachment-handling) setting of the inbox it replies from. On inboxes set to **AI Agent replies using the attachment**, your AI Agent reads up to 3 images from each request. It keeps every other file and passes it to a human agent on handoff. 4. Set up the required automations to route inquiries to Ada (e.g., Webhook, Triggers in Zendesk). 5. Test your flow. 6. When you're ready to route live inquiries to Ada via Email API, set up forwarding for your **Bring your own domain** email address. This ensures end-user replies to the AI Agent are correctly routed to the AI Agent for conversation continuity. #### Response codes You may receive the following responses after your call is sent. To troubleshoot errors, first review the returned response.
Response Code Details Additional Troubleshooting Checks
`200` Success Conversation ID is returned
`400` Invalid request, body or headers Check your payload to troubleshoot- your field should be one of the supported fields and types. With attachments, check that you send 10 files or fewer
`401` Unauthorized request Check that you've provided an auth header and that your API key is correct
`413` Content too large Check that the whole request, including attachments, is 30 MB or smaller
`422` Unprocessable content Check that your `reply_as` and `reply_to` is not the same email address. If it is, this is considered a forwarding loop and the request is rejected
`429` Too many requests Rate limit exceeded
`500` Server error Indicates that something went wrong on Ada's end
--- #### Examples That's all you need to know to get started. Next, explore these sample workflows. Each one outlines the key steps for its respective integration. Use these examples as a guide to assist with your setup. #### Example: Set up Zendesk ticket forms You can configure a Zendesk ticket form, and create a webhook and trigger to automatically forward content your customers submit to your AI Agent. 1. **Create a webhook** Follow Zendesk's instructions on [creating a webhook](https://support.zendesk.com/hc/en-us/articles/4408839108378-Creating-webhooks-to-interact-with-third-party-systems#topic_bwm_1tv_dpb), so you can use Zendesk to point to Ada's API. * When you're configuring your endpoint URL, use `https://{bothandle}.ada.support/api/v2/conversations/email`, replacing `{bothandle}` with your own AI Agent handle. * When you're adding your API key, select the "Bearer Token" option. Paste your API key as the value for the "Token" field. You will have generated your token on the API page in the Platform section of the Dashboard. When the webhook is configured, it should look like this: ![Zendesk: Email API authentication](/_fern-files/_img/b93c6c9804d0937cad58fc40867d0ce015d2d438a8654228dc93a74b135bfc1d.webp) 2. **Create a trigger** Follow Zendesk's instructions on [creating ticket triggers](https://support.zendesk.com/hc/en-us/articles/4408886797466-Creating-triggers-for-automatic-ticket-updates-and-notifications#topic_qfk_s23_vsb), so Zendesk can automatically call your webhook as soon as it receives a response to your form. * Recommended conditions: * Ticket > Ticket **Is** Created * Ticket > Attachment **Is not** Present * Ticket > Form **Is** \[Name of Your Webform Submission Form] ![Zendesk: Trigger conditions](/_fern-files/_img/4ef6b1c4fb4d7e2a198116e80eaad4837a9fe5ee3315b550c234f7b8922c96c6.webp) > **Tip** > > If your Ticket > Form condition uses the Default Form, and this form is also shared with other channels (e.g., calls or chats), create a new basic form and set it as the new default. This will ensure you have a dedicated form for Webform Submissions. Otherwise, inquiries from other channels may be routed to Ada via the Email API. * For your trigger actions, you can have any combination of actions. The following two are recommended: * **Call your webhook** 1. Choose **Add action** > **Notify by** > **Active webhook**. 2. Select the webhook you created. 3. For the JSON body, use the following. Make sure to replace the `reply_as` address with either your AI Agent's Ada-provided email address (`help@{bothandle}.email.ada.support`) or the address you've set up in your **Bring your own domain** settings. ``` { "name":"{{ticket.requester.name}}", "reply_to":"{{ticket.requester.email}}", "reply_as":"help@example.ada.support", "subject":"{{ticket.title}}", "text":"{{ticket.latest_public_comment}}", "metadata": { "ticket_id": "{{ticket.id}}" } } ``` * **Optional: Add CC recipients** If you'd like to copy specific email addresses on every outbound message, you can add a `cc` field to the JSON body. For example:`"cc": ["team@example.com"]` * **Close your ticket** 1. Click **Add action** > **Status category**. 2. Select **Closed**. With the two above actions, your configuration should look like this: ![Zendesk actions example](/_fern-files/_img/f44d018448422cfab3e5ec501a9c2534b4b6944df709a4a546aa880fbe50469d.webp) #### Example: Set up Salesforce contact forms You can create a Salesforce case form, and create an automated process to automatically forward content your customers submit to your AI Agent. You, or someone with Salesforce Admin permissions, can 1. **Set up your Salesforce case fields** 1. Add your Ada email as a case origin you can track in Salesforce, so you can track which cases were passed to your AI Agent. Follow Salesforce's instructions in [Add Picklist Values](https://help.salesforce.com/s/articleView?id=sf.fields_picklist_add_values.htm\&type=5). For your **Cases**, in the **Case Origin** field, add a picklist value with your Ada-provided email address (`help@{bothandle}.email.ada.support`) as the value. 2. Create a new check box, so your automation flow can track which cases it's already sent to Ada and doesn't send duplicates. Follow Salesforce's instructions in [Create Custom Fields](https://help.salesforce.com/s/articleView?id=sf.adding_fields.htm\&type=5), and create a check box with the following attributes: * Type: Checkbox; default unchecked * Name: Sent to Ada * Visible to all users * Read-only for all users except System Administrators profile * Do not add to layout 3. Click **Save**. 2. **Set up a flow to send case data to Ada** 1. Add your API credentials to Salesforce so it can use Ada's API to send over email data. Follow Salesforce's instructions to [Create or Edit a Basic Authentication External Credential](https://help.salesforce.com/s/articleView?id=sf.nc_create_edit_basic_auth_ext_cred.htm\&type=5), and enter the following information: * **Label**: `Ada Email API External Credential` * **Name**: `AdaEmailAPIExternalCredential` * **Authentication Protocol**: `No Authentication` Additionally, follow the instructions in the above link to create a principal, to act as a user for the credentials you just made. Use the following information: * **Parameter Name**: `User` * **Sequence Number**: `1` * **Identity Type**: `Named Principal` 2. Instead of putting your authentication in the credentials, add a custom header. Follow Salesforce's instructions to [Create and Edit Custom Headers](https://help.salesforce.com/s/articleView?id=sf.nc_create_custom_headers.htm\&type=5), and enter the following information: * **Name**: Authorization * **Value**: Bearer \. Paste in the API key you generated from the API page in the Ada Dashboard. * **Sequence Number**: `1` 3. Create a permission set, so you can share the credentials you just made with other admins. Follow Salesforce's instructions to [Create Permission Sets](https://help.salesforce.com/s/articleView?id=sf.perm_sets_create.htm\&type=5), and do the following: * **Name**: `Ada Email Http Callout` * Click **External Credential Principal Access**, then add the `Ada Email API External Credential` you created * Follow Salesforce's instructions to [Manage Permission Set Assignments](https://help.salesforce.com/s/articleView?id=sf.perm_sets_manage_assignments.htm\&type=5) to assign the new permission set to yourself and any other admins 4. Create a named credential. Follow Salesforce's instructions to [Create or Edit a Named Credential](https://help.salesforce.com/s/articleView?id=sf.nc_create_edit_named_credential.htm\&type=5), and enter the following information: * **Label**: `Ada Email API Named Credential` * **Name**: `AdaEmailAPINamedCredential` * **URL**: `https://{bothandle}.ada.support/api/v2/conversations/email`, replacing `{bothandle}` with your AI Agent's handle * Under **Authentication**, under **External Credential**, select the `Ada Email API External Credential` you created earlier 3. **Create a flow to automate closing cases** 1. Create a flow to update the case's status to Closed. Follow Salesforce's instructions to [Build a Flow](https://help.salesforce.com/s/articleView?id=sf.flow_build.htm\&type=5), and do the following: * Create a **Record-Triggered Flow** * **Object**: `Case` * **Trigger the Flow When**: `A record is created or updated` * **Condition Requirements**: `All Conditions are Met (AND)` * `Origin` `Equals` `Ada Email` * `Status` `Does Not Equal` `Closed` * **When to Run the Flow for Updated Records**: `Every time a record is updated and meets the condition requirements` * **Optimize the Flow for**: `Fast Field Updates` 2. Add an Update Triggering Record element to the flow. In the **New Update Records** window, enter the following information: * **Label**: `Update Status` * **API Name**: `Update_Status` * **How to Find Records to Update and Set Their Values**: `Use the case record that triggered the flow` * **Condition Requirements to Update Record**: `None - Always Update Record` * **Field**: `Status` * **Value**: `Closed` 3. Save and activate your flow, giving it a name like `CASE: Update Ada Email Status to Closed`. 4. **Create a flow to automate sending cases to Ada, using an HTTP callout** 1. Create a new flow to automatically send cases to Ada. Follow Salesforce's instructions to [Build a Flow](https://help.salesforce.com/s/articleView?id=sf.flow_build.htm\&type=5), and do the following: * Create a **Record-Triggered Flow** * **Object**: `Case` * **Trigger the Flow When**: `A record is created or updated` * **Condition Requirements**: `All Conditions are Met (AND)` * `Origin` `Equals` `Ada Email` * `Status` `Does Not Equal` `Closed` * `Sent_to_ada__c` `Equals` `False` * **When to Run the Flow for Updated Records**: `Only when a record is updated to meet the condition requirements` * **Optimize the Flow for**: `Actions and Related Records` 2. Add a scheduled path to the flow. Follow Salesforce's instructions to create [Scheduled Paths](https://help.salesforce.com/s/articleView?id=sf.flow_concepts_trigger_scheduled_path.htm\&type=5), and add the following information: * **Path Label**: `API to Ada` * **API Name**: `API_to_Ada` * **Time Source**: `Case: Last Modified Date` * **Offset Number**: `1` * **Offset Options**: `Minutes After` * **Advanced** > **Batch Size**: `1` 3. Add an HTTP callout to the flow. Follow Salesforce's instructions to [Configure an HTTP Callout Action](https://help.salesforce.com/s/articleView?id=sf.flow_http_callout_configure.htm\&type=5), and add the following information: 1. External service configuration: * **Category**: `HTTP Callout` * **Named Credential**: `Ada Email API Named Credential` 2. Invocable action: * **Label**: `Ada Email Invocable Action` * **Method**: `POST` * **Sample JSON request**: ``` { "name":"{{ticket.requester.name}}", "reply_to":"{{ticket.requester.email}}", "reply_as":"help@example.ada.support", "cc":["{{CcAddress}}"], "subject":"{{ticket.title}}", "text":"{{ticket.latest_public_comment}}", "metadata": { "ticket_id": "{{ticket.id}}" } } ``` * **Sample response body**: Not required This creates an Apex class variable that you can use in step e, so you can specify individual dynamic fields to send. 4. Now that you've configured the action, add it to your flow, so you can use the API callout to send cases to Ada. Use the following information: * **Name**: `Send to Ada` * **API Name**: `SendtoAda` * **Body**: `Apex-Defined Variable` * **Value**: Create a variable called `AdaEmailBody` 5. In your flow, add an assignment element **before** the action element you just added. You can see an example at Salesforce's [Flow Element: Assignment](https://help.salesforce.com/s/articleView?id=sf.flow_ref_elements_assignment.htm\&type=5) topic. Enter the following information: * **Label**: `Set Body Variables` * **API Name**: `Set_Body_Variables` Then, add each of the following variables by choosing the Apex-defined variable you created above, then the corresponding fields in your Salesforce case: * `AdaEmailBody > name` `Equals` `$Record > Name` * Optional: `AdaEmailBody > replyx5fas` `Equals` `help@company.com` * `AdaEmailBody > replyx5fto` `Equals` `$Record > Email Address` * `AdaEmailBody > subject` `Equals` `$Record > Subject` * `AdaEmailBody > text` `Equals` `$Record > Description` * `AdaEmailBody > metadata > ticket` `Equals` `$Record > Case ID` Ensure that all of the above values are on your case creation form, with the exception of your reply-as email. 6. Add an Update Triggering Record element to the flow. In the **New Update Records** window, enter the following information: * **Label**: `Update Sent to Ada checkbox on Case` * **API Name**: `Update_Sent_to_Ada_checkbox_on_Case` * **How to Find Records to Update and Set Their Values**: `Use the case record that triggered the flow` * **Condition Requirements to Update Record**: `None - Always Update Record` * **Field**: `Sent_to_Ada__c` * **Value**: `True` 7. Save and activate your flow, giving it a name like `CASE: Send to Ada Email`. 5. Test your flow. Create a case with a `Case Origin` of `Ada Email`, and use a valid email address to test. You should be able to see the conversation appear in Ada, and get a reply at the email address you provided. ### Implementation examples\[#implementation-examples] #### Hybrid implementation: Direct email + Email API\[#hybrid] You can use both direct email and Email API implementation methods to automate inquiries on all fronts, expanding your AI Agent's scope of responsibility. | Benefits | Things to consider | | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Maximize your AI Agent's oversight, handling even more inquiries automatically, and reducing the strain on your live agents. | Your AI Agent will automatically create tickets in your agent platform for inquiries that originated from a contact form, but it won't make tickets for inquiries over direct email. | | | If you want direct emails and contact form submissions to create a ticket in your agent platform, and then route those inquiries to Ada via Email API, make sure to use a different support email address for the AI Agent than the email address used to create those tickets in the agent platform from direct email. | #### Agent platform tickets\[#agent-platform] If you use any alternate methods to create tickets in your agent platform (outside of contact forms or direct emails), you can use the Email API to route tickets from your Agent platform to your AI Agent. #### Implementation notes\[#implementation-notes] * Regardless of a conversation's implementation method (direct email, contact forms, agent platform tickets), you can view conversation transcripts in the Conversations section of the Ada dashboard. * However, if a conversation happens in an email thread, that conversation won't appear in your agent platform, unless a handoff with a transcript occurs. * If a conversation starts with your agent platform and later gets handed off, the handoff doesn't update the original ticket. * Ada has a Zendesk Conversation Solution sync available if you need to sync contained conversations that your AI Agent was able to handle without handoff back into Zendesk. Contact your Ada team to learn more. ## Related features Explore additional Email configuration and deployment options. * [Email configuration](/docs/channels/email/email-configuration): Activate and test your Email channel. * [BYO domain](/docs/channels/email/email-configuration/byo-domain): Configure your own email domain for your AI Agent. * [Email deployment](/docs/channels/email/email-configuration/email-deployment): Set up email forwarding to your AI Agent. * [Email handoffs](/docs/channels/email/email-configuration/email-handoffs): Configure how your AI Agent escalates conversations to human agents. * [API keys](/reference/introduction/authentication): Generate API keys for the Email API. --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).