Disclaimer: I’m not a professional coder!

Do you need to use Zoho Mail API?

Me too. It lets you do all sorts of things — like reading the complete header of an email, or forwarding an email with its attachments — which is what I wanted to do.

But setting up the API (application programming interface) took me hours.

It didn’t need to, but advice on this forum sent me in circles and, while the Knowledgebase probably has all the information, it’s not easy to determine which are the relevant bits. So…

       To use Zoho Mail API you need:

b) Up to three Zoho IDs — User, Organization, Account

c) Depending on what you want to do, additional IDs for emails, folders, etc

OAUTH TOKEN

The token validates you when you make an API call. There are various ways to create it.

The hard way: it’s possible to create an OAuth token via Developer Space but this requires lots of options to be chosen and the OAuth token needs to be frequently refreshed.

The easy way, at least for me, was via a custom function in filters — because it’s simple to do, the OAuth token you create isn’t time-limited, and creating a custom function is what I was trying to do anyway 

If you already have an OAuth token, great. If not, but have already created a custom function, jump to 4 below. Alternatively:

      1)    In Zoho Mail, go to settings/filters

      2)    Create a new filter and, under Actions, select ‘Custom Function’. Zoho help file here.

      3)    Click ‘Select Function’ and create a new function or use an existing one

      4)    Once the custom function is on screen, select ‘DRE Connectors’ (Deluge Runtime Environment) at the top right

      5)    Click ‘Create Connection’ and under ‘Default Services’ choose ‘Zoho OAuth’

      6)    ‘Connection Name’ can be anything you like. It’s the ‘Connection Link Name’ that you will use in your Deluge scripts.

      7)    Chose the ‘Scopes’ of your token. There are zillions of them and they determine what your script can and can’t do. The most basic might be ‘ZohoMail.messages.READ’. The API Guide Index lists every API command and, for each, details what scope you need e.g. the send an email page shows you’ll need the scope ZohoMail.messages.ALL or ZohoMail.messages.CREATE. (Sorry, I don’t know why you wouldn’t always choose the ‘ALL’ flavour.)

      8)    After you click ‘Create and Connect’ you should have a working OAuth token with a lowercase ‘link name’ that you can paste into your Deluge scripts.

GETTING THE RELEVANT IDS

You’ll see from the snippet above that this particular API needs your ‘accountId’ to work. Here’s how you get it (Why Zoho makes it so difficult, I don’t know!)

      1)    You can get all your relevant IDs with one API call: https://mail.zoho.eu/api/accounts (remember to adjust for your area). Help page here for what scope you need. The call returns a mass of information but buried in it are your Zoho User ID (ZUID), Zoho Organisation ID (ZOID) and Zoho Account ID (ZAID).

      2)    If you only want your Zoho User ID (ZUID). you don’t need an API call. Just log into Zoho and click the ‘My Profile’ icon (top right). Your user ID is right there under your name and email address.

      3)    Zoho advises an API call to get your Zoho Organisation ID (ZOID). But, again, there’s an easier way: open your Zoho Mail Dashboard (remember, this link is for zoho.eu, you’ll need to use your area). Then select ‘Organization’ on the left menu bar to display your Zoho Organization ID under the heading ‘Organization Info’.

FOLDER & EMAIL IDs

      1)    You may be able to use the name of a folder (e.g. “Trash”) in your Deluge script but if you need the folder ID number, this is the API.

      2)    All my scripts are triggered by an email by arriving in my inbox. The ID for that current email is held in the variable ‘mail_messageId’.

      3)    For everything else refer to the API Guide Index

url = "https://mail.zoho.eu/api/accounts";

response = invokeurl

[

            url :url

            type :GET

            connection:"your_oath_token" // the link name (in quotes) for the OAuth Token you created 

];

sendmail

[

            from :zoho.loginuserid

            to :"you@youraddress" // your email address in double quotes

            subject :"accounts" // or whatever subject you want

            message :response

]