mailgun.js 3.5.6 → 3.6.0

package/.eslintrc

@@ -22,6 +22,7 @@
   "settings": {
     "import/resolver": "webpack"
   },
+  "ignorePatterns": ["docs/assets/js/*", "dist/**"],
   "rules": {
     "tsdoc/syntax": "warn",
     "comma-dangle": 0,
@@ -32,6 +33,9 @@
     "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 }],
+    "@typescript-eslint/no-var-requires": {
+      "ignorePatterns": ["**/webpack/*.js"]
+    }
   }
-}
+}

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 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.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)
+
+
+### Features
+
+* Update index.ts export to fix commonJs imports ([246c046](https://github.com/mailgun/mailgun-js/commits/246c046619c593e5f13abe1ff0414fe9c9524cf9))
+
+
+### Other changes
+
+* Add examples of sending files to the readme ([a922b35](https://github.com/mailgun/mailgun-js/commits/a922b3590a6afd02e15650a2d6acf7b43933bb49))
+
+### [3.5.7](https://github.com/mailgun/mailgun-js/compare/v3.5.6...v3.5.7) (2021-08-16)
+
+
+### Bug Fixes
+
+* Minification is messing up node-fetch's detection of abort signals ([79564f2](https://github.com/mailgun/mailgun-js/commits/79564f2ea46406e2df4ff911a8e49da44be86260))
+
 ### [3.5.6](https://github.com/mailgun/mailgun-js/compare/v3.5.5...v3.5.6) (2021-08-12)
 
 

package/README.md

@@ -11,7 +11,7 @@ __Table of Contents__
   - [Setup Client](#setup-client)
   - [Methods](#methods)
   - [Browser Demo](#browser-demo)
-  - [Examples](https://github.com/mailgun/mailgun-js/tree/c379f79ea2a2e0f825103751a3a102d8bdd3dd1b/example)
+  - [Examples](https://github.com/mailgun/mailgun-js/tree/master/examples)
 - [Development](#development)
   - [Requirements](#requirements)
   - [Build](#build)
@@ -125,42 +125,6 @@ Method naming conventions:
 
 `mg.messages.create(domain, data)` - [api docs](https://documentation.mailgun.com/api-sending.html#sending)
 
-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",
-    message: "<mime encoded string here>"
-  })
-  .then(msg => console.log(msg)) // logs response data
-  .catch(err => console.log(err)); // logs any error
-```
-
-Promise Returns:
-
-```
-{
-  id: '<20151025002517.117282.79817@sandbox-123.mailgun.org>',
-  message: 'Queued. Thank you.'
-}
-```
-
 Options:
 
 Parameter         | Description
@@ -181,6 +145,248 @@ o:tracking-opens  | Toggles opens tracking on a per-message basis. Has higher pr
 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.
 
+
+- 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:
+
+- Node.js example of send file as an attachment
+
+  ```js
+    const fsPromises = require('fs').promises;
+    const path = require('path');
+    const filepath = path.resolve(__dirname, '../test.pdf');
+    let messageParams = {
+        from: "Excited User <mailgun@sandbox-123.mailgun.org>",
+        to: ["test@example.com"],
+        subject: "Test subject",
+        text: "Hello here is a file in the attachment"
+    }
+
+    fsPromises.readFile(filepath)
+    .then(data => {
+      const file = {
+          filename: 'test-rename.pdf',
+          data
+      }
+      messageParams.attachment = file;
+      return mg.messages.create('sandbox-123.mailgun.org', messageParams);
+    })
+    .then(response => {
+        console.log(response);
+    })
+  ```
+- Node.js example of send multiple files as an attachment
+  ```js
+  const fsPromises = require('fs').promises;
+  const path = require('path');
+  const filepath = path.resolve(__dirname, '../test.pdf');
+  const filepath1 = path.resolve(__dirname, '../test.jpg');
+
+  let messageParams = {
+      from: "Excited User <mailgun@sandbox-123.mailgun.org>",
+      to: ["test@example.com"],
+      subject: "Test subject",
+      text: "Test message"
+  }
+
+  (async () =>{
+      try {
+          const firstFile = {
+              filename: 'test.pdf',
+              data: await fsPromises.readFile(filepath)
+          }
+
+          const secondFile = {
+              filename: 'test.jpg',
+              data: await fsPromises.readFile(filepath1)
+          }
+
+          messageParams.attachment = [firstFile, secondFile];
+          const result =  await mg.messages.create('sandbox-123.mailgun.org', messageParams);
+          console.log(result);
+          } catch (error) {
+              console.error(error);
+          }
+  })()
+  ```
+- Node.js example of send file as inline image
+  ```js
+    const fsPromises = require('fs').promises;
+    const path = require('path');
+    const filepath = path.resolve(__dirname, '../test.jpg');
+    let messageParams = {
+        from: "Excited User <mailgun@sandbox-123.mailgun.org>",
+        to: ["test@example.com"],
+        subject: "Test subject",
+        html: '<div><img alt="image" id="1" src="cid:test.jpg"/></div> Some extra text'
+    }
+
+    fsPromises.readFile(filepath)
+    .then(data => {
+      const file = {
+          filename: 'test.jpg',
+          data
+      }
+
+      messageParams.inline = file;
+      return mg.messages.create('sandbox-123.mailgun.org', messageParams);
+    })
+    .then(response => {
+        console.log(response);
+    })
+  ```
+
+- Browser example of send file
+
+  Before sending the file you need to somehow get the Blob of the file.
+  Usually can get it from the onChange event of input tag with type file.
+  ```js
+  const handleFileSelected = async (event) => {
+    const files = Array.from(event.target.files)
+    const fileBuffer = await files[0];
+  }
+  <input type="file" onChange={handleFileSelected} name="file-uploader"/>
+  ```
+
+  Then you can use the same approach as shown above for node.js apps.
+  ```js
+    const file = {
+      filename: 'test.pdf',
+      data: fileBuffer
+    };
+
+    let messageParams = {
+      from: "Excited User <mailgun@sandbox-123.mailgun.org>",
+      to: ["test@example.com"],
+      subject: "Test subject",
+      text: "Hello here is a file in the attachment",
+      attachment: file
+    };
+
+    const res = await mg.messages.create(DOMAIN, messageParams);
+  ```
+  Promise Returns:
+
+  ```js
+  {
+    id: '<20151025002517.117282.79817@sandbox-123.mailgun.org>',
+    message: 'Queued. Thank you.'
+  }
+  ```
+#### Templates
+
+Mailgun’s templates uses a fork of the very popular template engine [handlebars](https://handlebarsjs.com/).
+
+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
 
 #### list

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

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