--- title: "AI Email API Overview" slug: "6sense-conversational-email-overview-of-api" description: "Integrate AI Email with your systems, create leads, enroll in campaigns, and manage conversations using our comprehensive API documentation." tags: ["AI Email", "AI Email Integration", "API Documentation", "Lead Management"] updated: 2025-08-01T21:38:15Z published: 2025-08-01T21:38:15Z canonical: "support.6sense.com/6sense-conversational-email-overview-of-api" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.6sense.com/llms.txt > Use this file to discover all available pages before exploring further. # AI Email API Overview 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](https://docs.saleswhale.com/). There are also other API endpoints and [webhooks](https://docs.saleswhale.com/#webhook) available. Refer to the [API v2 documentation](http://docs.saleswhale.com/#v2). ## 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](http://docs.saleswhale.com/#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](/v1/docs/add-and-manage-sales-reps-for-ce). 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](http://docs.saleswhale.com/#list-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](/v1/docs/add-contact-and-account-custom-fields). To populate your `custom_attribute_value` object in your POST request, you will need to [retrieve all custom attributes](http://docs.saleswhale.com/#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](http://docs.saleswhale.com/#create-a-lead). ### Submit an enrollment To enroll a lead, you will need to: - Make sure [the lead is first created in the app](http://docs.saleswhale.com/#create-a-lead). 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](/v1/docs/create-a-campaign-in-ce). You will need to [retrieve all campaigns](http://docs.saleswhale.com/#list-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](http://docs.saleswhale.com/#show-a-conversation). ### Conversation statuses A conversation can either be ongoing or completed. This is determined by the [status on the conversation](/v1/docs/ce-conversation-statuses). 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](/v1/docs/handle-ce-human-review-tasks), 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](http://docs.saleswhale.com/#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,](mailto:example+1@company.com,)[example+2@company.com](mailto: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](http://docs.saleswhale.com/#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 Customer Relationship Management, an external platform used to manage your relationships and interactions with potential customers and clients. Application Programming Interface; a set of rules that allows different software applications to communicate with each other. A virtual email user that sends email on your behalf. Each AI email agent is associated with a single email inbox account on the configured email provider. Formerly called "AI inbox" or "AI Assistant".