> This page is for API, version 2026-01-01 (Stable) (default).
> For other versions, use one of these documentation indexes:
> - 2026-01-01 (Stable) (default): https://docs.deel.wtf/api/stable/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.deel.wtf/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.deel.wtf/_mcp/server.

# Create an email draft to a candidate

POST https://api.letsdeel.com/rest/ats/candidates/{candidate_id}/email-drafts
Content-Type: application/json

Saves an email to a candidate as a draft of the authenticated user, without sending it, and returns it rendered exactly as sending it would produce. Use it to stage an email for the user to confirm, then send it with the email draft sends endpoint.

 **Token scopes**: `ats:write`, `worker:write`

 **Beta**: this version requires the `X-Beta: true` request header and its contract may change before it is promoted to stable. It is scheduled to become stable on 2027-01-29.

Reference: https://docs.deel.wtf/api/reference/endpoints/ats/create-candidate-email-draft-v-2026-10-29

## Authentication

- `Authorization` header (bearer token, required) — ## Authentication The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail. ```curl curl -X GET 'https://api.deel.training/rest/v2/contracts' \ -H 'Authorization: Bearer YOUR-TOKEN-HERE' ``` [Learn more about authentication](/api/authentication)
- `Authorization` header (bearer token, required) — Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/

## Servers

- `https://api.letsdeel.com/rest` (Production, default)
- `https://api-staging.letsdeel.com/rest` (Demo)

## Request

### Path parameters

- `candidate_id` (string, required) — ID of the candidate the draft is addressed to

### Headers

- `X-Beta` (enum, required, default: true) — Opts in to the beta version of this endpoint. Must be `true`.
  - Allowed values: `true`

### Body (application/json)

This endpoint expects an object.

- `data` (AtsCandidatesCandidateIdEmailDraftsPostRequestBodyContentApplicationJsonSchemaData, required)

## Response

### 201

The new draft, rendered as it would be sent

- `data` (AtsCandidatesCandidateIdEmailDraftsPostResponsesContentApplicationJsonSchemaData, required) — The new draft, rendered as it would be sent

## Errors

### 400 Bad Request Error

Operation failed.

- `errors` (list of AtsCandidatesCandidateIdEmailDraftsPostResponsesContentApplicationJsonSchemaErrorsItems, required) — List of error objects

### 401 Unauthorized Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

### 403 Forbidden Error

Forbidden. ATS is not enabled for this organization or insufficient permissions.

- `errors` (list of AtsCandidatesCandidateIdEmailDraftsPostResponsesContentApplicationJsonSchemaErrorsItems, required) — List of error objects

### 404 Not Found Error

Not found, or not visible to the authenticated user. The two cases are indistinguishable.

- `errors` (list of AtsCandidatesCandidateIdEmailDraftsPostResponsesContentApplicationJsonSchemaErrorsItems, required) — List of error objects

### 500 Internal Server Error

Operation failed.

- `errors` (list of AtsCandidatesCandidateIdEmailDraftsPostResponsesContentApplicationJsonSchemaErrorsItems, required) — List of error objects

## Types

### AtsCandidatesCandidateIdEmailDraftsPostRequestBodyContentApplicationJsonSchemaData

- `to` (list of string, required) — Primary recipients. Each entry is an email address, or a dynamic recipient resolved when the draft is rendered: CANDIDATE, HIRING_MEMBERS, INTERVIEWERS, RECRUITERS or HIRING_MANAGERS.
- `body` (string, required) — The rich text HTML body. May contain placeholders, filled when the draft is rendered.
- `subject` (string, required) — The subject. May contain placeholders such as $\{\{candidate.firstName}}, filled when the draft is rendered.
- `cc` (list of string, optional) — CC recipients. Each entry is an email address, or a dynamic recipient resolved when the draft is rendered: CANDIDATE, HIRING_MEMBERS, INTERVIEWERS, RECRUITERS or HIRING_MANAGERS.
- `bcc` (list of string, optional) — BCC recipients. Each entry is an email address, or a dynamic recipient resolved when the draft is rendered: CANDIDATE, HIRING_MEMBERS, INTERVIEWERS, RECRUITERS or HIRING_MANAGERS.
- `application_id` (string, optional) — The application of the candidate the draft is about. Required unless the caller is an ATS admin, since access to emails is granted per job.

### AtsCandidatesCandidateIdEmailDraftsPostResponsesContentApplicationJsonSchemaData

The new draft, rendered as it would be sent

- `cc` (list of string, required) — CC recipients, resolved to addresses
- `id` (string, required) — The unique identifier of the email draft
- `to` (list of string, required) — Primary recipients, with dynamic recipients such as the candidate resolved to addresses
- `bcc` (list of string, required) — BCC recipients, resolved to addresses
- `body` (string, required) — The rich text HTML body with its placeholders filled in
- `from` (string, required) — The sender the email goes out as: the author's connected mailbox when they have one, otherwise the organization's sender
- `subject` (string, required) — The subject with its placeholders filled in
- `updated_at` (string, required) — The timestamp when the draft was last changed
- `attachments` (list of AtsCandidatesCandidateIdEmailDraftsPostResponsesContentApplicationJsonSchemaDataAttachmentsItems, required) — Files attached to the draft
- `application_id` (string, required, nullable) — The application the draft is about, or null for a draft about the candidate only
- `unresolved_placeholders` (list of string, required) — Placeholders left unfilled in the subject or body. The draft cannot be sent while any remain.

