Attachment

Purpose

To send the merge document as attachment with a message in the body of the email.

Prerequisites

Before using this API, you need to access the merge template once from Zoho Writer's UI.

Steps to access the template in Zoho Writer

  1. Open Zoho Writer dashboard and select your preferred merge template.

  2. Click the hamburger menu -> Automate tab.

Quick Reference

PropertyValue
MethodPOST
Request URLhttps://{zohoapis_domain}/writer/api/v1/documents/{document_id}/merge/email
ScopesZohoWriter.documentEditor.ALL, ZohoWriter.merge.ALL, ZohoPC.files.ALL, WorkDrive.files.ALL
Rate LimitSee Writer API throttle limits

Parameters

Path Parameters

ParameterData TypeDescription
document_idStringSpecify a unique id for the writer document.

Body Parameters

ParameterData TypeDescription
Mandatory Parameters
output_settings{
"format": "pdf | pdfform | docx",
"password": "**",
"restricted_access":
{
"password": "",
"permissions": ["document.copy", "document.print", "document.edit", "document.fill"]
}
}

format - Specify the format in which the merged document needs to attached and sent.
Supported formats are pdf, pdfform and docx.


password(optional) - Specify a password if you would like to protect the merged document.
Maximum characters allowed: Upto 100 characters


restricted_access(optional) - password: Specify the password to enable or override the restricted permissions. Maximum characters allowed: Upto 100 characters 

permissions: Specify the actions that needs to be restricted in merged document.
Note: If this param is passed, then both password and permissions fields are mandatory.

subjectStringSpecify a subject to the email.
messageStringSpecify a message related to the attachment in the email.
recipient_emailStringSpecify the receiver's email id.
Merge Data — pass data using any one of the below formats
merge_dataJSONObjectPass a String value through 'data' key as JSON Array.
merge_data_csv_contentFileProvide the required csv content in your API request body.
merge_data_json_contentFileProvide the required json content in your API request body.
merge_data_csv_urlurlProvide the required csv url in your API request body.
merge_data_json_urlurlProvide the required json url in your API request body.
record_idStringInstead of using merge_data, you can pass the record_id and we will fetch the data internally.
Note: This is applicable only for Zoho CRM, Creator and Bigin templates.
Maximum length allowed: 25
Optional Parameters
cc_emailStringSpecify the Cc email id's (maximum upto 10) separated by comma.
bcc_emailStringSpecify the BCC email id's (maximum upto 10) separated by comma.
attachment_nameStringSpecify a name (without extension) for the merged document (pdf or docx) that is attached in the mail.
For example: "attachment_name = test" (extension will be automatically added according to the attached file format)
from_emailStringSpecify the from address using which the merge document needs to be sent.
If the 'from_email' parameter is not passed (OR) the 'from address' is not configured in the Template's Mail Merge Settings, we will go ahead and use the Email ID of the current user who is sending the mail ( by default ).
common_attachmentsFileSpecify the attachments that needs to be sent to all the recipients in common.
Maximum files allowed: 10 to 20 attachments (depending on the integration). Refer here.
Maximum file size allowed: 5 to 10 MB (depending on the integration). Refer here.
Supported file formats: docx / doc / rtf / pdf / zip / html / txt / png / jpeg / gif / jpg
unique_attachments

"type": "field", 

"field_id": <field_id> 

}
(OR)

"type": "file", 

"folder_id":123456789, 

"filename_filter": 

"type":"startswith/contains/is/endswith",

 "value": <field_id> 

}, 

},

.... 

]

Using this param, you can send a different or unique attachment to each recipient.
It can be sent in either one of the following ways;
1. Field Containing Attachment URLs - If you want to map the attachment file paths to a spreadsheet/CSV file.
(OR)
2. Folder Containing Attachments - If you want to map the attachment file paths to a particular folder.
Maximum files allowed: 10 to 20 attachments (depending on the integration). Refer here.
Maximum file size allowed: 5 to 10 MB (depending on the integration). Refer here.
Supported file formats: pdf, docx, xlsx, xls, png, jpg, jpeg, psd, ical, ics, icalender, ifb
from_nameStringSpecify the display name for your 'from address'. If this param is not passed, by default, we will take the display name of your Zoho email account.
replyto_emailStringSpecify the 'Reply to' email address to which you want the recipients response email to be sent.
sign_service_nameStringThis param needs to be configured when you would like to upload the merged document with signer fields to a third party sign service.
Possible values: adobesign and docusign
Note: This param can be used only when the 'output_format' param value is configured as pdf.
test_modeBoolean (true/false)Using this param, you can test the Merge APIs without consuming any credit points. The output file will contain a watermark as it is used only for testing purpose.
Test mode limit: 50 merges/day for an org.

