---
title: "Batch create scheduled messages"
method: POST
path: "/messages/batch/create"
tags: ["Messages"]
---

# Batch create scheduled messages

`POST /messages/batch/create`

## Request

- Base URL: `https://api.100hires.com/v2`
- URL: `https://api.100hires.com/v2/messages/batch/create`
- Auth: HTTP bearer

Creates up to 100 scheduled messages in one request. Each item specifies its own `candidate_id` and message payload. Items are processed independently — one failure does not stop others. Per-candidate RBAC is enforced for each item.

## Request body

- BatchCreateMessagesRequest
  - `messages` object[], required: Array of message payloads to create (max 100).
    - `candidate_id` integer, required: Target candidate ID for this message.
    - `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`

Batch results with per-item success or error

- BatchCreateMessagesResponse
  - `results` BatchCreateMessagesResultItem[], required: Array of per-message results with success or error details.
    - `index` integer, required: Zero-based index of this item in the request array.
    - `candidate_id` integer, nullable, required: Candidate ID from the request. Null if not provided.
    - `data` 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.
    - `error` object: Structured error object on failure. Present only when the item failed. Same format as top-level API errors.
      - `name` string
      - `message` string
      - `code` integer
      - `status` integer
      - `validation_errors` object

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `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)