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
]