Zoho Mail API Wrapper 📨

Simple, minimal, and typed utility to send emails using Zoho.

In order to centralize mail domain management, I had to implement this class a while back to use Zoho not only as a mail provider but also as a server to send emails programmatically.

It's a minimal implementation that only handles sending emails using the complete options that Zoho provides.

Feel free to use it, modify it, report issues, or just complain about it.

[!WARNING]
You will need to have a Zoho account and a custom domain email that you want to use as sender. Then you'll need to create a Self-Client to generate credentials (Client ID and Client Secret) on Zoho API Console

Installation

pnpm add @yarso/zoho-mail

Usage

Create a client

Use the ZohoMail class with your credentials to create a client and start sending emails.

import { ZohoMail } from "@yarso/zoho-mail"

const zoho = new ZohoMail({
  clientId: 'nnnn.xxxxxxxxxxxxxxxxxxxxxxx', // Client ID
  clientSecret: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxx' // Client Secret
})

Just send an email

You're ready to directly send an email from your service. Check out the Zoho Docs if you're interested in all the params you can use to send an email: Zoho - Send an Email

[!NOTE]
It's important to mention that I included an optional param fromAlias to set the alias that appears in the mailbox. The field fromAddress is taken directly from your Zoho Account.

await zoho.send({
  fromAlias: "My Company", // Optional: appears as sender name
  toAddress: "[email protected]",
  subject: "Hey, Check Zoho Mail",
  content: "Foo Bar",
})

Error Handling

The wrapper throws ZohoMailError when something goes wrong. You can catch and handle these errors:

import { ZohoMail, ZohoMailError } from "@yarso/zoho-mail"

try {
  await zoho.send({
    toAddress: "[email protected]",
    subject: "Test",
    content: "Hello"
  })
} catch (error) {
  if (error instanceof ZohoMailError) {
    console.error(`Error ${error.code}: ${error.message}`)
  }
}

Known Limitations

This is a custom implementation designed to suit specific requirements, so yeah, there are plenty of areas for improvement.

No runtime validations

I implemented the full types to achieve a simple utility that you just call. There are no runtime type validations, so if you ignore the editor warnings, Zoho services are gonna return an error.

I don't have plans to implement it at the moment, I don't even need it. But feel free to fork if you want to extend the functionality.

Requirements

• Node.js >= 18.0.0 (native fetch support)
• Or Bun >= 1.0.0
• Or Deno >= 1.0.0

License

MIT License.