Kaizen #97 - Email APIs

Kaizen #97 - Email APIs

Howdy, tech wizards! Welcome back to another exciting post in our Kaizen series.  

This week, we will explore how to leverage the power of APIs to manage and interact with emails within the Zoho CRM platform.  

Consider you are the Manager of a technological company called Zylker Technologies, which uses Zoho CRM. You want to email a client using your organization's email ID and manage the reply emails within your CRM account. The first step in bringing your organization's email to your CRM account is IMAP/POP3 configuration.   

Email Configuration  

Zoho CRM supports email integration via Internet Messaging Access Protocol (IMAP) and Post Office Protocol 3 (POP3). These are email protocols that standardise the exchange of mails between the servers and clients. 

IMAP
POP3
IMAP keeps emails on the server and allows you to access them from multiple devices.
POP3 downloads emails to a local device. You can either keep a copy of them on the server or remove them to manage the storage of your web server.
It synchronises email actions (read, delete, move) across all devices, providing a consistent email experience.
It does not synchronise actions across devices, making it challenging to manage emails on multiple devices.
IMAP is ideal for users who need to access their emails from different devices or prefer centralised email management.
POP3 is suitable for users who prefer offline email access and want to save storage space on the server.


Following steps will help you to integrate your email with Zoho CRM.  
  • Navigate to Setup > Channels > Email > Email Configuration to choose your email service.
  • Under choose the protocol to configure select IMAP or POP integration based on your email service provider and business needs. 


Once you configure the IMAP/POP3 mail, the SalesInbox tab will sync and display all your mails.  Now that we have everything ready, we will take a look at how to email your clients using APIs. 

Emailing a Client using API  

Request URL : {api-domain}/crm/{version}/{module_api_name}/{record_id}/actions/send_mail
Request Method : POST
Scope : ZohoCRM.send_mail.{module_name}.CREATE  (or) ZohoCRM.send_mail.all.CREATE
Supported Modules : Leads, Contacts, Deals, Accounts, Sales Orders, Purchase Orders, Invoices, Quotes, Cases, and Custom. 
Request Body : 

{
  "data": [
    {
      "from": {
        "user_name": "Patricia Boyle",
        "email": "zylkertechnologies@zylker.com"
      },
      "to": [
        {
          "user_name": "Christopher Maclead",
          "email": "christopher@rangoni.com"
        }
      ],
      "cc": [
        {
          "user_name": "Jack Williams",
          "email": "jack.williams@zylker.com"
        }
      ],
      "org_email": true,
      "consent_email": true,
      "mail_format": "html",
      "subject": "Test Email",
      "content": "<h3><span style=\"background-color: rgb(254, 255, 102)\">New Product Launch is on Aug 15,2023!</span></h3><h3><span style=\"background-color: rgb(254, 255, 102)\">REGARDS,</span></h3><div><span style=\"background-color: rgb(254, 255, 102)\">AZ</span></div><div><span style=\"background-color: rgb(254, 255, 102)\">ADMIN</span></div>"
    }
  ]
}

You can also use other request JSON keys mentioned in this document to send an email. When you email a client, the email automatically gets added to the related lists of the record specified in the request url. 

There are a few other conditions that you need to check while emailing a client using the Send Mail API. 

(i) from Addresses 

As you are sending the email from your CRM account, you should use only the IMAP/POP3 configured email IDs. To know the configured email IDs of your CRM account, make a GET API call for the list of allowed "from" addresses . 

Request URL : {api-domain}/crm/{version}/settings/emails/actions/from_addresses
Request Method : GET
Scope : ZohoCRM.settings.emails.READ
Response : 

