Merge and Send Email

Open in ChatGPT Open in ChatGPT to ask questions about this page
Open in Claude Open in Claude to ask questions about this page
Copy as MarkdownCopy this page as markdown to use with AI assistants
View as Markdown Open this page as markdown in a new tab

Merges data into a Zoho Writer document template and sends the merged output by email, either embedded directly in the email body or as a file attachment.


Email Send Limits: Each email supports up to 1,000 recipients within the organization or up to 250 external recipients (across recipient_email, cc_email, and bcc_email combined). Daily send limits are 10 emails on the free plan and 1,000 emails per day for paid Zoho app plans. The combined total size of the merged document, email body, and all attachments must not exceed 12 MB.


Merge Data: Provide exactly one of merge_data, merge_data_csv_content, merge_data_json_content, merge_data_csv_url, merge_data_json_url, or record_id.

Endpoints

OAuth Scope

ZohoWriter.documentEditor.ALLZohoWriter.merge.ALLWorkDrive.files.ALLCopied!

Request Example

cURL
cURL
Deluge
Copied!
curl --request POST \
  --url https://www.zohoapis.com/writer/api/v1/documents/a1b2c3d4e5f6g7h8i9/merge/email \
  --header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \
  --header 'content-type: multipart/form-data' \
  -F 'output_settings={
  "format": "pdf",
  "password": "S3cur3P@ss"
}' \
  -F 'recipient_email=john.doe@zylker.com' \
  -F 'subject=Invoice 1042 - Action Required' \
  -F 'merge_data={
  "data": [
    {
      "customer_name": "John Miller",
      "customer_email_address": "john.miller@zylker.com",
      "invoice_number": "INV-2026-045",
      "items": [
        {
          "items.item_code": "SKU-1001",
          "items.item_name": "Aria Smartwatch S2",
          "items.item_images": [
            "https://workdrive.zoho.com/external/sample-image-id-1/download?directDownload=True",
            "https://workdrive.zoho.com/external/sample-image-id-2/download?directDownload=True"
          ],
          "items.item_replacement": "Yes"
        }
      ]
    }
  ]
}' \
  -F 'merge_data_csv_content=@file_path' \
  -F 'merge_data_json_content=@file_path' \
  -F 'merge_data_csv_url=https://zylker.com/merge-data.csv' \
  -F 'merge_data_json_url=https://zylker.com/merge-data.json' \
  -F 'record_id=4876000000123456' \
  -F 'cc_email=manager@zylker.com,accounts@zylker.com' \
  -F 'bcc_email=audit@zylker.com' \
  -F 'message=Please find your invoice attached. Contact us if you have any questions.' \
  -F 'from_email=billing@zylker.com' \
  -F 'from_name=Billing Team' \
  -F 'replyto_email=support@zylker.com' \
  -F 'attachment_name=invoice_john_doe' \
  -F 'common_attachments=@file_path' \
  -F 'unique_attachments=[
  {
    "type": "field",
    "field_id": "invoice_url"
  }
]' \
  -F 'sign_service_name=docusign' \
  -F 'test_mode=true'

Path Parameters

document_idstring(Required)

The unique identifier of the Zoho Writer document template.

Request Body

multipart/form-data
output_settingsJSON Object(Required)

Controls the delivery mode, file format, and access protection of the merged document.

Hide Sub-Attributes
formatstring(Required)

Set to inline to embed the merged document directly in the email body. Any other value sends the merged document as an email attachment in that format; use pdfform to preserve fillable form fields in the output PDF.

Allowed Values :
Show Values
inlineCopied!
pdfCopied!
pdfformCopied!
docxCopied!
Copied!Copy all as JSON Array
passwordstring(Optional)

An optional password for the merged document attachment. Applicable when format is not inline.

Maximum Length :100100Copied!
restricted_accessJSON Object(Optional)

Applies permission-based restrictions to the merged document. Applicable only when format is pdf; ignored for other formats. When present, both password and permissions are required.

