---
title: "candidate.addEmailMessage"
method: POST
path: "/candidate.addEmailMessage"
tags: ["Candidate"]
---

# candidate.addEmailMessage

`POST /candidate.addEmailMessage`

Attaches an existing email message (e.g. fetched from a partner provider) to a candidate.

**Requires the [`candidatesWrite`](authentication#permissions-candidateaddemailmessage) permission.**

## Request body

- CandidateAddEmailMessageRequest
  - `candidateId` string, uuid, required — The candidate to attach this email to
  - `emailProviderEmailId` string, required — Unique identifier for this message in the partner system. Must be unique per API key.
  - `subject` string, required — The email subject line
  - `from` string, required — The sender email address
  - `to` string, required — The recipient email address
  - `body` string, required — The html body of the email
  - `userId` string, uuid, nullable — The Ashby user ID to associate with this email. Defaults to the API key user.
  - `sentAt` string, nullable — When the email was sent. Defaults to the current time.
  - `cc` string, nullable — CC recipients
  - `messageUrl` string, nullable — URL to view the message in the partner application
  - `messageIdHeader` string, nullable — RFC 5322 message identifier
  - `threadId` string, nullable — Thread identifier to group this message with others. Defaults to emailProviderEmailId.
  - `isPrivate` boolean, nullable — Whether the email should be marked as private. Private emails require "Allow access to non-offer private fields?" API key permission to create and view. Defaults to false.

## Response `200`

Responses from the candidate.addEmailMessage endpoint

- union
  - CandidateAddEmailMessageSuccessResponse
    - `success` true, required
    - `results` EmailMessage, required
      - `id` string, uuid, required — The unique id of the email in Ashby
      - `candidateId` string, uuid, required — The candidate this email is attached to
      - `emailProviderEmailId` string, required — The unique identifier for this message in the partner system
      - `subject` string, required — The email subject line
      - `from` string, required — The sender email address
      - `to` string, required — The recipient email address
      - `body` string, nullable, required — The body of the email. Can be HTML or plain text
      - `sentAt` string, required — When the email was sent
      - `cc` string, nullable, required — CC recipients
      - `messageUrl` string, nullable, required — URL to view the message in the partner application
      - `messageIdHeader` string, nullable, required — RFC 5322 Message-ID header value
      - `threadId` string, required — Thread identifier grouping this message with others
      - `isPrivate` boolean, required — Whether the email is marked as private
      - `userIsSender` boolean, required — Whether the associated user is the sender (true) or recipient (false)
  - ErrorResponse
    - `success` false, required
    - `errors` ErrorDetail[], required
      - `message` string, required
      - `parameter` string

---

[API](https://skmtc.net/ashbyhq/apis/ashby-api.md) · [All operations](https://skmtc.net/ashbyhq/apis/ashby-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ashbyhq/ashby-api/revisions/778b919dc743/schema)