permissions

Permission Key NameDescription
document.copyCopy content from the merged document
document.printPrint the merged document
document.editEdit the merged document
document.fillTo fill form fields in the merged document

Notes

  • You need to access the template once before sending an API request. You need not access the template every time before you send an API request.
  • We have also provided an option to configure the values for all the above parameters while creating the document itself.
  • If you have saved the merge settings earlier by configuring the parameter values, then we will get those values (by default) if you miss to pass the parameters while sending the API request.
  • Optional parameters are not supported in mergeAndSend deluge task. To make use of them, you need to use the invokeURL task with this API.
  • For possible errors, refer to error codes.

Curl

Sample Request

Copiedcurl -X POST "https://www.zohoapis.com/writer/api/v1/documents/{document_id}/merge/email" \
  -H "Authorization: Zoho-oauthtoken <ACCESS_TOKEN>" \
  -F "output_settings={\"format\":\"pdf\"}" \
  -F "subject=Invoice - Please Review" \
  -F "message=Please find the merged document attached." \
  -F "recipient_email=amelia@zylker.com" \
  -F "merge_data={\"data\":[{\"name\":\"Amelia\",\"email\":\"amelia@zylker.com\"},{\"name\":\"Johnson\",\"email\":\"johnson@zylker.com\"}]}"

Sample Response

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": "{url}",
            "status": "inprogress"
        },
        {
            "data": {
                           "name": "John",
                           "email": "john@zylker.com"
                         },
            "download_link": "{url}",
            "status": "inprogress"
        }
    ],
}

// When 'merge_report_data_url' is invoked, you will receive the below response;

{
    "records": [
        {
            "data": {
                           "name": “Amelia”,
                           "email": “amelia@zylker.com"
            },
            "status": "completed"
        },
        {
            "data": {
                           "name": “John”,
                           "email": “john@zylker.com"
            },
            "status": "inprogress"
        }
    ],
    "status": "inprogress"
}

Deluge

Snippet 1

Copieddata = Map(); 
data.put("InvoiceNo","12345"); 
data.put("InvoiceDate","27 May 2022"); 
data.put("InvoiceAmount","$100");
param = Map(); 
param.put("message", "Reg Invoice \n Please find your invoice attached."); 
param.put("subject", "Invoice Data"); 
param.put("merge_data", {"data":data}); 
param.put("output_settings", {"format":pdf}); 
param.put("recipient_email","amelia@zylker.com"); 
param.put("cc_email", "john@zylker.com");    //optional
param.put("bcc_email", "kim@zylker.com");   //optional
param.put("from_email", "jackson@zylker.com");    //optional
param.put("attachment_name", "Invoice");    //optional
param.put("from_name", "Jack");    //optional
param.put("replyto_email", "jerry@zylker.com");    //optional
invokeurl 
[ 
url: "https://www.zohoapis.com/writer/api/v1/documents/fbsa6360a78f53f564dfa9b4a1e79febed569/merge/email" 
type: post 
parameters: param 
connection: "<connection_name>" 
];

Sample Response

Copied{
    "merge_report_data_url": "https://writer.zoho.com/writer/api/v1/merge/job/fbsa6360a78f53f564dfa9b4a1e79febed569/data",
    "merge_report_url": "https://writer.zoho.com/writer/v1/mailmerge/job/fbsa6360a78f53f564dfa9b4a1e79febed569",
    "records": [
        {
            "InvoiceNo": "12345",
            "InvoiceDate": "27 May 2022",
            "InvoiceAmount": "$100",
            "download_link": "{url}",
            "status": "inprogress"
        }
    ],
}

