---
title: "Create scheduled message for candidate"
method: POST
path: "/candidates/{id}/messages"
tags: ["Messages"]
---

# Create scheduled message for candidate

`POST /candidates/{id}/messages`

## Request

- Base URL: `https://api.100hires.com/v2`
- URL: `https://api.100hires.com/v2/candidates/{id}/messages`
- Auth: HTTP bearer

Creates a candidate message through mailbox scheduler. If `scheduled_at` is omitted, the message is scheduled for 15 minutes after creation instead of being sent immediately.

## Path parameters

- `id` string, required

## Request body

- ScheduledEmailCreateRequest
  - `from_account_id` integer, nullable: Optional sending mail account ID. Use `GET /users/{user_id}/mail-accounts` to list available accounts for a user, or `GET /companies/mail-accounts` to list all accounts. If omitted, the API key owner's default mail account is used.
  - `to` string[], required: Primary recipient email addresses.
  - `cc` string[]: Carbon-copy recipient email addresses.
  - `bcc` string[]: Blind carbon-copy recipient email addresses.
  - `subject` string, required: Email subject line.
  - `body` string, required: Email body as HTML.
  - `scheduled_at` integer, nullable: Unix timestamp (seconds). If omitted, defaults to created time plus 900 seconds.
  - `application_id` integer, nullable: Optional application ID linked to this message.
  - `reply_to_email_id` integer, nullable: Optional mailbox message ID to reply to.
  - `send_in_new_thread` boolean: Whether to send the message as a new thread instead of replying in an existing thread.

## Response `200`

Created scheduled message

- ScheduledEmail
  - `type` 'mailbox', required: Message channel type for scheduler-backed message endpoints.
  - `message` MailboxMessage, required
    - `id` integer, required: Message ID.
    - `from` string, nullable, required: Sender address.
    - `to` string, required: Recipient address.
    - `cc` string, required: CC recipients.
    - `subject` string, required: Message subject.
    - `body` string: Message body content. Present only when `view=full` (default); omitted entirely when `view=summary` — message bodies can run into tens of KB.
    - `date` string, required: Message date.
    - `attachments` Attachment[]: Message attachments. Present only when `view=full` (default); omitted entirely when `view=summary`.
      - `uuid` string, uuid, required: Unique attachment identifier. Stable across API calls; use in referencing endpoints.
      - `url` string, uri, nullable, required: Absolute download URL (e.g. `https://api.100hires.com/v2/attachments/application/{uuid}/{file_name}`). Hit with `Authorization: Bearer <API_KEY>`.
      - `relative_time` string, required: Human-readable time since upload (e.g. `"2 days ago"`).
      - `file` AttachmentFile, required
        - `is_image` boolean, nullable, required: Whether the file is an image.
        - `orig_file_name` string, required: Original file name.
        - `file_ext` string, required: File extension.
        - `file_type` string, required: File type category.
        - `readable_size` string, required: Human-readable file size.
    - `schedule` union, required
      - ''
      - MailboxSchedule
        - `senderId` integer, nullable, required: Sender mail account ID.
        - `isForceSend` boolean, required: Whether forced to send immediately.
        - `isFailed` boolean, required: Whether send failed.
        - `scheduleSendError` string, nullable, required: Error message on failure.
        - `isScheduled` boolean, required: Whether currently scheduled.
        - `scheduledDay` string, required: Scheduled date.
        - `sendAt` integer, required: Scheduled send time.
        - `humanDatetime` string, required: Human-readable scheduled time.
        - `systemDatetime` string, required: System scheduled time.
    - `opensCount` integer, required: Number of times opened.
    - `opens` MailboxOpenEvent[], required: Array of open tracking events.
      - `label` string, required: Open event label.
    - `autoJobId` union, required
      - integer
      - string
    - `isNurtured` boolean, required: Whether sent via nurture campaign.

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `415`: Content-Type must be application/json
- `429`: Too many requests

---

[API](https://skmtc.dev/100hires/apis/100hires-api.md) · [All operations](https://skmtc.dev/100hires/apis/100hires-api/llms.txt) · [OpenAPI document](https://skmtc.dev/100hires/apis/100hires-api/revisions/e63e2d3115f7?raw)