Skip to content

Commit 0373ae0

Browse files
xr0masterxr0master
committed
improve readme
1 parent 44b5fdf commit 0373ae0

File tree

1 file changed

+101
-26
lines changed

1 file changed

+101
-26
lines changed

‎README.md‎

Lines changed: 101 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,18 @@
22

33
SDK for [EmailJS.com](https://www.emailjs.com) customers.
44
\
5-
Use you EmailJS account for sending emails.
5+
Use your EmailJS account for sending emails.
66

77
[![codecov](https://codecov.io/gh/emailjs-com/emailjs-nodejs/branch/main/graph/badge.svg)](https://codecov.io/gh/emailjs-com/emailjs-nodejs)
88
[![npm version](https://img.shields.io/npm/v/@emailjs/nodejs.svg)](https://www.npmjs.com/package/@emailjs/nodejs)
99

1010
## Disclaimer
1111

12-
This is a NodeJS-only version, otherwise use
12+
This is a Node.js platform, otherwise use
13+
1314
- [Browser SDK](https://www.npmjs.com/package/@emailjs/browser)
14-
- [Flutter SDK](https://pub.dev/packages/emailjs)
15+
- [React Native](https://www.npmjs.com/package/@emailjs/react-native)
16+
- [Flutter](https://pub.dev/packages/emailjs)
1517
- [REST API](https://www.emailjs.com/docs/rest-api/send/)
1618

1719
## Links
@@ -20,33 +22,34 @@ This is a NodeJS-only version, otherwise use
2022

2123
## Intro
2224

23-
EmailJS helps to send emails directly from your code.
25+
EmailJS helps you send emails directly from code with one command.
2426
No large knowledge is required – just connect EmailJS to one of the supported
2527
email services, create an email template, and use our SDK
2628
to trigger an email.
2729

2830
## Usage
2931

30-
Install EmailJS SDK using [npm](https://www.npmjs.com/):
32+
Install EmailJS SDK using [npm](https://www.npmjs.com/package/@emailjs/nodejs):
3133

3234
```bash
3335
$ npm install @emailjs/nodejs
3436
```
3537

36-
***Note***: By default, API requests are disabled for non-browser applications.
38+
**_Note_**: By default, API requests are disabled for non-browser applications.
3739
You need to activate them through [Account:Security](https://dashboard.emailjs.com/admin/account/security).
3840

3941
## FAQ
4042

4143
#### API calls are disabled for non-browser applications
44+
4245
You need to activate API requests
4346
through [Account:Security](https://dashboard.emailjs.com/admin/account/security).
4447

4548
## Examples
4649

4750
### ECMAScript modules
4851

49-
**send email**
52+
**Send the email using the customized send method**
5053

5154
```js
5255
import emailjs from '@emailjs/nodejs';
@@ -57,9 +60,9 @@ const templateParams = {
5760
};
5861

5962
emailjs
60-
.send('<YOUR_SERVICE_ID>', '<YOUR_TEMPLATE_ID>', templateParams, {
61-
publicKey: '<YOUR_PUBLIC_KEY>',
62-
privateKey: '<YOUR_PRIVATE_KEY>', // optional, highly recommended for security reasons
63+
.send('YOUR_SERVICE_ID', 'YOUR_TEMPLATE_ID', templateParams, {
64+
publicKey: 'YOUR_PUBLIC_KEY',
65+
privateKey: 'YOUR_PRIVATE_KEY', // optional, highly recommended for security reasons
6366
})
6467
.then(
6568
(response) => {
@@ -78,11 +81,11 @@ import emailjs from '@emailjs/nodejs';
7881

7982
// set Public Key as global settings
8083
emailjs.init({
81-
publicKey: '<YOUR_PUBLIC_KEY>',
82-
privateKey: '<YOUR_PRIVATE_KEY>', // optional, highly recommended for security reasons
84+
publicKey: 'YOUR_PUBLIC_KEY',
85+
privateKey: 'YOUR_PRIVATE_KEY', // optional, highly recommended for security reasons
8386
});
8487

85-
emailjs.send('<YOUR_SERVICE_ID>', '<YOUR_TEMPLATE_ID>').then(
88+
emailjs.send('YOUR_SERVICE_ID', 'YOUR_TEMPLATE_ID').then(
8689
(response) => {
8790
console.log('SUCCESS!', response.status, response.text);
8891
},
@@ -99,12 +102,12 @@ import emailjs, { EmailJSResponseStatus } from '@emailjs/nodejs';
99102

100103
try {
101104
await emailjs.send(
102-
'<YOUR_SERVICE_ID>',
103-
'<YOUR_TEMPLATE_ID>',
105+
'YOUR_SERVICE_ID',
106+
'YOUR_TEMPLATE_ID',
104107
{},
105108
{
106-
publicKey: '<YOUR_PUBLIC_KEY>',
107-
privateKey: '<YOUR_PRIVATE_KEY>', // optional, highly recommended for security reasons
109+
publicKey: 'YOUR_PUBLIC_KEY',
110+
privateKey: 'YOUR_PRIVATE_KEY', // optional, highly recommended for security reasons
108111
},
109112
);
110113
console.log('SUCCESS!');
@@ -118,28 +121,100 @@ try {
118121
}
119122
```
120123

121-
### CommonJS modules
124+
## Configuration
125+
126+
**Options**
127+
128+
Options can be declared globally using the **init** method or locally as the fourth parameter of a function.
129+
\
130+
The local parameter will have higher priority than the global one.
131+
132+
| Name | Type | Default | Description |
133+
| --------------- | --------------- | ------- | ------------------------------------------------ |
134+
| publicKey | String | | The public key is required to invoke the method. |
135+
| blockList | BlockList | | Block list settings. |
136+
| limitRate | LimitRate | | Limit rate configuration. |
137+
| storageProvider | StorageProvider | | Provider for a custom key-value storage. |
138+
139+
**BlockList**
140+
141+
Allows to ignore a method call if the watched variable contains a value from the block list.
142+
\
143+
The method will return the error 403 if the request is blocked.
144+
145+
| Name | Type | Description |
146+
| ------------- | -------- | -------------------------------------------------- |
147+
| list | String[] | The array of strings contains values for blocking. |
148+
| watchVariable | String | A name of the variable to be watched. |
149+
150+
**LimitRate**
151+
152+
Allows to set the limit rate for calling a method.
153+
\
154+
If the request hits the limit rate, the method will return the error 429.
155+
156+
| Name | Type | Default | Description |
157+
| -------- | ------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
158+
| id | String | page path | The limit rate is per page by default. To override the behavior, set the ID. It can be a custom ID for each page, group, or application. |
159+
| throttle | Number | | _(ms)_ After how many milliseconds a next request is allowed. |
160+
161+
**StorageProvider**
162+
163+
Allows to provide a custom key value storage. By default, localStorage is used if available.
164+
\
165+
The custom provider must match the interface.
166+
167+
```ts
168+
interface StorageProvider {
169+
get: (key: string) => Promise<string | null | undefined>;
170+
set: (key: string, value: string) => Promise<void>;
171+
remove: (key: string) => Promise<void>;
172+
}
173+
```
174+
175+
**Declare global settings**
176+
177+
```js
178+
import emailjs from '@emailjs/nodejs';
179+
180+
emailjs.init({
181+
publicKey: 'YOUR_PUBLIC_KEY',
182+
privateKey: 'YOUR_PRIVATE_KEY', // optional, highly recommended for security reasons
183+
blockList: {
184+
list: ['[email protected]', '[email protected]'],
185+
},
186+
limitRate: {
187+
throttle: 10000, // 10s
188+
},
189+
});
190+
```
122191

123-
**send email**
192+
**Overwrite settings locally**
124193

125194
```js
126-
const emailjs = require('@emailjs/nodejs');
195+
import emailjs from '@emailjs/nodejs';
127196

128-
var templateParams = {
197+
const templateParams = {
129198
name: 'James',
130199
notes: 'Check this out!',
131200
};
132201

133202
emailjs
134-
.send('<YOUR_SERVICE_ID>', '<YOUR_TEMPLATE_ID>', templateParams, {
135-
publicKey: '<YOUR_PUBLIC_KEY>',
136-
privateKey: '<YOUR_PRIVATE_KEY>', // optional, highly recommended for security reasons
203+
.send('YOUR_SERVICE_ID', 'YOUR_TEMPLATE_ID', templateParams, {
204+
publicKey: 'YOUR_PUBLIC_KEY',
205+
privateKey: 'YOUR_PRIVATE_KEY', // optional, highly recommended for security reasons
206+
blockList: {
207+
watchVariable: 'userEmail',
208+
},
209+
limitRate: {
210+
throttle: 0, // turn off the limit rate for these requests
211+
},
137212
})
138213
.then(
139-
function (response) {
214+
(response) => {
140215
console.log('SUCCESS!', response.status, response.text);
141216
},
142-
function (err) {
217+
(err) => {
143218
console.log('FAILED...', err);
144219
},
145220
);

0 commit comments

Comments
 (0)