Salesforce SMTP Connector

Overview

The Salesforce SMTP Connector hands off Email conversations from your AI Agent to Salesforce as Cases. Human agents reply from the Case, and the end user gets the reply from your support email address, in the same email thread.

When a Handoff runs the Salesforce Email block:

1. The AI Agent creates a Case in Salesforce.
2. The AI Agent adds the conversation transcript and the attachments of the end user’s latest email to the Case as an email.
3. New emails from the end user go to the Case. The AI Agent does not reply to them.
4. A human agent replies from the Case. Salesforce sends the reply through the SMTP Connector, and the end user gets it from your support email address.

Limitations

The connector has these constraints:

• Email only. The Salesforce Email block works on the Email channel only. On other channels, the AI Agent sends the Error fallback response.
• One Salesforce org per AI Agent. All Email inboxes on the AI Agent use the same Salesforce connection. You cannot connect a different Salesforce org to each inbox. One Salesforce org can connect to more than one AI Agent. See Connect more than one AI Agent.
• Other AI Agents must be in the same region. One AI Agent can relay agent replies for up to 20 other AI Agents in its region.
• The Handoff ends when the conversation closes. A conversation closes after 72 hours with no new email in the thread. Closing the Case in Salesforce does not end the Handoff. After the conversation closes, a new email from the end user starts a new conversation with the AI Agent.
• Human agents must reply from the Organization-Wide Address that matches the BYOD address of an Ada Email inbox. A reply from any other address does not go through the connector.
• Cases that the AI Agent did not create. A human agent can email an end user from such a Case. The end user’s reply goes to the Case for 14 days after the first email in the thread. After 14 days, the reply goes to the AI Agent as a new conversation. See Replies on Cases that the AI Agent did not create.

Use cases

Use the Salesforce SMTP Connector when:

• Your human agents work Email escalations as Salesforce Cases.
• You want human agents and the AI Agent to use the same support email address.
• You want escalated conversations to stay in one email thread for the end user.
• You have more than one AI Agent or support address, and you want all of them to hand off to one Salesforce org.

Capabilities & configuration

The connector gives your Email Handoffs these capabilities:

• Case creation. Each Handoff creates one Case. The Case Subject is the email subject, and Case Origin is Email.
• Transcript and attachments. The Case gets the conversation transcript and the attachments of the end user’s latest email as an email in the Case feed. If a file cannot be attached, the Case gets a comment that lists it.
• Contact linking. The AI Agent links the Case to an existing Contact with the same email address. It does not create Contacts. If no Contact matches, the Case gets the end user’s name and email in the Web Name and Web Email fields.
• Case field mapping. In the Salesforce Email block, you can set Case fields from fixed values or from variables.
• Reply sync. End user replies go to the Case as new emails. During a Handoff, replies from CC’d participants also go to the Case, whatever the reply-all behavior of the inbox is.
• Agent replies in Ada. Human agent replies appear in the conversation in Ada, so transcripts and reports include them. Each reply shows the name of the Salesforce user who sent it, and Ada counts each user as a separate human agent in reports. If the AI Agent cannot read the Salesforce user, the reply shows the display name of the Organization-Wide Address.
• Many inboxes and AI Agents. Each Email inbox has its own Salesforce SMTP Connector toggle. One Email Relay in Salesforce can send agent replies for more than one AI Agent. See Connect more than one inbox and Connect more than one AI Agent.

Replies on Cases that the AI Agent did not create

A human agent can email an end user from any Case, for example a Case from Email-to-Case or a Case that an agent created. The email goes through the connector when the agent sends it from the Organization-Wide Address for your support address. Salesforce marks the email with the Case. When the end user replies, the AI Agent adds the reply to that Case as an incoming email. The AI Agent does not start a conversation and does not answer the end user.

The reply goes to the Case only when all of these are true:

• The human agent sent the email from the Case in Salesforce. An email from a mail client outside Salesforce is not linked to a Case.
• The end user replied to that email. A new email that is not a reply goes to the AI Agent.
• The end user replied within 14 days of the first email in the thread. A later reply goes to the AI Agent as a new conversation. A later email from the Case does not extend the 14 days if it replies in the same thread.
• The email thread has no conversation with the AI Agent. A reply in a thread that the AI Agent handed off goes through the Handoff.

If Salesforce is not available, the reply is tried again for up to 72 hours. If Salesforce does not accept the reply, for example because the Case was deleted, the reply goes to the AI Agent as a new conversation.

Quick start

Complete these steps to set up the connector for one AI Agent. See Implementation & usage for the detailed steps.

Implementation & usage

Follow these steps in order. Some steps need values from an earlier step.

Prerequisites

Before you start, make sure that:

