Send Mail Merge

Mail Merge

The Mail Merge function helps you to create customized documents such as forms, envelopes, letters, etc. Mail merge templates allow you to use CRM variables(merge fields) and create merged documents with the correct data from these variables. You can use these mail merge templates to send personalized emails, letters etc to other users without manually typing the information for every user. For more details, refer to Managing Mail Merge Templates.

Purpose

Use the send mail merge API to use a mail merge template and send emails to users. You can also attach files either as inline images or separate attachments with the email through the API.

Endpoints

Request Details

Request URL

{api-domain}/crm/{version}/{module_API_name}/{record_id}/actions/send_mail_merge

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope=ZohoCRM.settings.mailmerge.CREATE,ZohoWriter.documentEditor.ALL,ZohoWriter.merge.ALL,ZohoCRM.settings.emails.ALL

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v5/Leads/554023000003128089/actions/send_mail_merge"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@input.json"
-X POST
Input JSON
  • mail_merge_templateJSON object, mandatory
    • name string, mandatory

      The name of the mail merge template you want to use.

  • from_addressJSON object, optional

    The email ID you want to use to send emails from. This email address must be the one of the org-verified email addresses or the current user's email ID.

  • to_addressJSON array, optional

    The email ID you want to use to send emails to.

  • cc_emailJSON array, optional

    The details of the email or the mail merge field you want to include in the email's cc. The keys are same as the ones in the "from_address" JSON object.

  • bcc_emailJSON array, optional

    The details of the email or the mail merge field you want to include in the email's bcc. The keys are same as the ones in the "from_address" JSON object.

  • subjectstring, optional

    The subject line of the email.

  • attachment_namestring, optional

    The name of the attachment you want to include in the email.

  • typestring, mandatory when you want to send an attachment

    The attachment type you want to include in the email. The possible values are inline to send the attachment as an inline image, and attachment to send the the file separately.

Note

  • The values for "from_address", "to_address", "cc_email", "bcc-email", and "subject" will be taken from the mail merge template. If you want to override the values in the template, you must specify the values of these fields in the input body.

Sample Input

Copied{
    "send_mail_merge": [
        {
            "mail_merge_template": {
                "name": "mailmergename"
            },
            "from_address": {
                "type": "email",
                "value": "p.boyle@gmail.com"
            },
            "to_address": [
                {
                    "type": "email",
                    "value": "smith@gmail.com"
                },
                {
                    "type": "email",
                    "value": "john@gmail.com"
                }
            ],
            "subject": "Hi there",
            "cc_email": [
                {
                    "type": "email",
                    "value": "brie.c@gmail.com"
                }
            ],
            "bcc_email": [
                {
                    "type": "email",
                    "value": "ceo.zylker@gmail.com"
                }
            ],
            "type": "attachment",
            "attachment_name": "testdocument",
            "message": "Big Deal"
        }
    ]
}

Possible Errors

  • EXPECTED_FIELD_MISSINGHTTP 400

    You have not specified the name in the "mail_merge_template" key.
    Resolution: You must specify the name of the mail merge template in the "mail_merge_template" key.

  • INVALID_DATAHTTP 400

    You have specified an incorrect name of the mail merge template.
    Resolution: Provide the right name of the mail merge template.

  • INVALID_EMAILHTTP 400

    You have specified an incorrect email address for one or more of the "from_address", "to_address", "cc_email", and "bcc_email" fields.
    Resolution: The email IDs must belong to only the org-approved CRM users or the current user.

  • DEPENDENT_SERVICE_ERRORHTTP 400

    You are not authorized to use the email ID in the "from_address".
    Resolution: Contact your system administrator.

  • INVALID_DATAHTTP 400

    You have specified an incorrect record ID in the URL.
    Resolution: Provide the right record ID in the URL. Use the Get Records API to get the record ID.

  • INVALID_MODULEHTTP 400

    The module name is invalid.
    Resolution: Use the Modules API to get the API name of the module.

  • MANDATORY_NOT_FOUNDHTTP 400

    You have not specified one or more mandatory keys in the request.
    Resolution: Refer to the Input JSON section for the list of mandatory keys.

  • INVALID_REQUEST_METHODHTTP 400

    The HTTP request method is invalid.
    Resolution: The HTTP request method for this API is POST.

  • INTERNAL_ERRORHTTP 500

    Unhandled exception in server.
    Resolution: Contact the support team at support@zohocrm.com.

Sample Response

Copied{
    "code": "SUCCESS",
    "details": {
        "report_link": "https://writer.zoho.com/report_link"
    },
    "message": "mail merge action initiated successfully",
    "status": "success"
}