{
  "from_addresses": [
    {
      "default": true,
      "user_name": "Patricia Boyle",
      "type": "primary",
      "email": "patricia.boyle@zylker.com"
    },
    {
      "user_name": "Jack Williams",
      "id": "5545974000000434026",
      "type": "pop",
      "email": "jack.williams@zylker.com"
    },
    {
      "user_name": "Patricia Boyle",
      "id": "5545974000001222005",
      "type": "org_email",
      "email": "zylkertechnologies@zylker.com"
    }
  ]
}

  • The API lists the email addresses configured in the IMAP/POP3 accounts ( imap and pop ), the email ID used to sign in the CRM account ( primary ) and the configured organization email addresses ( org_email ). You can use any of these email addresses to email the clients.  
  • The default:true denotes the default from email address configured for UI usage. This will auto populate the from email address while emailing a client via UI. Anyhow, you have to specify the from address in the send mail API. 
  • If the email with type:org_email in this API response is used as a from address of the send mail API, the org_email key in the same send mail request body has to be marked as true . 

(ii) Modules that are Applicable for using Templates/Inventory Templates

Consider you want to send welcome emails to all of your new leads. You cannot manually draft a welcome email every time Zylker gets a new lead. Instead you can create a welcome email template and insert it to the draft. 

To insert template/inventory templates while emailing a record, make a Metadata API call of the particular module and check for the key inventory_template_supported .

  • inventory_template_supported: true states you can add inventory templates in the body of the mail.
  • inventory_template_supported: false states you can add only the email templates and not the inventory templates in the body of the mail.  

In our case, you want to send welcome emails to leads. So, let us check this key for the module, Leads . 



Since inventory_template_supported: false for Leads, we can add only email templates to its records. Below is the request body of the send mail API with welcome template,  

{
    "data": [
        {
            "from": {
                "user_name": "Patricia Boyle",
                "email": "zylkertechnologies@zylker.com"
            },
            "to": [
                {
                    "user_name": "Carissa Kidman",
                    "email": "carissa@goodknits.com"
                },
                {
                    "user_name": "Felix Hirpara",
                    "email": "felixhirpara@chapman.com"
                },
                {
                    "user_name": "Kayleigh Lace",
                    "email": "kayleigh@printingdimensions.com"
                }
            ],
            "cc": [
                {
                    "user_name": "Jack Williams",
                    "email": "jack.williams@zylker.com"
                }
            ],
            "mail_format": "html",
            "subject": "Welcome to Zylker",
            "template": {
                "id": "5545974000000640001"
            }
        }
    ]
}

Associate an Email with a Record         

Though Zoho CRM supports email Integration, sometimes you may want to import emails from a different email service provider and add them to certain records. You can use this API for adding only particular emails to a record without completely synchronising or integrating the email service provider with Zoho CRM. 

Request URL : {api-domain}/crm/{version}/{module}/{record_id}/actions/associate_email
Request Method : POST
Scope : ZohoCRM.modules.emails.ALL  (or) ZohoCRM.modules.{module}.ALL
Supported Modules : Leads, Contacts, Quotes, Invoices, Sales_Orders, Purchase_Orders, Deals, Accounts and Custom.
Request Body :

{
  "Emails": [
    {
      "from": {
        "user_name": "Patricia Boyle",
        "email": "zylkertechnologies@zylker.com"
      },
      "to": [
        {
          "user_name": "Christopher Maclead",
          "email": "christopher@rangoni.com"
        }
      ],
      "cc": [
        {
          "user_name": "Jack Williams",
          "email": "jack.williams@zylker.com"
        }
      ],
      "subject": "Test Email",
      "content": "<h3><span style=\"background-color: rgb(254, 255, 102)\">New Product Launch is on Aug 15,2023!</span></h3><h3><span style=\"background-color: rgb(254, 255, 102)\">REGARDS,</span></h3><div><span style=\"background-color: rgb(254, 255, 102)\">AZ</span></div><div><span style=\"background-color: rgb(254, 255, 102)\">ADMIN</span></div>",
      "mail_format": "html",
      "date_time": "2023-07-27T22:24:12+05:30",
      "sent": true,
      "linked_record": {
        "id": "5545974000002858070",
        "name": "Mega Deal",
        "module": {
          "api_name": "Potentials",
          "id": "5545974000000002181"
        }
      },
      "original_message_id": "000146"
    }
  ]
}