• Your AI Agent has an Email inbox on your own domain. For more information, see Bring your own domain.
• Your Salesforce org has API access. Enterprise, Performance, Unlimited, and Developer editions include it. Professional edition needs the API add-on.
• The person who configures Salesforce can change the Setup settings in this guide. If you are not sure which permissions this needs, use a user with the System Administrator profile.
• You can add a DNS TXT record to the domain of your support email address.

You also need your Salesforce My Domain URL. In Salesforce Setup, go to My Domain and copy the Current My Domain URL. It looks like https://yourcompany.my.salesforce.com.

Step 1: Create the integration user

The AI Agent makes all Salesforce changes as this user. A dedicated user shows clearly which Cases come from the AI Agent.

To create the integration user:

1. In Salesforce Setup, go to Users and click New User.

2. Enter these values:

   Field	Value
   First Name, Last Name	For example, Ada and Integration
   Email	A shared team address, for example salesforce-admins@yourcompany.com. A personal address can be used, but the integration user is then tied to that email.
   Username	A unique value in email format, for example ada.integration@yourcompany.com
   User License	Salesforce Integration
   Profile	Minimum Access - API Only Integrations

3. Clear the Generate new password and notify user immediately check box. This user never logs in.

4. Click Save.

5. On the new user, in Permission Set License Assignments, click Edit, select Salesforce API Integration, and click Save.

   Use Permission Set License Assignments, not Permission Set Assignments. You assign the permission set in the next step.

Step 2: Create the permission set

The permission set gives the integration user access to Cases and Contacts only.

To create the permission set:

1. In Setup, go to Permission Sets and click New.

2. Enter a label, like Ada SMTP Handoff.

3. Set License to Salesforce API Integration. If the user has a Salesforce license, select --None--. You cannot change this value later.

4. Click Save.

5. In Object Settings, set these permissions:

   Object	Object permissions	Field permissions
   Cases	Read, Create, Edit	Edit on Subject, Description, Contact Name, Web Email, Web Name, and Case Origin
   Contacts	Read, View All Records	Read on Email

   Salesforce sharing can hide Contacts from the integration user. A Contact with no Account is visible only to its owner. Without View All Records, the AI Agent cannot find these Contacts, and the Case is not linked to them. Field permissions still apply, so the integration user can read only the Email field on Contacts.

6. If your Cases use record types, select the record type for email Cases in Case: Record Type Assignments.

7. Click Manage Assignments, click Add Assignment, and assign the permission set to the integration user.

Step 3: Create the External Client App

The External Client App gives the AI Agent its Salesforce credentials.

To create the External Client App:

1. In Setup, go to External Client App Manager and click New External Client App.
2. Enter a name, like Ada SMTP Handoff, and the shared team address from Step 1 as the contact email. Set Distribution State to Local.
3. Select the Enable OAuth check box, and enter a dummy URL, like http://localhost/callback, as the Callback URL. Ada does not use this URL, but Salesforce requires it.
4. Add the OAuth scope Manage user data via APIs (api).
5. Select the Enable Client Credentials Flow check box, and click Create.
6. Open the Policies tab and click Edit.
7. Under OAuth Policies, in OAuth Flows and External Client App Enhancements, select the Enable Client Credentials Flow check box. In Run As (Username), enter the username of the integration user, for example ada.integration@yourcompany.com. Click Save.

To copy the Consumer Key and Consumer Secret:

1. Open the Settings tab of the app.
2. Under OAuth Settings, click Consumer Key and Secret, and complete the identity check.
3. Copy the Consumer Key and Consumer Secret. You enter them in Ada in the next step.

Step 4: Connect Ada to Salesforce

In Ada, you enter the Salesforce credentials and get the Ada credentials for the Salesforce Email Relay.

To connect Ada to Salesforce:

1. On the Ada dashboard, go to Config > CHANNELS > Email, and select your inbox.

2. Scroll to the Salesforce SMTP Connector section and click Configure connection.

   

3. Under Salesforce credentials, enter your My Domain URL as the Instance URL. Then enter the Consumer key and Consumer secret.

4. Under Ada credentials, click Generate a Password. Copy the password and store it in a safe place.

5. Copy the Outbound hostname, SMTP port, and Username of this account. The username has the format <AI Agent handle>.<region domain>, for example yourcompany.ada.support. You need these values and the password in Step 6.

6. Click Save.

When you click Save, Ada checks the credentials, the integration user’s access to Cases, and, if you changed the Other AI Agents list, the password of each AI Agent in it. If the check passes, the Salesforce SMTP Connector toggle is enabled for this inbox. If it fails, the error message tells you what to fix.

Step 5: Set up Case email in Salesforce

Salesforce needs Email-to-Case and the Case feed to show the emails that the AI Agent adds to a Case.

To set up Case email:

