Choose where you’d like to start

Merge And Send V2

Description
Syntax
Example
Usecase
Response Format
Related Links

Note: Applicable to all services except Zoho Creator

Description

The zoho.writer.v2.mergeAndSend task merges your document and sends it via email. The merged documents can be sent inline (in the body of an email) or as an attachment to the email. This task is based on the Zoho Writer Merge and Email API.

Note: To use this API for CRM and People templates you need to add the following scopes and include the id in the merge_data.
CRM: ZohoCRM.settings.emails.ALL
People: zohopeople.automation.ALL

Sample merge data:

merge_data = {data: [{"name": "Amelia", "email": "amelia@zylker.com", "id": "1234567789"}]}

To use the 'from address alias' of Zoho Mail service as 'from address' for this API, you need to include VirtualOffice.settings.ALL scope as well.

Syntax

 <response> = zoho.writer.v2.mergeAndSend(<document_id>, <merge_detail>, <output_settings>, <optional_settings>,  <connection>)

Params	Data type	Description
<response>	KEY-VALUE	The response returned by Zoho Writer. It provides the merged document's details, such as the merge data and the status of the merge.
<document_id>	TEXT	The ID of the document to be merged and sent as an email. The document ID can be obtained from the URL of the document that needs to be merged and sent as an email. The URL is formatted as follows: https://writer.zoho.com/writer/open/<document_id>
<merge_detail>	KEY-VALUE	Specify how your input for the merge will be. It can be a JSON, CSV file, or a URL.
<output_settings>	KEY-VALUE	The output parameters you can send to merge and send as an email according to your preference.
<option_settings>	KEY-VALUE	The optional parameters you can send to merge and send as an email according to your preference.
<connection>	TEXT	The connection's link name. Note: To prevent new AuthToken generation and ensure new integration tasks (tasks created after the deadline specified in the post) work as expected, a Zoho OAuth connection with appropriate scopes is mandatory. Existing integration tasks will continue to work, with or without the connections parameter, until you manually delete the AuthToken from Zoho Accounts. Add relevant scopes from the Zoho Writer API when creating the connection Refer to this post for a list of Zoho services that support the Connections page. Learn more about connections

You can provide the <merge_detail> in any one of the following formats:

