mailcub 2.0.9 → 2.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +179 -71
  2. package/package.json +9 -6
package/README.md CHANGED
@@ -1,71 +1,179 @@
1
- # Mailcub Package Documentation
2
- Version: 2.0.9
3
-
4
- ## Introduction
5
- 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:
6
-
7
- ## Sending HTML emails.
8
- Attaching files to emails.
9
- Sending emails with a secret key for authentication.
10
-
11
- ## Installation
12
- To install the "mailcub" package, use npm:
13
-
14
- ```bash
15
-
16
- npm install mailcub
17
-
18
- ```
19
-
20
- ## Usage
21
- ### Import the Package
22
- You can import the "mailcub" package in your Node.js application as follows:
23
-
24
- ```javascript
25
- const mailcub = require('mailcub');
26
- ```
27
-
28
- ### Sending an Email
29
- To send an email, use the sendMail function with the following parameters:
30
-
31
- - body (Object): An object containing the email details.
32
- - key (String): The secret key for authentication.
33
-
34
-
35
- ```javascript
36
- const emailBody = {
37
- email_from: 'user@yourdomain.com',
38
- receiver: 'user@example.com',
39
- subject: 'Subject',
40
- html: '<h1>Hello</h1>',
41
- attachment: attachment_file
42
- };
43
-
44
- const secretKey = 'your-secret-key';
45
-
46
- mailcub.sendMail(emailBody, secretKey)
47
- .then(() => {
48
- console.log('Email sent successfully');
49
- })
50
- .catch((error) => {
51
- console.error('Error sending email:', error);
52
- });
53
- ```
54
-
55
- ## Parameters
56
- - emailBody (Object):
57
- - email_from (String): The sender's email address.
58
- - receiver (String): The recipient's email address.
59
- - subject (String): The email subject.
60
- - html (String): The HTML content of the email.
61
- - attachment (File or Array of files): The single attachment file, or an array of files for multiple attachments — e.g., ['file1', 'file2', 'file3'].
62
-
63
- - secretKey (String): The secret key for authentication. You can obtain this key from console.mailcub.com.
64
-
65
- ## Support and Issues
66
- If you encounter any issues or have questions, please contact our support team at support@mailcub.com.
67
-
68
- ## License
69
- This package is distributed under the MIT License. See the LICENSE file for details.
70
-
71
-
1
+ #Mailcub — Node.js SDK to send transactional emails and newsletters from your own domain using the MailCub email API.
2
+
3
+ **Mailcub** is a lightweight Node.js package for sending HTML or plain‑text emails and attachments from your own domain via the MailCub email API. It’s built for transactional emails, app notifications, and simple newsletters without managing SMTP servers yourself.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/mailcub.svg)](https://www.npmjs.com/package/mailcub)
6
+ [![npm downloads](https://img.shields.io/npm/dm/mailcub.svg)](https://www.npmjs.com/package/mailcub)
7
+ [![license](https://img.shields.io/npm/l/mailcub.svg)](https://www.npmjs.com/package/mailcub)
8
+
9
+ ---
10
+
11
+ ## Installation
12
+
13
+ ```bash
14
+ npm install mailcub
15
+ ```
16
+
17
+ ---
18
+
19
+ ## Quick example (30-second demo)
20
+
21
+ ```javascript
22
+ const mailcub = require('mailcub');
23
+
24
+ const emailBody = {
25
+ email_from: 'hello@yourdomain.com',
26
+ receiver: 'user@example.com',
27
+ subject: 'Welcome',
28
+ html: '<h1>Hello!</h1><p>Thanks for signing up.</p>'
29
+ };
30
+
31
+ mailcub.sendMail(emailBody, 'your-secret-key')
32
+ .then(() => console.log('Email sent'))
33
+ .catch(err => console.error('Error:', err));
34
+ ```
35
+
36
+ Get your secret key at [mailcub.com](https://mailcub.com).
37
+
38
+ ---
39
+
40
+ ## Full API & options
41
+
42
+ ### `sendMail(body, key)`
43
+
44
+ Sends an email. Returns a Promise.
45
+
46
+ | Parameter | Type | Description |
47
+ |-----------|------|-------------|
48
+ | `body` | Object | Email payload (see below). |
49
+ | `key` | String | Secret key for authentication. From [client.mailcub.com](https://client.mailcub.com). |
50
+
51
+ ### `body` object
52
+
53
+ | Field | Type | Required | Description |
54
+ |-------|------|----------|-------------|
55
+ | `email_from` | string | Yes | Sender email (use an address on your registered domain). |
56
+ | `receiver` | string | Yes | Recipient email address. |
57
+ | `subject` | string | Yes | Email subject line. |
58
+ | `html` | string | No* | HTML body of the email. |
59
+ | `text` | string | No* | Plain-text body of the email. Use `html` or `text` (or both). |
60
+ | `attachment` | File or File[] | No | Single file or array of files (file objects only, not paths). |
61
+
62
+ *At least one of `html` or `text` is required.
63
+
64
+ ### Examples
65
+
66
+ **Plain text only**
67
+
68
+ ```javascript
69
+ mailcub.sendMail({
70
+ email_from: 'noreply@yourdomain.com',
71
+ receiver: 'customer@example.com',
72
+ subject: 'Order confirmation',
73
+ text: 'Thank you for your order. Order #1234 has been received.'
74
+ }, process.env.MAILCUB_SECRET_KEY);
75
+ ```
76
+
77
+ **HTML only**
78
+
79
+ ```javascript
80
+ mailcub.sendMail({
81
+ email_from: 'noreply@yourdomain.com',
82
+ receiver: 'customer@example.com',
83
+ subject: 'Order confirmation',
84
+ html: '<h1>Order #1234</h1><p>Thank you for your order.</p>'
85
+ }, process.env.MAILCUB_SECRET_KEY);
86
+ ```
87
+
88
+ **With a single attachment**
89
+
90
+ ```javascript
91
+ // attachment = file from request, Postman, etc.
92
+ mailcub.sendMail({
93
+ email_from: 'billing@yourdomain.com',
94
+ receiver: 'client@example.com',
95
+ subject: 'Your invoice',
96
+ html: '<p>Please find your invoice attached.</p>',
97
+ attachment
98
+ }, process.env.MAILCUB_SECRET_KEY);
99
+ ```
100
+
101
+ **With multiple attachments**
102
+
103
+ ```javascript
104
+ // attachment = array of files (e.g. from request, Postman, etc.)
105
+ mailcub.sendMail({
106
+ email_from: 'team@yourdomain.com',
107
+ receiver: 'user@example.com',
108
+ subject: 'Your documents',
109
+ html: '<p>Attached are the requested files.</p>',
110
+ attachment: [file1, file2]
111
+ }, process.env.MAILCUB_SECRET_KEY);
112
+ ```
113
+
114
+ **Using async/await**
115
+
116
+ ```javascript
117
+ const mailcub = require('mailcub');
118
+
119
+ async function sendWelcomeEmail(to) {
120
+ try {
121
+ await mailcub.sendMail({
122
+ email_from: 'hello@yourdomain.com',
123
+ receiver: to,
124
+ subject: 'Welcome',
125
+ html: '<h1>Welcome!</h1>'
126
+ }, process.env.MAILCUB_SECRET_KEY);
127
+ return true;
128
+ } catch (err) {
129
+ console.error(err);
130
+ return false;
131
+ }
132
+ }
133
+ ```
134
+
135
+ ---
136
+
137
+ ## Why choose Mailcub?
138
+
139
+ - **Simple API** — One function, clear parameters; no SMTP or server config.
140
+ - **Your domain** — Send from your own domain for a professional, branded look.
141
+ - **HTML or plain text** — Send rich HTML or simple plain-text emails (or both).
142
+ - **Attachments** — Single or multiple file attachments.
143
+ - **Secret-key auth** — Secure authentication; keep your key in env vars.
144
+ - **Lightweight** — Minimal dependencies; fits into existing Node.js apps.
145
+ - **Transactional & newsletters** — Suited for both one-off emails and bulk sending.
146
+
147
+ ---
148
+
149
+ ## Troubleshooting & FAQ
150
+
151
+ **Where do I get the secret key?**
152
+ Sign up and get your key at [client.mailcub.com](https://client.mailcub.com).
153
+
154
+ **"Error sending email" or failed requests**
155
+ - Ensure `email_from` uses a domain you’ve registered in Mailcub.
156
+ - Check that your secret key is correct and not expired.
157
+ - Verify `receiver` and `subject` are non-empty; include at least one of `html` or `text`.
158
+
159
+ **Attachments not sending**
160
+ - `attachment` must be file(s) (e.g. from request, Postman, or your app), not path strings.
161
+ - For multiple files, pass an array: `attachment: [file1, file2]`.
162
+
163
+ **Need help?**
164
+ Contact **support@mailcub.com** or open an issue: [GitHub Issues](https://github.com/devflips/mailcub/issues).
165
+
166
+ ---
167
+
168
+ ## Contributing & Code of Conduct
169
+
170
+ 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.
171
+
172
+ ---
173
+
174
+
175
+ ## License & Author
176
+
177
+ - **License:** [ISC](https://opensource.org/licenses/ISC)
178
+ - **Author:** [Devflips](https://github.com/devflips)
179
+ - **Package:** [npm — mailcub](https://www.npmjs.com/package/mailcub) · [GitHub — mailcub](https://github.com/devflips/mailcub)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mailcub",
3
- "version": "2.0.9",
3
+ "version": "2.0.11",
4
4
  "description": "This package enables users to send emails using their registered domains, providing a professional and branded approach to communication.",
5
5
  "main": "index.js",
6
6
  "scripts": {
@@ -17,11 +17,14 @@
17
17
  "author": "Devflips",
18
18
  "license": "ISC",
19
19
  "keywords": [
20
- "mailcub",
21
- "mailcub api",
22
- "email",
23
- "mail",
24
- "newsletter"
20
+ "mailcub",
21
+ "email",
22
+ "email api",
23
+ "transactional email",
24
+ "smtp",
25
+ "nodejs",
26
+ "email hosting",
27
+ "mail server"
25
28
  ],
26
29
  "bugs": {
27
30
  "url": "https://github.com/devflips/mailcub/issues"