Hide Sub-Attributes
passwordstring(Required)

The password required to override the applied document restrictions.

Maximum Length :255255Copied!
permissionsarray(Required)

The list of actions to restrict in the merged document. document.copy restricts copying content, document.print restricts printing, document.edit restricts editing, and document.fill restricts filling form fields. Any action not listed remains unrestricted.

recipient_emailstring(Required)

Comma-separated list of recipient email addresses. A maximum of 10 addresses is supported.

subjectstring(Required)

The subject line of the outgoing email.

Maximum Length :250250Copied!
merge_dataJSON Object(Optional)

Inline merge data as a JSON object. Must contain a data key whose value is a JSON array of records, with each record being a key-value map that matches the template's merge fields. For a subform field, use the subform's name as the key, mapped to an array of row objects; each row's keys follow the <subform_name>.<field_name> convention (e.g. items.item_code).

Hide Sub-Attributes
dataJSON Array(Required)

Array of records used to populate the template merge fields.

Hide Sub-Attributes
merge_data_csv_contentbinary(Optional)

A CSV file uploaded in the request body, up to 2 MB. Each row represents one merge record. Supported formats: csv.

merge_data_json_contentbinary(Optional)

A JSON file uploaded in the request body, up to 2 MB. Must contain an array of merge records. Supported formats: json.

merge_data_csv_urluri(Optional)

A publicly accessible URL pointing to a CSV file of merge records, up to 2 MB. Supported formats: csv.

merge_data_json_urluri(Optional)

A publicly accessible URL pointing to a JSON file of merge records, up to 2 MB. Supported formats: json.

record_idstring(Optional)

A record identifier from Zoho CRM, Zoho Creator, or Bigin. When provided, the API fetches merge data internally from the respective service. Cannot be combined with any other merge data parameter.

Maximum Length :2525Copied!
cc_emailstring(Optional)

Comma-separated list of CC recipient email addresses. A maximum of 10 addresses is supported.

bcc_emailstring(Optional)

Comma-separated list of BCC recipient email addresses. A maximum of 10 addresses is supported.

messagestring(Optional)

The body text of the email that accompanies the merged document attachment. Applicable when output_settings.format is not inline.

Maximum Length :100000100000Copied!
from_emailemail(Optional)

The sender's email address. If omitted, or if no from address is configured in the template's mail merge settings, the authenticated user's email address is used.

Maximum Length :100100Copied!
from_namestring(Optional)

The display name shown as the sender. Defaults to the display name associated with the authenticated Zoho email account.

Maximum Length :100100Copied!
replyto_emailemail(Optional)

The email address to which recipient replies are directed.

Maximum Length :100100Copied!
attachment_namestring(Optional)

A custom filename for the attached merged document, without a file extension. The appropriate extension is appended automatically based on the format set in output_settings. Applicable when output_settings.format is not inline.

Maximum Length :255255Copied!
common_attachmentsarray(Optional)

One or more files to attach to every email in the merge run.
Attachment limits vary by the Zoho app where the merge is configured:
Zoho Writer and Zoho CRM — up to 20 files per send, each up to 10 MB
Zoho Recruit — up to 10 files, each up to 10 MB
Zoho People — up to 10 files, each up to 5 MB
Supported formats: docx, doc, rtf, pdf, zip, html, txt, odt, epub, xml, ics, png, jpeg, gif, jpg.

unique_attachmentsJSON Array(Optional)

An array of objects that maps a distinct attachment to each recipient. Use type: field to map attachment URLs from a data field, or type: file to match files from a folder.
Attachment limits vary by the Zoho app where the merge is configured:
Zoho Writer and Zoho CRM — up to 20 attachments per recipient, each up to 10 MB
Zoho Recruit — up to 10 attachments, each up to 10 MB
Zoho People — up to 10 attachments, each up to 5 MB
Supported formats: pdf, docx, xlsx, xls, png, jpg, jpeg, psd, ical, ics, ifb.

