@explita/cloud-mail-client/README.md

A simple mail client for Node applications.

### Part of the Explita Cloud Platform

A lightweight mail client for Node.js — built as a core component of the Explita Cloud platform. It simplifies mail in your backend by providing easy-to-use utilities for sending emails.

---

## 🚀 Installation

```bash
npm install @explita/cloud-mail-client
```

or

```bash
yarn add @explita/cloud-mail-client
```

or

```bash
pnpm add @explita/cloud-mail-client
```

---

#### Usage

##### Send Single Mail

```typescript
import { sendMail } from "@explita/cloud-mail-client";

const res = await sendMail({
  from: "John Doe <john@example.com>",
  to: "john@example.com", // can be an array of emails
  subject: "Hello",
  text: "Hello, this is a test email",
  html: "<h1>Hello, this is a test email</h1>",

  //optionals
  replyTo: "john@example.com", // can be an array of emails
  cc: "john@example.com", // can be an array of emails
  bcc: "john@example.com", // can be an array of emails
  attachments: [
    {
      filename: "test.txt",
      content: "Hello, this is a test email", //Buffer | string;
      contentType: "text/plain", // optional
    },
  ],
  headers: {
    "X-Custom-Header": "Custom Value",
  },
});

console.log(res);

// response could be:
// {
//   success: true,
//   status: "ACCEPTED",
//   messageId: "1234567890",
//   createdAt: "2022-01-01T00:00:00.000Z",
// }

// or
// {
//   success: false,
//   error: {
//     code: "InvalidData",
//     message: "Invalid data provided",
//     errors: {
//       from: "from is required",
//       to: "to is required",
//       subject: "subject is required",
//     },
//   },
// }
```

##### Send Batch Mail

```typescript
import { sendBatch } from "@explita/cloud-mail-client";

const res = await sendBatch([
  {
    from: "John Doe <john@example.com>",
    to: "john@example.com", // can be an array of emails
    subject: "Hello",
    text: "Hello, this is a test email",
    html: "<h1>Hello, this is a test email</h1>",

    //optionals
    replyTo: "john@example.com", // can be an array of emails
    cc: "john@example.com", // can be an array of emails
    bcc: "john@example.com", // can be an array of emails
    attachments: [
      {
        filename: "test.txt",
        content: "Hello, this is a test email", //Buffer | string;
        contentType: "text/plain", // optional
      },
    ],
    headers: {
      "X-Custom-Header": "Custom Value",
    },
  },
  {
    from: "John Doe <john@example.com>",
    to: "john@example.com", // can be an array of emails
    subject: "Hello",
    text: "Hello, this is a test email",
    html: "<h1>Hello, this is a test email</h1>",

    //optionals
    replyTo: "john@example.com", // can be an array of emails
    cc: "john@example.com", // can be an array of emails
    bcc: "john@example.com", // can be an array of emails
    attachments: [
      {
        filename: "test.txt",
        content: "Hello, this is a test email", //Buffer | string;
        contentType: "text/plain", // optional
      },
    ],
    headers: {
      "X-Custom-Header": "Custom Value",
    },
  },
]);

console.log(res);

// response could be:
// {
//     "success": false,
//     "error": {
//         "code": "InvalidSenderDomain",
//         "message": "One or more sender domains are invalid.",
//         "details": [
//             {
//                 "index": 0,
//                 "reason": "Sender domain (example.com) not found"
//             }
//         ]
//     }
// }

// [{
//   success: true,
//   status: "ACCEPTED",
//   messageId: "1234567890",
//   createdAt: "2022-01-01T00:00:00.000Z",
// }]

// or
// {
//   success: false,
//   error: {
//     code: "InvalidData",
//     message: "Invalid data provided",
//     errors: {
//       from: "from is required",
//       to: "to is required",
//       subject: "subject is required",
//     },
//   },
// }
```

---

### Getting started

Sign up for an account at [Explita Cloud](https://cloud.explita.ng), create a project, add mail service and get your API key from the dashboard and add it to your environment variables.

---

### 📄 License

MIT — Made with ❤️ by [Explita](https://explita.ng)