1. In Setup, go to Email-to-Case. Select Enable Email-to-Case and click Save. You do not need a routing address. Salesforce does not let you turn off Email-to-Case after you turn it on.
2. On the same page, clear the Insert Thread ID in the Email Subject and Insert Thread ID in the Email Body check boxes. The thread ID changes the subject of agent replies, and that can split the email thread in some email clients.
3. Go to Support Settings and click Edit. Select Enable Case Feed Actions and Feed Items and click Save. If this check box is not there, turn on feed tracking for Case in Feed Tracking first.

Step 6: Add the Email Relay

Agent replies leave Salesforce through an Email Relay to Ada. Ada then sends them to the end user from your support email address.

To let Salesforce send email:

1. In Setup, go to Deliverability, set Access level to All email, and click Save.

To verify your email domain:

1. In Setup, go to Authorized Email Domains and click Add.
2. Enter the domain of your support email address, for example yourcompany.com, and click Save.
3. Add the verification key that Salesforce shows as a DNS TXT record on your domain.
4. Open the domain and verify ownership. Wait for the Verified status.

To add the Organization-Wide Address:

1. In Setup, go to Organization-Wide Addresses and click Add.
2. Enter a Display Name. End users see this name on every agent reply, so use the name of your support team.
3. Enter your support email address. This is the same address as your Ada Email inbox.
4. Select Allow All Profiles to Use this From Address and click Save.
5. Click the link in the verification email from Salesforce.

To add the Email Relay:

1. In Setup, go to Email Relays and click Create Email Relay.

2. Enter the Ada credentials from Step 4:

   Salesforce field	Value
   Host	Outbound hostname
   Port	SMTP port
   TLS Setting	Required Verify
   Enable SMTP Auth	Selected
   Auth Type	Auth Plain
   Username	Username of this account, for example yourcompany.ada.support
   Password, Confirm Password	The password you generated

3. Click Save.

To add the Email Domain Filter:

1. In Setup, go to Email Domain Filters and click Create.
2. Set Sender Domain to the domain of your support email address. Set Recipient Domain to *.
3. Select the Email Relay you created, select Active, and click Save.

The filter sends only email from your support domain through Ada. All other Salesforce email is not changed.

Step 7: Add the Salesforce Email block to your Handoff

The Salesforce Email block creates the Case when the Handoff runs.

To add the block:

1. On the Ada dashboard, go to Config > AI AGENT > Handoffs, then create or select a Handoff.
2. Set the Handoff availability so it applies only when the channel is Email.
3. In the Build the Handoff section, drag the Salesforce Email block from the block bar into your Handoff content.
4. Optional: under Case fields, map Case fields to fixed values or variables.
5. Click Save, and make sure the Handoff is Active.

If Salesforce requires a Case field that you did not map, the block shows a warning. Map the field, unless Salesforce sets it automatically. If the Case cannot be created, the AI Agent sends the Error fallback response.

Connect more than one inbox

One AI Agent can hand off from more than one Email inbox to the same Salesforce org. The inboxes can use the same domain or different domains, for example support@yourcompany.com, billing@yourcompany.com, and support@help.yourcompany.com.

All inboxes on the AI Agent share one Salesforce connection, one set of Ada credentials, and one Email Relay. Each email domain and each support address needs its own Salesforce settings:

To connect another inbox:

1. In Ada, add the inbox and its support address. For more information, see Bring your own domain.
2. If the support address uses a new domain, add the domain in Authorized Email Domains and verify it, as in Step 6.
3. If the support address uses a new domain, add an Email Domain Filter for that domain. Select the Email Relay that you already created for the AI Agent.
4. Add the support address as an Organization-Wide Address, and click the link in the verification email. The email is visible in an Ada conversation.
5. In Ada, go to Config > CHANNELS > Email, select the inbox, and enable the Salesforce SMTP Connector toggle.

Each inbox has its own Salesforce SMTP Connector toggle. For example, if you disable the toggle for support@yourcompany.com, Handoffs from billing@yourcompany.com continue. When the toggle is disabled for an inbox, the Salesforce Email block sends its fallback response.

Connect more than one AI Agent

One Salesforce org can receive Handoffs from more than one AI Agent. Connect one AI Agent first, with Steps 1–7. This AI Agent is the primary AI Agent. It owns the only Email Relay. Then add each other AI Agent to the Other AI Agents list of the primary AI Agent.

The Email Relay logs in as the primary AI Agent. For each agent reply, Ada reads the From address and sends the reply as the AI Agent that has that address as an inbox. The reply then appears in the conversation of that AI Agent.

To connect another AI Agent:

