mailcub 2.0.9 → 2.0.10

package/README.md

@@ -1,71 +1,179 @@
-# Mailcub Package Documentation
-Version: 2.0.9
+# Mailcub — Send email from Node.js with your domain
 
-## Introduction
-Mailcub is an npm package that enables you to send emails using a simple and straightforward interface. It provides a function to send emails with the following features:
+**Mailcub** is a Node.js npm package to send HTML or plain-text emails and attachments using your registered domain. Simple API, secret-key auth, ideal for transactional email and newsletters.
 
-## Sending HTML emails.
-Attaching files to emails.
-Sending emails with a secret key for authentication.
+[![npm version](https://img.shields.io/npm/v/mailcub.svg)](https://www.npmjs.com/package/mailcub)
+[![npm downloads](https://img.shields.io/npm/dm/mailcub.svg)](https://www.npmjs.com/package/mailcub)
+[![license](https://img.shields.io/npm/l/mailcub.svg)](https://www.npmjs.com/package/mailcub)
+
+---
 
 ## Installation
-To install the "mailcub" package, use npm:
 
 ```bash
-
 npm install mailcub
-
 ```
 
-## Usage
-### Import the Package
-You can import the "mailcub" package in your Node.js application as follows:
+---
+
+## Quick example (30-second demo)
 
 ```javascript
 const mailcub = require('mailcub');
+
+const emailBody = {
+  email_from: 'hello@yourdomain.com',
+  receiver: 'user@example.com',
+  subject: 'Welcome',
+  html: '<h1>Hello!</h1><p>Thanks for signing up.</p>'
+};
+
+mailcub.sendMail(emailBody, 'your-secret-key')
+  .then(() => console.log('Email sent'))
+  .catch(err => console.error('Error:', err));
 ```
 
-### Sending an Email
-To send an email, use the sendMail function with the following parameters:
+Get your secret key at [client.mailcub.com](https://client.mailcub.com).
+
+---
+
+## Full API & options
+
+### `sendMail(body, key)`
 
-- body (Object): An object containing the email details.
-- key (String): The secret key for authentication.
+Sends an email. Returns a Promise.
 
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `body` | Object | Email payload (see below). |
+| `key` | String | Secret key for authentication. From [client.mailcub.com](https://client.mailcub.com). |
+
+### `body` object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email_from` | string | Yes | Sender email (use an address on your registered domain). |
+| `receiver` | string | Yes | Recipient email address. |
+| `subject` | string | Yes | Email subject line. |
+| `html` | string | No* | HTML body of the email. |
+| `text` | string | No* | Plain-text body of the email. Use `html` or `text` (or both). |
+| `attachment` | File or File[] | No | Single file or array of files (file objects only, not paths). |
+
+*At least one of `html` or `text` is required.
+
+### Examples
+
+**Plain text only**
 
 ```javascript
-const emailBody = {
-  email_from: 'user@yourdomain.com',
+mailcub.sendMail({
+  email_from: 'noreply@yourdomain.com',
+  receiver: 'customer@example.com',
+  subject: 'Order confirmation',
+  text: 'Thank you for your order. Order #1234 has been received.'
+}, process.env.MAILCUB_SECRET_KEY);
+```
+
+**HTML only**
+
+```javascript
+mailcub.sendMail({
+  email_from: 'noreply@yourdomain.com',
+  receiver: 'customer@example.com',
+  subject: 'Order confirmation',
+  html: '<h1>Order #1234</h1><p>Thank you for your order.</p>'
+}, process.env.MAILCUB_SECRET_KEY);
+```
+
+**With a single attachment**
+
+```javascript
+// attachment = file from request, Postman, etc.
+mailcub.sendMail({
+  email_from: 'billing@yourdomain.com',
+  receiver: 'client@example.com',
+  subject: 'Your invoice',
+  html: '<p>Please find your invoice attached.</p>',
+  attachment
+}, process.env.MAILCUB_SECRET_KEY);
+```
+
+**With multiple attachments**
+
+```javascript
+// attachment = array of files (e.g. from request, Postman, etc.)
+mailcub.sendMail({
+  email_from: 'team@yourdomain.com',
   receiver: 'user@example.com',
-  subject: 'Subject',
-  html: '<h1>Hello</h1>',
-  attachment: attachment_file
-};
+  subject: 'Your documents',
+  html: '<p>Attached are the requested files.</p>',
+  attachment: [file1, file2]
+}, process.env.MAILCUB_SECRET_KEY);
+```
 
-const secretKey = 'your-secret-key';
+**Using async/await**
+
+```javascript
+const mailcub = require('mailcub');
 
-mailcub.sendMail(emailBody, secretKey)
-  .then(() => {
-    console.log('Email sent successfully');
-  })
-  .catch((error) => {
-    console.error('Error sending email:', error);
-  });
+async function sendWelcomeEmail(to) {
+  try {
+    await mailcub.sendMail({
+      email_from: 'hello@yourdomain.com',
+      receiver: to,
+      subject: 'Welcome',
+      html: '<h1>Welcome!</h1>'
+    }, process.env.MAILCUB_SECRET_KEY);
+    return true;
+  } catch (err) {
+    console.error(err);
+    return false;
+  }
+}
 ```
 
-## Parameters
-- emailBody (Object):
-    - email_from (String): The sender's email address.
-    - receiver (String): The recipient's email address.
-    - subject (String): The email subject.
-    - html (String): The HTML content of the email.
-    - attachment (File or Array of files): The single attachment file, or an array of files for multiple attachments — e.g., ['file1', 'file2', 'file3'].
+---
+
+## Why choose Mailcub?
+
+- **Simple API** — One function, clear parameters; no SMTP or server config.
+- **Your domain** — Send from your own domain for a professional, branded look.
+- **HTML or plain text** — Send rich HTML or simple plain-text emails (or both).
+- **Attachments** — Single or multiple file attachments.
+- **Secret-key auth** — Secure authentication; keep your key in env vars.
+- **Lightweight** — Minimal dependencies; fits into existing Node.js apps.
+- **Transactional & newsletters** — Suited for both one-off emails and bulk sending.
+
+---
+
+## Troubleshooting & FAQ
+
+**Where do I get the secret key?**  
+Sign up and get your key at [client.mailcub.com](https://client.mailcub.com).
+
+**"Error sending email" or failed requests**  
+- Ensure `email_from` uses a domain you’ve registered in Mailcub.  
+- Check that your secret key is correct and not expired.  
+- Verify `receiver` and `subject` are non-empty; include at least one of `html` or `text`.
+
+**Attachments not sending**  
+- `attachment` must be file(s) (e.g. from request, Postman, or your app), not path strings.  
+- For multiple files, pass an array: `attachment: [file1, file2]`.
+
+**Need help?**  
+Contact **support@mailcub.com** or open an issue: [GitHub Issues](https://github.com/devflips/mailcub/issues).
+
+---
+
+## Contributing & Code of Conduct
 
-- secretKey (String): The secret key for authentication. You can obtain this key from console.mailcub.com.
+Contributions are welcome. Please open an issue or pull request on [GitHub](https://github.com/devflips/mailcub). Be respectful and constructive; we expect a courteous, inclusive environment for everyone.
 
-## Support and Issues
-If you encounter any issues or have questions, please contact our support team at support@mailcub.com.
+---
 
-## License
-This package is distributed under the MIT License. See the LICENSE file for details.
 
+## License & Author
 
+- **License:** [ISC](https://opensource.org/licenses/ISC)  
+- **Author:** [Devflips](https://github.com/devflips)  
+- **Package:** [npm — mailcub](https://www.npmjs.com/package/mailcub) · [GitHub — mailcub](https://github.com/devflips/mailcub)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailcub",
-  "version": "2.0.9",
+  "version": "2.0.10",
   "description": "This package enables users to send emails using their registered domains, providing a professional and branded approach to communication.",
   "main": "index.js",
   "scripts": {