If you want to integrate AI Email (formerly Conversational Email) with a non-Salesforce CRM, or configure a custom workflow between AI Email (AIE) and your existing systems, you can do so using our API.
The page covers common API scenarios. For the latest version of our API documents, refer to the API documentation. There are also other API endpoints and webhooks available. Refer to the API v2 documentation.
Create a lead
You can create a lead in AIE that is not enrolled into any campaigns. No email is sent to the lead.
After a new lead is created in AIE, you can find the lead under the Leads tab.
To create a new lead, refer to Create a lead.
Create a lead with a lead owner
To create a lead with a lead owner, please first make sure that the lead owner is defined as a handoff rep in the app. We will only accept lead owners who are pre-populated in the app as a handoff rep. Otherwise, the lead owner will be discarded and the lead will be handed over on a round robin basis in the event of a qualification.
To populate your lead_owner object in your POST request, you will need to retrieve all sales reps by searching and matching on your end based on the rep’s email address to retrieve the lead owner ID. You can then submit this in with your POST request.
Create a lead with custom attributes
To create a lead with custom attributes, please first make sure that the custom attribute is created in the app.
To populate your custom_attribute_value object in your POST request, you will need to retrieve all custom attributes by searching and matching on your end based on the attribute name to retrieve the custom attribute ID. You can then submit this in with your POST request.
Enroll a lead
You can enroll a lead to a campaign in AIE, and start a conversation with the lead.
After a lead is enrolled, you can find the lead under the Leads tab or Campaign Details page.
To enroll a lead, refer to Create a lead.
Submit an enrollment
To enroll a lead, you will need to:
Make sure the lead is first created in the app. After it is created, you will retrieve the lead ID from the response of your lead creation API call.
Make sure the campaign you wish to enroll to is first created in the app. You will need to retrieve all campaigns, do a search and match on your end based on the campaign name to retrieve the campaign ID. You can then submit this in with your POST request.
Enrollment restrictions
A lead cannot be enrolled if it:
Still has an ongoing conversation.
Has been enrolled in the same topic in the past.
Has been enrolled in the same campaign in the past.
Retrieve a conversation
To retrieve a conversation, refer to Show a conversation.
Conversation statuses
A conversation can either be ongoing or completed. This is determined by the status on the conversation. This is reflected under conversation.status in your GET request response:
Ongoing conversation statuses: Pending lead response, Pending AI email agent response
Completed conversation statuses: Bounced, Human Review, Not Interested, Qualified, Stopped Responding, Unresponsive, Cancelled
When a conversation is completed, it will have a terminal conversation status. These statuses are representative of the final state of the conversation, with a couple of exceptions:
If the human review owner marks a human review task as Completed, the status can change from Human Review to Qualified, Stopped Responding, Cancelled, or Not Interested.
If a lead subsequently responds after the final email has already gone out, the status can change from Unresponsive or Stopped Responding to other statuses.
Multiple leads in a conversation
In a conversation where your lead refers the AI email agent to their colleague, or CCs in other people, there will be multiple leads in a conversation.
All leads within a conversation will have the same conversation status, as the status belongs to the conversation and not the individual leads.
leads is an array in the response which returns all leads in the conversation in no particular order.
is_main refers to the main lead when the conversation is completed, which is assumed to be the last person who replied to the AI email agent. If marked as true, this lead is the To recipient. If false, this lead is either a CC or BCC recipient.
is_original refers to the original lead contacted.
Delete a lead
To delete a lead, refer to Delete a lead.
The delete endpoint is for soft delete. Soft delete archives the lead in the app, and the lead profile is no longer accessible. The conversation will still be present. When you create the lead again, the previous copy of the lead will be restored.
By default, the API prevents you from deleting a lead that has an ongoing conversation. You can override this behavior (delete the lead and cancel his/her ongoing conversation) by including the force property in the JSON body.
Hard delete a lead
If you are testing the import/enrollment endpoints and need to start from a clean slate, you will need to hard delete the lead.
Hard delete permanently deletes the lead from our database. All conversation and lead details will be irreversibly lost, and stats attributed to it will be reverted.
Hard delete is currently not available over API or within the app. For details contact your Customer Support Manager. Alternatively, you can test the endpoints on the same email multiple times like this: example+1@company.com,example+2@company.com
Multiple leads in a conversation
If you delete a lead in a conversation with multiple leads:
Soft-deleting a lead/all leads will not delete the conversation.
Hard deleting one lead will not delete the conversation, but hard deleting all leads will delete the conversation.
Cancel a conversation
To cancel a conversation, refer to Cancel a conversation.
A lead is not allowed to have more than one ongoing conversation at once.
After you cancel a conversation, the conversation status is marked as Cancelled in the app and the lead is now available to enroll in a new conversation.
Restrictions of API v2
The API v2 does not allow:
Update a lead
Hard delete a lead
Return emails in a conversation object
Create multiple leads at once
Enroll multiple leads at once
Cancel multiple conversations at once
Delete multiple leads at once