mailgun.js 3.5.8 → 3.7.0

package/.eslintrc

@@ -7,20 +7,17 @@
     "mocha": true
   },
   "extends": [
-    "airbnb-base",
-    "plugin:@typescript-eslint/eslint-recommended",
-    "plugin:@typescript-eslint/recommended"
+    "airbnb-base"
   ],
-  "plugins": [
-    "eslint-plugin-tsdoc",
-    "@typescript-eslint"
-  ],
-  "parser": "@typescript-eslint/parser",
   "parserOptions": {
     "ecmaVersion": 12
   },
   "settings": {
-    "import/resolver": "webpack"
+      "import/resolver": {
+        "node": {
+          "extensions": [".js", ".jsx", ".ts", ".tsx"]
+        }
+      }
   },
   "ignorePatterns": ["docs/assets/js/*", "dist/**"],
   "rules": {
@@ -33,6 +30,25 @@
     "class-methods-use-this": 0,
     "prefer-destructuring": 0,
     "import/extensions": 0,
-    "lines-between-class-members": ["error", "always", { "exceptAfterSingleLine": true }]
-  }
+    "lines-between-class-members": ["error", "always", { "exceptAfterSingleLine": true }],
+    "import/no-extraneous-dependencies" :["error", {"devDependencies": true, "optionalDependencies": false, "peerDependencies": false}]
+  },
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx"],
+      "extends": [
+        "plugin:@typescript-eslint/eslint-recommended",
+        "plugin:@typescript-eslint/recommended"
+      ],
+      "parser": "@typescript-eslint/parser",
+      "rules": {
+        "import/extensions": 0
+        // "import/no-extraneous-dependencies" :["error", {"devDependencies": true, "optionalDependencies": false, "peerDependencies": false}]
+      },
+      "plugins": [
+        "eslint-plugin-tsdoc",
+        "@typescript-eslint"
+      ]
+    }
+  ]
 }

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [3.7.0](https://github.com/mailgun/mailgun-js/compare/v3.6.1...v3.7.0) (2021-10-20)
+
+
+### Features
+
+* Fix linter errors ([126ba03](https://github.com/mailgun/mailgun-js/commits/126ba039bccfbdb257ddde7d17a58790e4cd30a3))
+
+### [3.6.1](https://github.com/mailgun/mailgun-js/compare/v3.6.0...v3.6.1) (2021-10-18)
+
+
+### Other changes
+
+* Update eslint dependency. Regenerate package-lock file ([0e1fef6](https://github.com/mailgun/mailgun-js/commits/0e1fef683b86e05852a04c6e2f6199db0e39ff22))
+* Update mocha to v9 ([768ed1f](https://github.com/mailgun/mailgun-js/commits/768ed1f5896c2bbb7fff59f4fbb68d425ea5a594))
+
+## [3.6.0](https://github.com/mailgun/mailgun-js/compare/v3.5.9...v3.6.0) (2021-10-13)
+
+
+### Features
+
+* Split the distro for different targets ([1a55085](https://github.com/mailgun/mailgun-js/commits/1a550854765c7cdbb68b13b32c1f1392003abf30))
+* Update commitlint rules ([262ce0c](https://github.com/mailgun/mailgun-js/commits/262ce0ccd594bbcd97c9aa9ba5f11ad6ce6fc8c5))
+
+### [3.5.9](https://github.com/mailgun/mailgun-js/compare/v3.5.8...v3.5.9) (2021-09-16)
+
+
+### Bug Fixes
+
+* Update @commitlint/cli and standard-version dependencies ([fe0233e](https://github.com/mailgun/mailgun-js/commits/fe0233e9afbd546f33b0f1c73930ca9329b5fa38))
+
+
+### Other changes
+
+* Add templates examples to readme ([f0bf0b8](https://github.com/mailgun/mailgun-js/commits/f0bf0b8cc66b3e7e5899fa913f2f79582f547a37))
+
 ### [3.5.8](https://github.com/mailgun/mailgun-js/compare/v3.5.7...v3.5.8) (2021-09-02)
 
 

package/README.md

@@ -125,32 +125,53 @@ Method naming conventions:
 
 `mg.messages.create(domain, data)` - [api docs](https://documentation.mailgun.com/api-sending.html#sending)
 
-HTML/TEXT Example:
+Options:
 
-```js
-mg.messages.create('sandbox-123.mailgun.org', {
-    from: "Excited User <mailgun@sandbox-123.mailgun.org>",
-    to: ["test@example.com"],
-    subject: "Hello",
-    text: "Testing some Mailgun awesomness!",
-    html: "<h1>Testing some Mailgun awesomness!</h1>"
-  })
-  .then(msg => console.log(msg)) // logs response data
-  .catch(err => console.log(err)); // logs any error
-```
+Parameter         | Description
+:---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+to                | Email address of the recipient(s). Example: "Bob <bob@host.com>". You can use commas to separate multiple recipients (e.g.: "test@example.com,test@example.com" or ["test@example.com", "test@example.com"]). Make sure to include all To, Cc and Bcc recipients of the message.
+html              | HTML version of the message.
+text              | Text version of the message.
+message           | MIME string of the message. Make sure to use multipart/form-data to send this as a file upload.
+attachment        | File attachment. You can post multiple attachment values. Important: You must use multipart/form-data encoding when sending attachments. Also you can use `{data: file, filename: filename}` to define custom filename.
+o:tag             | Tag string. See Tagging for more information.
+o:campaign        | Id of the campaign the message belongs to. See um-campaign-analytics for details.
+o:deliverytime    | Desired time of delivery. See Date Format. Note: Messages can be scheduled for a maximum of 3 days in the future.
+o:dkim            | Enables/disabled DKIM signatures on per-message basis. Pass yes or no
+o:testmode        | Enables sending in test mode. Pass yes if needed. See Sending in Test Mode
+o:tracking        | Toggles tracking on a per-message basis, see Tracking Messages for details. Pass yes or no.
+o:tracking-clicks | Toggles clicks tracking on a per-message basis. Has higher priority than domain-level setting. Pass yes, no or htmlonly.
+o:tracking-opens  | Toggles opens tracking on a per-message basis. Has higher priority than domain-level setting. Pass yes or no.
+h:X-My-Header     | h: prefix followed by an arbitrary value allows to append a custom MIME header to the message (X-My-Header in this case). For example, h:Reply-To to specify Reply-To address.
+v:my-var          | v: prefix followed by an arbitrary name allows to attach a custom JSON data to the message. See Attaching Data to Messages for more information.
 
-MIME Example:
 
-```js
-mg.messages.create('sandbox-123.mailgun.org', {
-    from: "Excited User <mailgun@sandbox-123.mailgun.org>",
-    to: ["test@example.com"],
-    subject: "Hello",
-    message: "<mime encoded string here>"
-  })
-  .then(msg => console.log(msg)) // logs response data
-  .catch(err => console.log(err)); // logs any error
-```
+- HTML/TEXT Example:
+
+  ```js
+  mg.messages.create('sandbox-123.mailgun.org', {
+      from: "Excited User <mailgun@sandbox-123.mailgun.org>",
+      to: ["test@example.com"],
+      subject: "Hello",
+      text: "Testing some Mailgun awesomness!",
+      html: "<h1>Testing some Mailgun awesomness!</h1>"
+    })
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.log(err)); // logs any error
+  ```
+
+- MIME Example:
+
+  ```js
+  mg.messages.create('sandbox-123.mailgun.org', {
+      from: "Excited User <mailgun@sandbox-123.mailgun.org>",
+      to: ["test@example.com"],
+      subject: "Hello",
+      text: "<mime encoded string here>"
+    })
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.log(err)); // logs any error
+  ```
 
 Messages with attachments:
 
@@ -164,7 +185,7 @@ Messages with attachments:
         from: "Excited User <mailgun@sandbox-123.mailgun.org>",
         to: ["test@example.com"],
         subject: "Test subject",
-        message: "Hello here is a file in the attachment"
+        text: "Hello here is a file in the attachment"
     }
 
     fsPromises.readFile(filepath)
@@ -191,7 +212,7 @@ Messages with attachments:
       from: "Excited User <mailgun@sandbox-123.mailgun.org>",
       to: ["test@example.com"],
       subject: "Test subject",
-      message: "Test message"
+      text: "Test message"
   }
 
   (async () =>{
@@ -270,34 +291,101 @@ Messages with attachments:
 
     const res = await mg.messages.create(DOMAIN, messageParams);
   ```
-Promise Returns:
+  Promise Returns:
 
-```
-{
-  id: '<20151025002517.117282.79817@sandbox-123.mailgun.org>',
-  message: 'Queued. Thank you.'
-}
-```
+  ```js
+  {
+    id: '<20151025002517.117282.79817@sandbox-123.mailgun.org>',
+    message: 'Queued. Thank you.'
+  }
+  ```
+#### Templates
 
-Options:
+Mailgun’s templates uses a fork of the very popular template engine [handlebars](https://handlebarsjs.com/).
 
-Parameter         | Description
-:---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-to                | Email address of the recipient(s). Example: "Bob <bob@host.com>". You can use commas to separate multiple recipients (e.g.: "test@example.com,test@example.com" or ["test@example.com", "test@example.com"]). Make sure to include all To, Cc and Bcc recipients of the message.
-html              | HTML version of the message.
-text              | Text version of the message.
-message           | MIME string of the message. Make sure to use multipart/form-data to send this as a file upload.
-attachment        | File attachment. You can post multiple attachment values. Important: You must use multipart/form-data encoding when sending attachments. Also you can use `{data: file, filename: filename}` to define custom filename.
-o:tag             | Tag string. See Tagging for more information.
-o:campaign        | Id of the campaign the message belongs to. See um-campaign-analytics for details.
-o:deliverytime    | Desired time of delivery. See Date Format. Note: Messages can be scheduled for a maximum of 3 days in the future.
-o:dkim            | Enables/disabled DKIM signatures on per-message basis. Pass yes or no
-o:testmode        | Enables sending in test mode. Pass yes if needed. See Sending in Test Mode
-o:tracking        | Toggles tracking on a per-message basis, see Tracking Messages for details. Pass yes or no.
-o:tracking-clicks | Toggles clicks tracking on a per-message basis. Has higher priority than domain-level setting. Pass yes, no or htmlonly.
-o:tracking-opens  | Toggles opens tracking on a per-message basis. Has higher priority than domain-level setting. Pass yes or no.
-h:X-My-Header     | h: prefix followed by an arbitrary value allows to append a custom MIME header to the message (X-My-Header in this case). For example, h:Reply-To to specify Reply-To address.
-v:my-var          | v: prefix followed by an arbitrary name allows to attach a custom JSON data to the message. See Attaching Data to Messages for more information.
+To provide values for a substitution you need to use 'h:X-Mailgun-Variables' property in the message description.
+
+Make sure that this property is a JSON string like {"title":"A title", "body":"The body"}.
+
+You can find few examples of how to use templates below.
+- Providing values for **title** and **slug** variables to render in template
+```js
+...
+  const {
+    title,
+    slug,
+  } = someDataSource;
+
+  const mailgunData = {
+    from: 'mailer@example.com>',
+    to: 'recipient@example.com',
+    subject: `Email ${title}`,
+    template: 'name-of-the-template-you-made-in-mailgun-web-portal',
+    'h:X-Mailgun-Variables': JSON.stringify({ // be sure to stringify your payload
+      title,
+      slug,
+    }),
+    'h:Reply-To': 'reply-to@example.com',
+  };
+
+  try {
+    const response = await mailgun.messages.create(DOMAIN_NAME, mailgunData);
+...
+```
+
+- Providing an array of objects to render them in the template
+```JS
+  ...
+  const mailgunData = {
+    from: 'mailer@example.com>',
+    to: 'recipient@example.com',
+    subject: `Email ${title}`,
+    template: 'name-of-the-another-template-you-made-in-mailgun-web-portal',
+    'h:X-Mailgun-Variables': JSON.stringify({
+    "arrayItems": [
+        {
+            "question": "test_question",
+            "answer": "test_answer"
+        },
+        {
+            "question": "test_question",
+            "answer": "test_answer"
+        }
+    ]})
+  };
+  try {
+    const response = await mailgun.messages.create(DOMAIN_NAME, mailgunData);
+  ...
+```
+
+#### Recipient Variables
+[Docs](https://documentation.mailgun.com/en/latest/user_manual.html#batch-sending)
+
+Recipient Variables are custom variables that you define, which you can then reference in the message body. They give you the ability to send a custom message to each recipient while still using a single API Call.
+
+```Js
+...
+ const mailgunData = {
+    from: 'Example.com Mailer <mailer@mailer.example.com>',
+    to: ['me@example.com', 'you@example.com'],
+    subject: 'Recipient - %recipient.title%',
+    html: 'Here\'s %recipient.title% and <a href="%recipient.link%">link</a>',
+    'recipient-variables': JSON.stringify({
+      'me@example.com': {
+        title: 'Me',
+        link: 'href-var',
+      },
+      'you@example.com': {
+        title: 'You',
+        link: 'slug-recipient-var-c',
+      },
+    }),
+  };
+
+  try {
+    const response = await mailgun.messages.create(DOMAIN_NAME, mailgunData);
+...
+```
 
 ### domains
 

package/commitlint.config.js

@@ -1,8 +1,7 @@
 module.exports = {
   extends: ['@commitlint/config-conventional'],
   rules: {
-    'type-enum': [2, 'always', ['Breaking', 'Feature', 'Fix', 'Other']],
-    'type-case': [2, 'always', 'pascal-case'],
+    'type-enum': [2, 'always', ['breaking', 'feature', 'fix', 'other']],
     'subject-case': [2, 'always', 'sentence-case']
   },
 };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import Options from './lib/interfaces/Options';
 import IFormData from './lib/interfaces/IFormData';
 declare class Mailgun {
     private formData;
-    constructor(FormData: new (...args: any[]) => IFormData);
+    constructor(FormData: new (...args: unknown[]) => IFormData);
     client(options: Options): Client;
 }
 export = Mailgun;

package/dist/lib/client.d.ts

@@ -28,5 +28,5 @@ export default class Client {
     ips: IpsClient;
     ip_pools: IpPoolsClient;
     lists: ListsClient;
-    constructor(options: Options, formData: new (...args: any[]) => IFormData);
+    constructor(options: Options, formData: new (...args: unknown[]) => IFormData);
 }

package/dist/lib/events.d.ts

@@ -1,29 +1,13 @@
-declare const MgRequest: any;
+import { EventsList, EventsPage, EventsResponse, PagesList } from './interfaces/Events';
+import Request from './request';
 export default class EventClient {
-    request: typeof MgRequest;
-    constructor(request: typeof MgRequest);
+    request: Request;
+    constructor(request: Request);
     _parsePageNumber(url: string): string;
-    _parsePage(id: string, url: string): {
-        id: string;
-        number: string;
-        url: string;
-    };
-    _parsePageLinks(response: {
-        body: {
-            paging: any;
-        };
-    }): any;
-    _parseEventList(response: {
-        body: {
-            items: any;
-            paging: any;
-        };
-    }): {
-        items: any;
-        pages: any;
-    };
+    _parsePage(id: string, url: string): EventsPage;
+    _parsePageLinks(response: EventsResponse): PagesList;
+    _parseEventList(response: EventsResponse): EventsList;
     get(domain: string, query: {
-        page: any;
-    }): any;
+        page: string;
+    }): Promise<EventsList>;
 }
-export {};

package/dist/lib/interfaces/APIErrorOptions.d.ts

@@ -1,4 +1,4 @@
-export default interface APIErrorOptions {
+interface APIErrorOptions {
     headers: {
         [key: string]: any;
     };
@@ -8,3 +8,4 @@ export default interface APIErrorOptions {
     url: string;
     statusText: string;
 }
+export default APIErrorOptions;

package/dist/lib/interfaces/ApiResponse.d.ts

@@ -1,4 +1,5 @@
-export default interface APIResponse {
+interface APIResponse {
     status: number;
     body: any;
 }
+export default APIResponse;

package/dist/lib/interfaces/Events.d.ts

@@ -0,0 +1,24 @@
+export interface EventsPage {
+    id: string;
+    number: string;
+    url: string;
+}
+export interface PagesList {
+    previous: string;
+    first: string;
+    last: string;
+    next: string;
+}
+export interface EventsResponse {
+    body: {
+        items: [];
+        paging: PagesList;
+    };
+}
+export interface EventsList {
+    items: [];
+    pages: PagesList;
+}
+export interface PagesListAccumulator {
+    [index: string]: EventsPage;
+}

package/dist/lib/interfaces/IpPools.d.ts

@@ -5,3 +5,15 @@ export interface IpPool {
     name: string;
     pool_id: string;
 }
+export interface IpPoolListResponse {
+    body: {
+        ip_pools: IpPool;
+        message: string;
+    };
+}
+export interface IpPoolUpdateData {
+    name: string;
+    description: string;
+    add_ip: string;
+    remove_ip: string;
+}

package/dist/lib/interfaces/Options.d.ts

@@ -1,7 +1,8 @@
-export default interface Options {
+interface Options {
     username: string;
     key: string;
     url?: string;
     public_key?: string;
     timeout?: number;
 }
+export default Options;

package/dist/lib/interfaces/RequestOptions.d.ts

@@ -1,5 +1,6 @@
 import Options from './Options';
-export default interface RequestOptions extends Options {
+interface RequestOptions extends Options {
     headers: any;
     timeout: number;
 }
+export default RequestOptions;

package/dist/lib/interfaces/StatsOptions.d.ts

@@ -1,4 +1,4 @@
-export default interface StatsOptions {
+interface StatsOptions {
     start: string | Date;
     end: string | Date;
     resolution: string;
@@ -11,3 +11,4 @@ export default interface StatsOptions {
         };
     }[];
 }
+export default StatsOptions;

package/dist/lib/interfaces/mailListMembers.d.ts

@@ -1,4 +1,10 @@
 import { MailingList } from './lists';
+export interface MailListMember {
+    address: string;
+    name: string;
+    subscribed: boolean;
+    vars: string | any;
+}
 export interface MailListMembersQuery {
     subscribed?: 'yes' | 'no';
     limit?: number;
@@ -25,12 +31,6 @@ export interface CreateUpdateMailListMembersReq {
     subscribed?: 'yes' | 'no' | boolean;
     upsert?: 'yes' | 'no';
 }
-export interface MailListMember {
-    address: string;
-    name: string;
-    subscribed: boolean;
-    vars: string | any;
-}
 export interface DeletedMember {
     member: {
         address: string;

package/dist/lib/ip-pools.d.ts

@@ -1,24 +1,21 @@
-declare const MgRequest: any;
-import { IpPool } from "./interfaces/IpPools";
+import Request from './request';
+import { IpPool, IpPoolUpdateData } from './interfaces/IpPools';
 export default class IpPoolsClient {
-    request: typeof MgRequest;
-    constructor(request: typeof MgRequest);
-    list(query: any): IpPool[];
+    request: Request;
+    constructor(request: Request);
+    list(query: any): Promise<IpPool[]>;
     create(data: {
         name: string;
         description?: string;
         ips?: string[];
-    }): any;
-    update(poolId: string, data: {
-        name: string;
-        description: string;
-        add_ip: string;
-        remove_ip: string;
-    }): any;
+    }): Promise<{
+        message: string;
+        pool_id: string;
+    }>;
+    update(poolId: string, data: IpPoolUpdateData): Promise<any>;
     delete(poolId: string, data: {
         id: string;
         pool_id: string;
-    }): any;
+    }): Promise<any>;
     private parseIpPoolsResponse;
 }
-export {};

package/dist/lib/ips.d.ts

@@ -1,9 +1,9 @@
-declare const MgRequest: any;
+import MgRequest from './request';
+import { IpData, IpsListResponseBody } from './interfaces/Ips';
 export default class IpsClient {
-    request: typeof MgRequest;
-    constructor(request: typeof MgRequest);
-    list(query: any): any;
-    get(ip: string): any;
+    request: MgRequest;
+    constructor(request: MgRequest);
+    list(query: any): Promise<IpsListResponseBody | IpData>;
+    get(ip: string): Promise<IpsListResponseBody | IpData>;
     private parseIpsResponse;
 }
-export {};

package/dist/lib/messages.d.ts

@@ -1,4 +1,4 @@
-import Request from "./request";
+import Request from './request';
 export default class MessagesClient {
     request: Request;
     constructor(request: Request);

package/dist/lib/suppressions.d.ts

@@ -1,6 +1,5 @@
 import Request from './request';
 import { BounceData, ComplaintData, UnsubscribeData } from './interfaces/Supressions';
-declare type TModel = typeof Bounce | typeof Complaint | typeof Unsubscribe;
 declare class Bounce {
     type: string;
     address: string;
@@ -22,6 +21,7 @@ declare class Unsubscribe {
     created_at: Date;
     constructor(data: UnsubscribeData);
 }
+declare type TModel = typeof Bounce | typeof Complaint | typeof Unsubscribe;
 export default class SuppressionClient {
     request: any;
     models: {