---
title: "replaceVariablesAsync"
method: POST
path: "/v1/email-template/templates:replaceAsync"
tags: ["Variables"]
---

# replaceVariablesAsync

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

This endpoint allows to initiate an asynchronous process in replacing the template details & generating the documents.
On initial request, a jobId and STARTED status are returned. Subsequent requests can use this jobId to poll for the resolved template.
If still processing, it returns the jobId and IN-PROGRESS status. Upon completion or failure, it returns the final template or a failure status with reason.

## Query parameters

- `job_id` string

## Request body

- object
  - `email_template_id` string
  - `variable_parameters` VariableParameters
    - `template_type` 'email' | 'document', required
    - `language` 'en' | 'de'
    - `main_entity_id` string — The main entity ID. Use main entity in order to use the variable without schema slug prefix - or just pass directly to other object ID.
    - `user_id` string — User ID
    - `custom_variables` object[] — Custom variables to be replaced in the email template
      - `variable` string — Template Variable Name
      - `value` string — Value to be Replaced
  - `must_include_unsubscribe_link` boolean — If true then include unsubscribe link in the email body
  - `skip_document_generation` boolean — If true then skip document generation. This is useful when you want to replace html variables only. Speeds up the process.

## Response `200`

Success

- AsyncEmailTemplateResponse
  - `job_id` string, required — Job ID of the email template that is requested to replace and generate docs
  - `status` 'STARTED' | 'PROCESSING' | 'SUCCESS' | 'FAILED', required
  - `message` string — Error message
  - `doc_progress_count` object — Progress count of the documents that are needed to generate
    - `total` number, required — Total count
    - `completed` number, required — Completed count
  - `result` object — Result of the email template that is replaced along with generated docs
    - `entity` EmailTemplateEntity
      - `_id` string, required — Entity ID
      - `_title` string, required — Entity title
      - `_org` string, required — Ivy Organization ID the entity belongs to
      - `_schema` string, required — URL-friendly identifier for the entity schema
      - `_tags` string[] — Entity tags
      - `_created_at` string, date-time, required — Created date
      - `_updated_at` string, date-time, required — Updated date
      - `_purpose` string[] — Entity Purposes
      - `_manifest` string[] — Manifest ID used to create/update the entity
      - `name` string, required — name
      - `brand_id` number, nullable — Brand ID. Equal 0 if available for All brands
      - `from` From
        - `name` string
        - `email` string, required
      - `to` To[] — To
        - `name` string
        - `email` string, required
      - `cc` To[] — Cc
        - `name` string
        - `email` string, required
      - `bcc` To[] — Bcc
        - `name` string
        - `email` string, required
      - `subject` string — Subject
      - `body` string — Body
      - `attachments` Attachment[], nullable — Email template attachments
        - `cid` string — Attachment ID
        - `filename` string, required — File name
        - `size` number, required — File size in bytes
        - `content_type` string, required — Content type
        - `url` string — URL to download the attachment.
        - `bucket` string, required — S3 bucket where file is stored
        - `object_key` string, required — S3 object apiKey
        - `inline` boolean — If true then this attachment should not be offered for download (at least not in the main attachments list).\ The usecase is CID embedded image (aka inline image).
        - `send_as_link` boolean — If true then this attachment is sent via link. The link is already inserted to email body by API caller. In this case, service doesn't process this attachment.
        - `type` string — File type such as Document template, Document,... Use for replace variables on document template
        - `copy_to_message` boolean — If true then this attachment is copied to the message and replaces corresponding one
      - `file` object
        - `$relation` object[] — Entity tags
      - `created_by` string — Created by
      - `updated_by` string — Updated by
      - `json_template` string — This field is used to store JSON templates. If this field is populated, then the Body html is derived from the JSON.
      - `backup` object — Snapshot of the legacy template body, taken when migrating to the email-builder format.
        - `body` string — Original HTML body before conversion to email-builder blocks.
        - `backed_up_at` string — ISO 8601 timestamp when the backup was created.
      - `converted_to_new_editor` boolean — True after the template has been converted from legacy HTML to the new email-builder format. Used by the UI to expose the "Revert to legacy HTML" action.
      - `system_template` boolean — If template is created by system (Double Opt-in, CMD invitation,...) then true, and some attributes can not be edited such as Name, To,... Remember to add default content of template to system_template enum for revert to original feature
      - `original_template_id` string, nullable — Set on a duplicated template to point at its source template id. Cleared after automations have been migrated via `migrateAutomationsForTemplate`.
    - `relations` object[]

## 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)