> 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. # Start a conversation over Ada's email channel POST https://example.ada.support/api/v2/conversations/email/ Content-Type: application/json Start a conversation with an end user over Ada's native Email channel, providing context for their inquiry. **This endpoint is exclusive to the native Email channel and cannot be used for custom channels.** Your AI Agent can start conversations only with the default Ada-provided email address, or with email addresses you’ve configured through Bring Your Own Domain (BYOD) settings. To include files the customer attached to their inquiry, send the request as `multipart/form-data`. Put the JSON request body in the `data` part and add one `attachments` part per file. A request can include up to 10 attachments and 30 MB in total. Attachments follow the attachment handling setting of the inbox the AI Agent replies from, the same as attachments on an email sent to the AI Agent. The AI Agent reads at most 3 images per request, and only on inboxes set to reply using the attachment. It keeps every other file and passes it to a human agent on handoff. Reference: https://docs.ada.cx/reference/conversations/create-email-conversation ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects an EmailConversationCreateRequest. - `name` (string, required) — The customer's full name - `subject` (string, required) — The subject of the customer's inquiry; used as the subject for the AI Agent's reply - `reply_to` (string, required) — The customer's email address - `text` (string, optional) — The customer's inquiry, limited to 10 KB - `reply_as` (string, optional) — The company email address you want to use to reply to the customer. Defaults to the Ada provided email address. - `cc` (list of string, optional) — The email addresses in the email's CC field - `metadata` (EmailConversationCreateRequestMetadata, optional) — Any metadata associated with the conversation, up to 4 KB. All metadata passed through this field will appear as metavariables in your dashboard. ## Response ### 200 Conversation Created - `conversation_id` (string, optional) — The Ada-generated conversation id ## Errors ### 400 Bad Request Error Bad Request - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 401 Unauthorized Error Unauthorized - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 413 Content Too Large Error Content Too Large - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 422 Unprocessable Entity Error Unprocessable Content - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 429 Too Many Requests Error Too Many Requests - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 500 Internal Server Error Internal Server Error - `errors` (list of ErrorsErrorsItems, required) — A list of errors ## Types ### EmailConversationCreateRequestMetadata Any metadata associated with the conversation, up to 4 KB. All metadata passed through this field will appear as metavariables in your dashboard. ### ErrorsErrorsItems - `type` (string, required) — The error type - `message` (string, required) — The error message - `details` (string, optional, nullable) — Extra information about the error ## Examples **Request** ```json { "name": "Firstname Lastname", "subject": "Email subject", "reply_to": "user@mail.com" } ``` **Response** ```json { "conversation_id": "5df263b7db5a7e6ea03fae9b" } ``` **SDK Code** ```python import requests url = "https://example.ada.support/api/v2/conversations/email/" payload = { "name": "Firstname Lastname", "subject": "Email subject", "reply_to": "user@mail.com" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://example.ada.support/api/v2/conversations/email/'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"Firstname Lastname","subject":"Email subject","reply_to":"user@mail.com"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://example.ada.support/api/v2/conversations/email/" payload := strings.NewReader("{\n \"name\": \"Firstname Lastname\",\n \"subject\": \"Email subject\",\n \"reply_to\": \"user@mail.com\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://example.ada.support/api/v2/conversations/email/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"Firstname Lastname\",\n \"subject\": \"Email subject\",\n \"reply_to\": \"user@mail.com\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://example.ada.support/api/v2/conversations/email/") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"Firstname Lastname\",\n \"subject\": \"Email subject\",\n \"reply_to\": \"user@mail.com\"\n}") .asString(); ``` ```php request('POST', 'https://example.ada.support/api/v2/conversations/email/', [ 'body' => '{ "name": "Firstname Lastname", "subject": "Email subject", "reply_to": "user@mail.com" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://example.ada.support/api/v2/conversations/email/"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"Firstname Lastname\",\n \"subject\": \"Email subject\",\n \"reply_to\": \"user@mail.com\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "Firstname Lastname", "subject": "Email subject", "reply_to": "user@mail.com" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://example.ada.support/api/v2/conversations/email/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```