1. On the other AI Agent, add its Email inboxes and support addresses. For more information, see Bring your own domain.
2. On the other AI Agent, complete Step 4 with the Instance URL of the primary AI Agent, and the Consumer key and Consumer secret from Step 3. Ada does not show the secret again. To copy it again, open the app in External Client App Manager and click Consumer Key and Secret. Click Generate a Password. Copy the Username of this account, for example yourcompany-billing.ada.support, and the password. Click Save.
3. On the primary AI Agent, go to Config > CHANNELS > Email, select an inbox, and click Configure connection.
4. Under Other AI Agents, click Add AI Agent. Enter the username and the password from step 2, and click Save.
5. In Salesforce, for each support address of the other AI Agent on a new domain, add the domain in Authorized Email Domains and verify it. Then add an Email Domain Filter for that domain, and select the Email Relay of the primary AI Agent.
6. Add each support address of the other AI Agent as an Organization-Wide Address, and click the link in the verification email. The email is visible in an Ada conversation on the other AI Agent.
7. On the other AI Agent, enable the Salesforce SMTP Connector toggle for each other inbox, and complete Step 7.

When you click Save on the primary AI Agent, Ada checks each username and password in the list. If a check fails, an error under the list tells you which AI Agent to fix.

You can add up to 20 other AI Agents. All of them must be in the same region as the primary AI Agent, and they must use the same Salesforce org.

Regenerating the Ada password

Ada shows the password one time only. If you lose it, regenerate it. After you regenerate the password, the previous password works for 5 more minutes. Then it stops working.

To regenerate the Ada password:

1. In Ada, go to Config > CHANNELS > Email, select an inbox, and click Configure connection.
2. Under Ada credentials, click Regenerate Password. Copy the new password and store it in a safe place.
3. Within 5 minutes, enter the new password in each place that uses it:
   • If this AI Agent owns the Email Relay, open the relay in Setup > Email Relays. Enter the new password in Password and Confirm Password, and click Save.
   • If this AI Agent is in the Other AI Agents list of the primary AI Agent, enter the new password for this AI Agent in that list. Then click Save on the primary AI Agent.

If the Other AI Agents list has a password that no longer works, agent replies from that AI Agent still get to the end user. But Ada sends them as the primary AI Agent, and they do not appear in the conversation of the other AI Agent. Ada does not show an error for this.

Clear configuration on another AI Agent also revokes its password. Remove the AI Agent from the list, or enter its new password after you connect it again.

Best practices

Test the full flow before your AI Agent hands off live conversations, and stop the connector in the correct order.

Test the connector

Use an email address that is not an agent or admin address in Salesforce. If you connect more than one AI Agent, test each AI Agent.

To test the connector:

1. Send an email to your support address, and ask for a human agent.
2. In Salesforce, open the new Case. Make sure the transcript email is in the Case feed.
3. Reply from the Case with the Email action. Select the Organization-Wide Address as the From address.
4. Make sure the reply arrives in the same email thread, from your support address.
5. In Ada, make sure the reply appears in the conversation, with the name of the human agent.
6. Reply to that email. Make sure your reply appears on the Case, and the AI Agent does not reply.

Turn off the connector

Handoffs to Salesforce stop for one inbox when you disable its Salesforce SMTP Connector toggle in Config > CHANNELS > Email. While another inbox on the AI Agent is enabled, Cases that are already open continue to get end user emails.

When the last toggle on an AI Agent is disabled, the connector turns off for that AI Agent. Open Cases then stop getting end user emails, and Ada rejects the agent replies from the addresses of that AI Agent. The Case shows each rejected reply as sent, but the end user does not get it. The Salesforce Email Log shows the reply as a permanent failure with a 550 error.

To stop Handoffs from another AI Agent:

1. On the primary AI Agent, click Configure connection. Under Other AI Agents, remove the AI Agent, and click Save.
2. On the other AI Agent, disable the toggle for each inbox.

After step 1, agent replies from the addresses of that AI Agent go out as the primary AI Agent, and they do not appear in Ada. Do step 1 first. While the AI Agent is in the list with no enabled inbox, Ada rejects its agent replies.

To stop Handoffs from all AI Agents:

1. In Salesforce, remove the Email Domain Filters, and then the Email Relay.
2. In Ada, disable the toggle for each inbox on each AI Agent.

Remove the Email Relay first. When the last toggle on the primary AI Agent is disabled, Ada rejects every agent reply that Salesforce sends through the relay, including the replies of the other AI Agents. Without the relay, agent replies go out through Salesforce.

To remove the credentials from Ada, click Configure connection, then Clear configuration, and then Confirm. Clear configuration revokes the password at once. It also revokes every previous password that is still in its 5-minute window, and deletes the Other AI Agents list.

Troubleshooting

Use this table to fix common problems.

FAQs

Common questions about the Salesforce SMTP Connector.