### AtsCandidatesCandidateIdEmailDraftsPostResponsesContentApplicationJsonSchemaErrorsItems

- `code` (string, required) — Machine-readable error code
- `message` (string, required) — Human-readable error message
- `field` (string, optional) — Request field related to the error, if applicable

### ApiErrorRequest

- `method` (string, optional) — The HTTP method of the failed request
- `url` (string, optional) — The relative URL of the failed request
- `status` (double, optional) — The status code of the response
- `api_req_id` (string, optional) — The request ID of the failed request
- `docs` (string, optional) — A link to the official documentation for the requested endpoint resource
- `source` (string, optional) — The source handler which produced the returned error
- `code` (double, optional) — The code of the source handler which produced the returned error

### ApiError

- `message` (string, optional) — A description of the returned error
- `path` (string, optional) — The JSON path where input validation failed

### AtsCandidatesCandidateIdEmailDraftsPostResponsesContentApplicationJsonSchemaDataAttachmentsItems

- `id` (string, required) — The unique identifier of the attachment
- `file_name` (string, required) — The name of the attached file

## Examples

**Request**

```json
{
  "data": {
    "to": [
      "CANDIDATE"
    ],
    "body": "<p>Hi ${{candidate.firstName}}, thanks for your time today.</p>",
    "subject": "Next steps for the Data Engineer role"
  }
}
```

**Response**

```json
{
  "data": {
    "cc": [
      "ada.lovelace@example.com"
    ],
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to": [
      "ada.lovelace@example.com"
    ],
    "bcc": [
      "ada.lovelace@example.com"
    ],
    "body": "<p>Hi Ada, thanks for your time today.</p>",
    "from": "Grace Hopper <grace.hopper@acme.com>",
    "subject": "Next steps for the Data Engineer role",
    "updated_at": "2026-10-23T10:30:00.000Z",
    "attachments": [
      {
        "id": "c2d3e4f5-a6b7-8901-bcde-f12345678901",
        "file_name": "interview-guide.pdf"
      }
    ],
    "application_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "unresolved_placeholders": [
      "${{interview.bookingLink}}"
    ]
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.letsdeel.com/rest/ats/candidates/faac641e-a484-4875-aed5-bfcb0a0691a0/email-drafts"

payload = { "data": {
        "to": ["CANDIDATE"],
        "body": "<p>Hi ${{candidate.firstName}}, thanks for your time today.</p>",
        "subject": "Next steps for the Data Engineer role"
    } }
headers = {
    "X-Beta": "true",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.letsdeel.com/rest/ats/candidates/faac641e-a484-4875-aed5-bfcb0a0691a0/email-drafts';
const options = {
  method: 'POST',
  headers: {
    'X-Beta': 'true',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"data":{"to":["CANDIDATE"],"body":"<p>Hi ${{candidate.firstName}}, thanks for your time today.</p>","subject":"Next steps for the Data Engineer role"}}'
};

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://api.letsdeel.com/rest/ats/candidates/faac641e-a484-4875-aed5-bfcb0a0691a0/email-drafts"

	payload := strings.NewReader("{\n  \"data\": {\n    \"to\": [\n      \"CANDIDATE\"\n    ],\n    \"body\": \"<p>Hi ${{candidate.firstName}}, thanks for your time today.</p>\",\n    \"subject\": \"Next steps for the Data Engineer role\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Beta", "true")
	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://api.letsdeel.com/rest/ats/candidates/faac641e-a484-4875-aed5-bfcb0a0691a0/email-drafts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Beta"] = 'true'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"to\": [\n      \"CANDIDATE\"\n    ],\n    \"body\": \"<p>Hi ${{candidate.firstName}}, thanks for your time today.</p>\",\n    \"subject\": \"Next steps for the Data Engineer role\"\n  }\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://api.letsdeel.com/rest/ats/candidates/faac641e-a484-4875-aed5-bfcb0a0691a0/email-drafts")
  .header("X-Beta", "true")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"to\": [\n      \"CANDIDATE\"\n    ],\n    \"body\": \"<p>Hi ${{candidate.firstName}}, thanks for your time today.</p>\",\n    \"subject\": \"Next steps for the Data Engineer role\"\n  }\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.letsdeel.com/rest/ats/candidates/faac641e-a484-4875-aed5-bfcb0a0691a0/email-drafts', [
  'body' => '{
  "data": {
    "to": [
      "CANDIDATE"
    ],
    "body": "<p>Hi ${{candidate.firstName}}, thanks for your time today.</p>",
    "subject": "Next steps for the Data Engineer role"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'X-Beta' => 'true',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.letsdeel.com/rest/ats/candidates/faac641e-a484-4875-aed5-bfcb0a0691a0/email-drafts");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Beta", "true");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"data\": {\n    \"to\": [\n      \"CANDIDATE\"\n    ],\n    \"body\": \"<p>Hi ${{candidate.firstName}}, thanks for your time today.</p>\",\n    \"subject\": \"Next steps for the Data Engineer role\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Beta": "true",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["data": [
    "to": ["CANDIDATE"],
    "body": "<p>Hi ${{candidate.firstName}}, thanks for your time today.</p>",
    "subject": "Next steps for the Data Engineer role"
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/ats/candidates/faac641e-a484-4875-aed5-bfcb0a0691a0/email-drafts")! 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()
```