Snippet 2 - Merge and Email with common attachments

Copiedmessage = "Hello \n Team";
fields = invokeurl
[
	url :"https://www.zohoapis.com/writer/api/v1/documents/eb4kob4cf6***61119eb9/fields"
	type :GET
	connection:"<connection_name>"
];
data = Map();
data.put("InvoiceNo","12345"); 
data.put("InvoiceDate","27 May 2022"); 
data.put("InvoiceAmount","$100");
dataMap = Map();
dataMap = {"data":data};
downloadFile = invokeurl
[
	url :"https://homepages.inf.ed.ac.uk/neilb/TestWordDoc.doc"
	type :GET
];
info downloadFile;
commonAttachmentFile1 = invokeurl
[
	url :"https://example.com/download/publicdocument"
	type :GET
];
info commonAttachmentFile1;
commonAttachmentFile2 = invokeurl
[
	url :"https://example.com/download/publicdocument"
	type :GET
];
info commonAttachmentFile2;
downloadFile.setParamName("common_attachments");
commonAttachmentFile2.setParamName("common_attachments");
paramList = list();
paramMap1 = {"paramName":"common_attachments","content":commonAttachmentFile1};
paramMap8 = {"paramName":"common_attachments1","content":commonAttachmentFile2};
paramMap2 = {"paramName":"merge_data","content":dataMap.toString(),"stringPart":"true","encodingType":"UTF-8"};
paramMap3 = {"paramName":"subject","content":"Invoice data","stringPart":"true"};
paramMap4 = {"paramName":"message","content":"Reg Invoice \n Please find your invoice attached.","stringPart":"true"};
paramMap5 = {"paramName":"attachment_name","content":"attachment_name","stringPart":"true"};
paramMap6 = {"paramName":"output_format","content":"pdf","stringPart":"true"};
paramMap7 = {"paramName":"recipient_email","content":"amelia@gmail.com","stringPart":"true"};
paramList.add(paramMap1);
paramList.add(paramMap2);
paramList.add(paramMap3);
paramList.add(paramMap4);
paramList.add(paramMap5);
paramList.add(paramMap6);
paramList.add(paramMap7);
paramList.add(paramMap8);
merge = invokeurl
[
	url :"https://www.zohoapis.com/writer/api/v1/documents/eb4kob4cf6***61119eb9/merge/email"
	type :POST
	files:paramList
	connection:"<connection_name>"
];
info merge;

Sample Response

Copied{
    "merge_report_data_url": "https://writer.zoho.com/writer/api/v1/merge/job/fbsa6360a78f53f564dfa9b4a1e79febed569/data",
    "merge_report_url": "https://writer.zoho.com/writer/v1/mailmerge/job/fbsa6360a78f53f564dfa9b4a1e79febed569",
    "records": [
        {
            "InvoiceNo": "12345",
            "InvoiceDate": "27 May 2022",
            "InvoiceAmount": "$100",
            "download_link": "{url}",
            "status": "inprogress"
        }
    ],
}

Snippet 3 - Merge and Email Task (Attachment Type)

Copieddata = {"data":{"InvoiceNo":"12345","InvoiceDate":"27 May 2022","InvoiceAmt":"$100"}};
mergedata = Map();
mergedata.put("merge_data", data);
mergedata.put("subject", "Invoice data");     
mergedata.put("message", "Please find your invoice in the attachment");    
zoho.writer.mergeAndSend("fbsa6360a78f53f564dfa9b4a1e79febed569", "docx", "amelia@zylker.com", mergedata, "<connection_name>");    //outputformat -> pdf/docx

Sample Response

Copied{
    "merge_report_data_url": "https://writer.zoho.com/writer/api/v1/merge/job/fbsa6360a78f53f564dfa9b4a1e79febed569/data",
    "merge_report_url": "https://writer.zoho.com/writer/v1/mailmerge/job/fbsa6360a78f53f564dfa9b4a1e79febed569",
    "records": [
        {
	    "InvoiceNo": "12345",
            "InvoiceDate": "27 May 2022",
            "InvoiceAmount": "$100",
            "download_link": "{url}",
            "status": "inprogress"
        }
    ],
}