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. This route is intended for developers who are using external apps to link with Zoho.

The easy way, at least for me, was via a custom function in filters — because it’s simple to do, refreshing the OAuth token is handled by Zoho, 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). It's good security practice to only use the minimum scope you need.

      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.

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, either use this API or, even easier, select an email in the folder your interested in, right click and pick 'Open in New Window'. The folder ID comes after 'folId=' in the browser URL.

      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