---
title: "bulkSendMessage"
method: POST
path: "/v1/email-template/templates:bulkSendMessage"
tags: ["Email templates"]
---

# bulkSendMessage

`POST /v1/email-template/templates:bulkSendMessage`

Send emails to multiple recipients using a template

## Request body

- union
  - BulkSendMessageRequestWithQuery — It takes an entity query to derive recipient_ids, treating each as a separate mainEntity to construct individual messages. For e.g; if the query is provided as `_schema:opportunity AND status:PENDING`, then all the opportunity Ids with status PENDING are treated as separate mainEntity to construct individual messages.
    - `skip_creating_entities` boolean — When true, it lets to send only the email by skip creating the thread & message entities.
    - `complete_thread` boolean — Whether the thread is marked as Done immediately after sending the message
    - `email_template_id` string, required — ID of email template to use for sending bulk emails
    - `must_include_unsubscribe_link` boolean — If true then include unsubscribe link in the email body
    - `recipient_query` string, required — Entity search query to select recipients
    - `custom_variables` object[] — Custom variables to be replaced in the email template
      - `variable` string — Template Variable Name
      - `value` string — Value to be Replaced
  - BulkSendMessageRequest — It takes a list of entity ids, treating each as a separate mainEntity to construct individual messages. For e.g; if there some opportunityIds are provided, then each opportunityId is treated as a separate mainEntity to construct individual messages.
    - `skip_creating_entities` boolean — When true, it lets to send only the email by skip creating the thread & message entities.
    - `complete_thread` boolean — Whether the thread is marked as Done immediately after sending the message
    - `email_template_id` string, required — ID of email template to use for sending bulk emails
    - `must_include_unsubscribe_link` boolean — If true then include unsubscribe link in the email body
    - `recipient_ids` string[], required — List of entity ids to use as recipients
    - `custom_variables` object[] — Custom variables to be replaced in the email template
      - `variable` string — Template Variable Name
      - `value` string — Value to be Replaced
  - object
    - `job_id` string, required — Job ID for tracking the status of a bulk message request
    - `action` 'APPROVE' | 'APPROVE_WITH_CONSENT' | 'APPROVE_ALL' | 'CANCEL' — Trigger an APPROVE OR CANCEL action for the bulk message request. * APPROVE: Alias for APPROVE_WITH_CONSENT * APPROVE_WITH_CONSENT: Approve the bulk message request and send emails to queued recipients with consent * APPROVE_ALL: Approve the bulk message request and send emails to all queued recipients, including those without consent * CANCEL: Cancel the bulk message request

## Response `200`

Success

- BulkSendMessageJob
  - `org_id` string — Organization ID
  - `job_id` string, required — Job ID for tracking the status of bulk message action
  - `skip_creating_entities` boolean — When true, it lets to send only the email by skip creating the thread & message entities.
  - `complete_thread` boolean — Whether the thread is marked as Done immediately after sending the message
  - `status` 'PROCESSING' | 'QUEUEING' | 'APPROVAL' | 'SENDING' | 'SUCCESS' | 'FAILED' | 'CANCELLED', required — Status of the bulk message action * PROCESSING: Bulk message action is processing the request * QUEUEING: Bulk message action is generating emails to send in a queue * SENDING: Bulk message action is sending emails from the queue * SUCCESS: Bulk message action is completed successfully * FAILED: Bulk message action is failed * CANCELLED: Bulk message action was cancelled
  - `request` union, required
    - BulkSendMessageRequest — It takes a list of entity ids, treating each as a separate mainEntity to construct individual messages. For e.g; if there some opportunityIds are provided, then each opportunityId is treated as a separate mainEntity to construct individual messages.
      - `skip_creating_entities` boolean — When true, it lets to send only the email by skip creating the thread & message entities.
      - `complete_thread` boolean — Whether the thread is marked as Done immediately after sending the message
      - `email_template_id` string, required — ID of email template to use for sending bulk emails
      - `must_include_unsubscribe_link` boolean — If true then include unsubscribe link in the email body
      - `recipient_ids` string[], required — List of entity ids to use as recipients
      - `custom_variables` object[] — Custom variables to be replaced in the email template
        - `variable` string — Template Variable Name
        - `value` string — Value to be Replaced
    - BulkSendMessageRequestWithQuery — It takes an entity query to derive recipient_ids, treating each as a separate mainEntity to construct individual messages. For e.g; if the query is provided as `_schema:opportunity AND status:PENDING`, then all the opportunity Ids with status PENDING are treated as separate mainEntity to construct individual messages.
      - `skip_creating_entities` boolean — When true, it lets to send only the email by skip creating the thread & message entities.
      - `complete_thread` boolean — Whether the thread is marked as Done immediately after sending the message
      - `email_template_id` string, required — ID of email template to use for sending bulk emails
      - `must_include_unsubscribe_link` boolean — If true then include unsubscribe link in the email body
      - `recipient_query` string, required — Entity search query to select recipients
      - `custom_variables` object[] — Custom variables to be replaced in the email template
        - `variable` string — Template Variable Name
        - `value` string — Value to be Replaced
  - `created_by` string — User ID who created the bulk message action
  - `created_at` string, date-time — Time when the bulk message action was created
  - `updated_at` string, date-time — Time when the bulk message action was last updated
  - `approved_at` string, date-time — Time when the bulk message action was last approved
  - `approve_action` 'APPROVE_WITH_CONSENT' | 'APPROVE_ALL' — Type of approval action for the bulk message request. * APPROVE_WITH_CONSENT: Approve the bulk message request and send emails to queued recipients with consent * APPROVE_ALL: Approve the bulk message request and send emails to all queued recipients, including those without consent
  - `task_token` string — Task token to approve or cancel the bulk message action
  - `total_queued` integer — Total number of emails generated and queued for sending
  - `queued` object[] — List of entity ids that are queued for sending
    - `entity_id` string, required — Recipient Entity ID
    - `email_to` string[], required — Recipient emails
    - `email_with_consent` string[], required — Recipient emails with consent
  - `sent` object[] — List of entity ids and message ids that were sent successfully
    - `entity_id` string, required — Recipient Entity ID
    - `message_id` string, required — Message ID
    - `email_to` string[]
  - `failed` object[] — List of entity ids that were skipped or failed
    - `entity_id` string, required — Recipient Entity ID
    - `error` string, required — Error message
    - `email_to` string[]

## Other responses

- `403` — Forbidden

---

[API](https://skmtc.dev/epilot/apis/email-template-api.md) · [All operations](https://skmtc.dev/epilot/apis/email-template-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/epilot/email-template-api/revisions/0c6165eaceb0/schema)