> This page is for version Generative (default).
> For other versions, use one of these documentation indexes:
> - Generative (default): https://developers.ada.cx/generative/llms.txt
> - Scripted: https://developers.ada.cx/scripted/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.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 a customer over Ada's email channel, providing context for their inquiry. Your AI agent can only start conversations using the default Ada provided email, or email addresses you've set up in your bring your own domain settings.

Reference: https://developers.ada.cx/reference/email-conversations/create-email-conversation

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, 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.
- `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

## 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.

## 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 <token>",
    "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 <token>', '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 <token>")
	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 <token>'
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<String> response = Unirest.post("https://example.ada.support/api/v2/conversations/email/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Firstname Lastname\",\n  \"subject\": \"Email subject\",\n  \"reply_to\": \"user@mail.com\"\n}")
  .asString();
```

```php 
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->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 <token>',
    '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 <token>");
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 <token>",
  "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()
```