Hide Sub-Attributes
typestring(Required)

The attachment mapping strategy to use.

Allowed Values :
Show Values
fieldCopied!
fileCopied!
Copied!Copy all as JSON Array
field_idstring(Optional)

The data field containing attachment URLs. Applicable when type is field.

folder_idstring(Optional)

The ID of the folder containing the attachment files. Applicable when type is file.

filename_filterJSON Object(Optional)

A filter to match files in the folder by name. Applicable when type is file.

Hide Sub-Attributes
typestring(Required)

The match strategy for the filename filter.

Allowed Values :
Show Values
startswithCopied!
startswithignorecaseCopied!
containsCopied!
containsignorecaseCopied!
doesnotcontainsCopied!
doesnotcontainsignorecaseCopied!
isCopied!
isignorecaseCopied!
endswithCopied!
endswithignorecaseCopied!
Copied!Copy all as JSON Array
valuestring(Required)

The value to match against the filename.

sign_service_namestring(Optional)

The third-party e-signature service to which the merged PDF is uploaded for signing. Applicable only when output_settings.format is pdf.

Allowed Values :
Show Values
adobesignCopied!
docusignCopied!
Copied!Copy all as JSON Array
test_modeboolean(Optional)

When true, the merge runs without consuming credit points. The output document will include a watermark. Limited to 50 merges per day per organization.

Body Parameters

Copied!
// Note: payload contains multiple type attributes

// type: object
output_settings = {
  "format": "pdf",
  "password": "S3cur3P@ss"
}

// type: string
recipient_email = john.doe@zylker.com

// type: string
subject = Invoice 1042 - Action Required

// type: object
merge_data = {
  "data": [
    {
      "customer_name": "John Miller",
      "customer_email_address": "john.miller@zylker.com",
      "invoice_number": "INV-2026-045",
      "items": [
        {
          "items.item_code": "SKU-1001",
          "items.item_name": "Aria Smartwatch S2",
          "items.item_images": [
            "https://workdrive.zoho.com/external/sample-image-id-1/download?directDownload=True",
            "https://workdrive.zoho.com/external/sample-image-id-2/download?directDownload=True"
          ],
          "items.item_replacement": "Yes"
        }
      ]
    }
  ]
}

// type: file
merge_data_csv_content = <file>

// type: file
merge_data_json_content = <file>

// type: string(uri)
merge_data_csv_url = https://zylker.com/merge-data.csv

// type: string(uri)
merge_data_json_url = https://zylker.com/merge-data.json

// type: string
record_id = 4876000000123456

// type: string
cc_email = manager@zylker.com,accounts@zylker.com

// type: string
bcc_email = audit@zylker.com

// type: string
message = Please find your invoice attached. Contact us if you have any questions.

// type: string(email)
from_email = billing@zylker.com

// type: string
from_name = Billing Team

// type: string(email)
replyto_email = support@zylker.com

// type: string
attachment_name = invoice_john_doe

// type: array[file]
common_attachments = [
  "<file>"
]

// type: array
unique_attachments = [
  {
    "type": "field",
    "field_id": "invoice_url"
  }
]

// type: string
sign_service_name = docusign

// type: boolean
test_mode = true
Show full

Response Example

200
Copied!
  {
    "merge_report_data_url": "https://writer.zoho.com/writer/api/v1/merge/job/0tq5n465132106580437abe99b6f56f2b0c85/data",
    "merge_report_url": "https://writer.zoho.com/writer/v1/mailmerge/job/0tq5n465132106580437abe99b6f56f2b0c85",
    "records": [
      {
        "data": {
          "name": "Amelia",
          "email": "amelia@zylker.com"
        },
        "download_link": "https://writer.zoho.com/writer/api/v1/documents/a1b2c3d4e5f6g7h8i9/merge/download/gas3hfnkju456mndhjku987b",
        "status": "inprogress"
      }
    ]
  }
                
Show full