This sample input JSON is for linking an email to a record in Deals.

The original_message_id key is the unique ID provided by any email service provider after sending an email. To avoid adding an already existing email to a record, this unique ID has to be specified while adding an email to a record. 

Now as a manager, you may want to associate the sales reps' emails with the corresponding records they have handled. To achieve this, add the record owner's ID to the owner key in the request body. Only users with admin profile can perform this action.   

The API extends its horizon to associating emails with the inline images to a record. For this, you have to upload the image to Zoho File System using the Upload files to ZFS API . Ensure you specify the parameter "type":"inline" while uploading the inline images to the ZFS. 



The ID provided in the response of this API has to be specified in the content key of associate email to a record API as follows:  

"content": "<h3><span style=\"background-color: rgb(254, 255, 102)\">New Product Launch is on Aug 15,2023!</span></h3><h3><span style=\"background-color: rgb(254, 255, 102)\"><img class=\"ZCrmImage\" src=\"crm\/img_id:c5afdcdbe17cd7bcee305c1a23067169caf522cbf76ed9d1c9c06408b22888ee\"></span></h3><h3><span style=\"background-color: rgb(254, 255, 102)\">REGARDS,</span></h3><div><span style=\"background-color: rgb(254, 255, 102)\">AZ</span></div><div><span style=\"background-color: rgb(254, 255, 102)\">ADMIN</span></div>"

Zoho CRM also offers API support to fetch all the emails of a record , list the users with whom a record's emails are shared , and download email attachments and inline images . They help us to streamline email-related processes, enhance communication, and maximize the efficiency of email management. 

We hope you found this post useful and engaging! 

If you have any queries, feel free to drop them in the comments section below or reach out to us directly at support@zohocrm.com . We eagerly await your thoughts and feedback on this! 

Keep an eye out for more valuable insights on our developer space! 

Cheers! 





    Access your files securely from anywhere

        Zoho Developer Community

            Bootcamp
            Community
            Pricing
            Webinars
            What's New
            Integrations
            Contact Support
            Contact Sales

              Zoho Survey Resources
                Features
                Survey Templates
                Integrations
                Community
                iOS Mobile Surveys
                Pricing
                Android Mobile Surveys
                Insurvey Blogs
                Insight Blogs
                Tips & Tricks





                              Latest Feature Updates


                                  Zoho Desk Resources

                                  • Desk Community Learning Series


                                  • Digest


                                  • Functions


                                  • Meetups


                                  • Kbase


                                  • Resources


                                  • Glossary


                                  • Desk Marketplace


                                  • MVP Corner


                                  • Word of the Day




                                      Zoho Marketing Automation
                                        Zoho SalesIQ Resources


                                              Manage your brands on social media
                                              Access Zoho Social

                                                Zoho Pagesense Resources


                                                    Zoho TeamInbox Resources

                                                      Zoho DataPrep Resources



                                                        Zoho CRM Plus Resources

                                                          Zoho Books Resources


                                                            Zoho Subscriptions Resources

                                                              Zoho Projects Resources


                                                                Zoho Sprints Resources


                                                                  Qntrl Resources


                                                                    Zoho Creator Resources



                                                                        Zoho Campaigns Resources


                                                                          Zoho CRM Resources

                                                                          • CRM Community Learning Series

                                                                            CRM Community Learning Series


                                                                          • Kaizen

                                                                            Kaizen

                                                                          • Functions

                                                                            Functions

                                                                          • Meetups

                                                                            Meetups

                                                                          • Kbase

                                                                            Kbase

                                                                          • Resources

                                                                            Resources

                                                                          • Digest

                                                                            Digest

                                                                          • CRM Marketplace

                                                                            CRM Marketplace

                                                                          • MVP Corner

                                                                            MVP Corner





                                                                              Design. Discuss. Deliver.

                                                                              Create visually engaging stories with Zoho Show.

                                                                              Get Started Now