Key	Value	Description
merge_data	JSONObject	Pass a string value through the data key as a JSON Array. Sample json: { "data": [ { "First_Name": "Amelia", "Email": "amelia@zylker.com", "Phone": 9876543210, "Address": "132, My Street,\nKingston,\nNew York 12401.", "Invoices": [ { "Invoices.Invoice_Number": "10001", "Invoices.Date": "07/10/2024" } ], "Products": [ { "Products.Product_Code": "129548", "Products.Product_Image": "<Publicly downloadable image url>", "Products.Item_Quantity": 2, "Products.Item_Price": "$ 10" } ] } ]
merge_data_csv_content	File	Provide the required CSV content in your API request body.
merge_data_json_content	File	Provide the required JSON content in your API request body.
merge_data_csv_url	URL	Provide the required CSV URL in your API request body.
merge_data_json_url	URL	Provide the required JSON URL in your API request body.

Output_settings

Parameter	Type	Description
output_format	string	Specify the format in which the merged document needs to be attached and sent. Supported formats include PDF, PDFFORM, and DOCX.
subject	string	Specify a subject for the email.
message	string	Specify a message related to the attachment in the email.
recipient_email	String	Specify the receiver's email address.

<optional_settings>

Parameter	Data type	Description
cc_email	String	Specify the CC email addresses' (maximum of 10) separated by comma.
bcc_email	String	Specify the BCC email addresses' (maximum of 10) separated by comma.
password	String	Specify a password if you would like to protect the merged document.
attachment_name	String	Specify a name (without the file format) for the merged document (PDF or DOCX) to be sent as an email attachment. For example: "attachment_name = test" (extension will be automatically added according to the attached file format)
from_email	String	Specify the from email address used to send the merged document. If the 'from_email' parameter is not passed (OR) the 'from address' is not configured in the template's mail merge settings, then the current user's email address will be used.
common_attachments	File	Specify the attachments that need to be sent to all the recipients in common. Maximum files allowed: 3 Maximum file size allowed: 3MB 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 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 WorkDrive folder.
from_name	String	Specify the display name for your from address. If this param is not passed, the display name of your Zoho email account will be used.
replyto_email	String	Specify the 'Reply to' email addresses to which you want the recipient's response email to be sent.
sign_service_name	String	This 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_mode	Boolean (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 purposes. Test mode limit: 50 merges/day for an org.

4. Examples

The following script merges a document and sends it in an email to a user.

document_id = "rrxzk387b5db17dd343f5335cd440";
CustomerInfo = Map();
CustomerInfo.put("First_Name", "Amelia");
CustomerInfo.put("Email", "amelia@zylker.com");
CustomerInfo.put("Phone", 9876543210);
CustomerInfo.put("Address", "132, My Street,\nKingston,\nNew York 12401.");
invoicesList = List();
invoiceDetails = Map();
invoiceDetails.put("Invoices.Invoice_Number", "10001");
invoiceDetails.put("Invoices.Date", "07/10/2024");
invoicesList.add(invoiceDetails);
CustomerInfo.put("Invoices", invoicesList);
productList = list();
productDetails = Map();
productDetails.put("Products.Product_Code", "129548");
productDetails.put("Products.Product_Image", <Publicly downloadable image url>);
productDetails.put("Products.Item_Quantity", 2);
productDetails.put("Products.Item_Price", "$ 10");
CustomerInfo.put("Products", productList);
merge_detail = Map();
merge_detail.put("merge_data",{"data":CustomerInfo});
output_settings = Map();
output_settings.put("output_format","pdf");
output_settings.put("subject","Invoice Details");
output_settings.put("message","Please find your invoice attached.");
output_settings.put("recipient_email","amelia@zylker.com");
downloadFile = invokeurl
[
url :"<https://example.com/download/publicdocument>"
type :GET
];
downloadFile1 = invokeurl
[
url :"<https://example.com/download/publicdocument>"
type :GET
];
optional_settings = Map();
optional_settings.put("password","12345");
optional_settings.put("attachment_name","attachmenttesting");
optional_settings.put("common_attachments",{downloadFile,downloadFile1});                
response = zoho.writer.v2.mergeAndSend(document_id,merge_detail,output_settings,optional_settings,"writer_connection");
info response;

5. Use case

Scenario: Say the HR team is generating offer letters for employees in Zoho People who need to be onboarded with your organization. The team inputs each employee's name, designation, salary, and work mode, then sends it as an email attachment to the employees with the help of a custom function.

records = zoho.people.getRecordByID("Candidate",peopleID);
document_id = "34ulekd9w3403klwori093wjlwer34fl32er"
merge_detail = Map();
merge_detail.put("215519000000255007_215519000000255051",records.get("First_Name"));
merge_detail.put("215519000000255007_215519000001098655",records.get("Posting_Title"));
merge_detail.put("215519000000255007_215519000001098721",records.get("Job_Posting_Location"));
merge_detail.put("215519000000255007_215519000001098637",records.get("Date_of_Joining"));
merge_detail.put("215519000000255007_215519000000451001",records.get("Tentative_Joining_Date"));
merge_detail.put("Id",peopleID);
data_map = Map();
data_map.put("data",merge_detail);
merge_data = Map();
merge_data.put("merge_data",data_map);
output_settings = Map();
output_settings.put("output_format","pdf");
output_settings.put("subject","");
output_settings.put("message","Kindly read all the details in the properly...");
output_settings.put("recipient_email",records.get("Email_ID"));
optional_settings = Map();
optional_settings.put("password","12345");
optional_settings.put("attachment_name","attachmenttesting");
response = zoho.writer.v2.mergeAndSend(document_id,merge_detail,output_settings,optional_settings,"writer_connection");
info response;

Response Format

Success Response:

The success response will be returned in the following format:

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

Deluge

The fastest programming language for developers