mailgun.js 4.1.4 → 4.2.1

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.
 
+### [4.2.1](https://github.com/mailgun/mailgun.js/compare/v4.2.0...v4.2.1) (2022-02-04)
+
+
+### Bug Fixes
+
+* Remove redundant logs ([27142a0](https://github.com/mailgun/mailgun.js/commits/27142a0f0af6bbb18463a46c50f36dce66f85ad5))
+
+
+### Other changes
+
+* Update readme ([ea795e6](https://github.com/mailgun/mailgun.js/commits/ea795e62eea82d575907691a570f867b863c0fb9))
+
+## [4.2.0](https://github.com/mailgun/mailgun.js/compare/v4.1.6...v4.2.0) (2022-02-02)
+
+
+### Features
+
+* Add domains tags functionality ([6cc41e3](https://github.com/mailgun/mailgun.js/commits/6cc41e30f20f70d9dc4a4ec247a600e553d706f4))
+
+
+### Other changes
+
+* Add tests for new functionality ([e741689](https://github.com/mailgun/mailgun.js/commits/e741689123de9648c35eee4e31f95bb38b86aa78))
+
+### [4.1.6](https://github.com/mailgun/mailgun.js/compare/v4.1.5...v4.1.6) (2022-01-24)
+
+
+### Bug Fixes
+
+* Update "mocha" to fix "nanoid" dependency ([4e122cf](https://github.com/mailgun/mailgun.js/commits/4e122cffc6d35967bf70380a9003938949a6f442))
+* Update "typedoc" version to fix "marked" version ([a84a252](https://github.com/mailgun/mailgun.js/commits/a84a25231e877313c2756cefd89da64d98065196))
+
+
+### Other changes
+
+* Recompile documentation ([f068746](https://github.com/mailgun/mailgun.js/commits/f0687462e35c237909fbf133a0c563da4a87f6bd))
+
+### [4.1.5](https://github.com/mailgun/mailgun.js/compare/v4.1.4...v4.1.5) (2022-01-24)
+
 ### [4.1.4](https://github.com/mailgun/mailgun.js/compare/v4.1.3...v4.1.4) (2021-12-23)
 
 

package/README.md

@@ -43,16 +43,6 @@ const mailgun = new Mailgun(formData);
 const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
 ```
 
-To use `validate` and `parse` methods, you must additionally include `public_key`. If you're using only those methods, `key` can be an empty string.
-
-```js
-const mg = mailgun.client({
-  username: 'api',
-  key: process.env.MAILGUN_API_KEY || '',
-  public_key: process.env.MAILGUN_PUBLIC_KEY || 'pubkey-yourkeyhere'
-});
-```
-
 In the case your mailgun account is eu hosted you would need to define eu's subdomain as `url` in mailgun's Client constructor:
 
 ```js
@@ -102,12 +92,15 @@ The following service methods are available to instantiated clients. The example
       - [destroy](#destroy-2)
     - [validate](#validate)
       - [get](#get-5)
-    - [parse](#parse)
-      - [get](#get-6)
-    - [lists](#lists)
-      - [list](#list-4)
-      - [get](#get-7)
+    - [Multiple Validation](#multiple-validation)
       - [create](#create-5)
+      - [list](#list-4)
+      - [get](#get-5)
+      - [destroy](#destroy-3)
+    - [lists](#lists)
+      - [list](#list-5)
+      - [get](#get-6)
+      - [create](#create-6)
       - [update](#update-2)
       - [destroy](#destroy-3)
     - [mailListMembers](#maillistmembers)
@@ -136,7 +129,7 @@ Method naming conventions:
 
 #### create
 
-`mg.messages.create(domain, data)` - [api docs](https://documentation.mailgun.com/api-sending.html#sending)
+`mg.messages.create(domain, data)` - [api docs](https://documentation.mailgun.com/en/latest/api-sending.html)
 
 Options:
 
@@ -1334,7 +1327,7 @@ Promise Returns: response body
 Example:
 
 ```js
-mg.validate.get('alice@example.com')
+mg.validate.get('foo@mailgun.net')
   .then(data => console.log(data)) // logs response body
   .catch(err => console.log(err)); // logs any error
 ```
@@ -1350,29 +1343,137 @@ Promise Returns: response body
 }
 ```
 
-### parse
+### Multiple Validation
+https://documentation.mailgun.com/en/latest/api-email-validation.html#email-validation
+#### create
+`mg.validate.multipleValidation.create('name_of_the_list', { file })`
 
-#### get
+```js
+const fsPromises = require('fs').promises;
+const filepath = path.resolve(__dirname, '../path_to_your_file_with_emails_list.csv');
 
-`mg.parse.get(addresses, enableDnsEspChecks)`
+...
 
-Example:
+(async () => {
+  try {
+    const file = {
+      filename: 'test.csv',
+      data: await fsPromises.readFile(filepath)
+    };
+
+    const validateBulkResult = await mg.validate.multipleValidation.create('name_of_the_list', { file });
+    console.log('validateBulkResult', validateBulkResult);
+  } catch (error) {
+    console.error(error);
+  }
+})();
+```
+
+Response shape:
+```JSON
+ {
+  "id": "name_of_the_list",
+  "message": "The validation job was submitted."
+}
+```
+
+#### list
+
+`mg.validate.multipleValidation.list()`
 
 ```js
-mg.parse.get('Alice <alice@example.com>, example.com', true)
+mg.validate.multipleValidation.list()
   .then(data => console.log(data)) // logs response body
   .catch(err => console.log(err)); // logs any error
 ```
 
-Promise Returns: response body
+Response shape:
+```JSON
+{
+  "jobs": [
+    {
+      "created_at": 1643965937,
+      "download_url": {
+        "csv": "csv-url",
+        "json": "json-url"
+      },
+      "id": "name_of_the_list",
+      "quantity": 40,
+      "records_processed": 40,
+      "status": "uploaded",
+      "summary": {
+        "result": {
+          "catch_all": 0,
+          "deliverable": 0,
+          "do_not_send": 0,
+          "undeliverable": 0,
+          "unknown": 40
+        },
+        "risk": { "high": 0, "low": 0, "medium": 0, "unknown": 40 }
+      }
+    }
+  ],
+  "paging": {
+    "first": "https://api.mailgun.net/v4/address/validate/bulk?limit=100&page=first&pivot=",
+    "last": "https://api.mailgun.net/v4/address/validate/bulk?limit=100&page=last&pivot=",
+    "next": "https://api.mailgun.net/v4/address/validate/bulk?limit=100&page=next&pivot=b4808b5b-1111-2222-3333-6cd0b63f41ea",
+    "prev": "https://api.mailgun.net/v4/address/validate/bulk?limit=100&page=prev&pivot="
+  },
+  "total": 1
+}
+```
+
+#### get
+
+`mg.validate.multipleValidation.get('name_of_the_list')`
 
+```js
+mg.validate.multipleValidation.get('name_of_the_list')
+  .then(data => console.log(data)) // logs response body
+  .catch(err => console.log(err)); // logs any error
 ```
+
+Response shape:
+```JSON
+{
+  "created_at": 1643965937,
+  "download_url": {
+    "csv": "csv-url",
+    "json": "json-url"
+  },
+  "id": "name_of_the_list",
+  "quantity": 40,
+  "records_processed": 40,
+  "status": "uploaded",
+  "summary": {
+    "result": {
+      "catch_all": 0,
+      "deliverable": 0,
+      "do_not_send": 0,
+      "undeliverable": 0,
+      "unknown": 40
+    },
+    "risk": { "high": 0, "low": 0, "medium": 0, "unknown": 40 }
+  }
+}
+```
+
+#### destroy
+
+`mg.validate.multipleValidation.destroy('name_of_the_list');`
+
+cancels bulk validation job
+```js
+mg.validate.multipleValidation.destroy('name_of_the_list');
+  .then(data => console.log(data)) // logs response body
+  .catch(err => console.log(err)); // logs any error
+```
+
+Response shape:
+```JSON
 {
-  parsed: [],
-  unparseable: [
-    'Alice <alice@example.com>',
-    'example.com'
-  ]
+  "body": "Validation job canceled.",
+  "status": 200
 }
 ```
 

package/dist/lib/domains.d.ts

@@ -6,6 +6,8 @@ import { IDomainCredentials } from './interfaces/DomainCredentials';
 import { IDomainTemplatesClient } from './interfaces/DomainTemplates';
 import DomainCredentialsClient from './domainsCredentials';
 import DomainTemplatesClient from './domainsTemplates';
+import { IDomainTagsClient } from './interfaces/DomainTags';
+import DomainTagsClient from './domainsTags';
 export declare class Domain {
     name: string;
     require_tls: boolean;
@@ -25,7 +27,8 @@ export default class DomainClient {
     request: Request;
     domainCredentials: IDomainCredentials;
     domainTemplates: IDomainTemplatesClient;
-    constructor(request: Request, domainCredentialsClient: DomainCredentialsClient, domainTemplatesClient: DomainTemplatesClient);
+    domainTags: IDomainTagsClient;
+    constructor(request: Request, domainCredentialsClient: DomainCredentialsClient, domainTemplatesClient: DomainTemplatesClient, domainTagsClient: DomainTagsClient);
     private _parseMessage;
     private _parseDomainList;
     private _parseDomain;

package/dist/lib/domainsTags.d.ts

@@ -0,0 +1,34 @@
+import Request from './request';
+import { DomainTagCountriesAggregation, DomainTagDevicesAggregation, DomainTagProvidersAggregation, DomainTagsItem, DomainTagsItemInfo, DomainTagsList, DomainTagsMessageRes, DomainTagsQuery, DomainTagsStatisticQuery, DomainTagStatAPIResponse, DomainTagStatisticItem, DomainTagStatisticResult, IDomainTagsClient, Resolution } from './interfaces/DomainTags';
+export declare class DomainTag implements DomainTagsItem {
+    tag: string;
+    description: string;
+    'first-seen': Date;
+    'last-seen': Date;
+    constructor(tagInfo: DomainTagsItemInfo);
+}
+export declare class DomainTagStatistic implements DomainTagStatisticResult {
+    tag: string;
+    description: string;
+    start: Date;
+    end: Date;
+    resolution: Resolution;
+    stats: DomainTagStatisticItem[];
+    constructor(tagStatisticInfo: DomainTagStatAPIResponse);
+}
+export default class DomainTagsClient implements IDomainTagsClient {
+    baseRoute: string;
+    request: Request;
+    constructor(request: Request);
+    private _parsePageLinks;
+    private _parseDomainTagsList;
+    private _parseTagStatistic;
+    list(domain: string, query?: DomainTagsQuery): Promise<DomainTagsList>;
+    get(domain: string, tag: string): Promise<DomainTagsItem>;
+    update(domain: string, tag: string, description: string): Promise<DomainTagsMessageRes>;
+    destroy(domain: string, tag: string): Promise<DomainTagsMessageRes>;
+    statistic(domain: string, tag: string, query: DomainTagsStatisticQuery): Promise<DomainTagStatistic>;
+    countries(domain: string, tag: string): Promise<DomainTagCountriesAggregation>;
+    providers(domain: string, tag: string): Promise<DomainTagProvidersAggregation>;
+    devices(domain: string, tag: string): Promise<DomainTagDevicesAggregation>;
+}

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

@@ -0,0 +1,228 @@
+import { DomainTagStatistic } from '../domainsTags';
+export declare enum Resolution {
+    HOUR = "hour",
+    DAY = "day",
+    MONTH = "month"
+}
+export interface DomainTagsQuery {
+    limit: number;
+}
+export interface DomainTagsStatisticQuery {
+    event: string;
+    start?: number;
+    end?: number;
+    resolution?: Resolution;
+    duration?: string;
+}
+export interface DomainTagsItemInfo {
+    tag: string;
+    description: string;
+    'first-seen': string;
+    'last-seen': string;
+}
+export interface DomainTagsItem {
+    tag: string;
+    description: string;
+    'first-seen': Date;
+    'last-seen': Date;
+}
+export interface PagesList {
+    previous: string;
+    first: string;
+    last: string;
+    next: string;
+}
+export interface ParsedPage {
+    id: string;
+    url: string;
+}
+export interface ParsedPagesList {
+    previous: ParsedPage;
+    first: ParsedPage;
+    last: ParsedPage;
+    next: ParsedPage;
+}
+export interface TagsPage {
+    id: string;
+    url: string;
+}
+export interface PagesListAccumulator {
+    [index: string]: TagsPage;
+}
+export interface DomainTagsResponseData {
+    status: number;
+    body: {
+        items: DomainTagsItemInfo[];
+        paging: PagesList;
+    };
+}
+export interface DomainTagsList {
+    items: DomainTagsItem[];
+    pages: ParsedPagesList;
+}
+export interface DomainTagsMessageRes {
+    message: string;
+    status?: number;
+}
+export interface DomainTagAPIResponseStatsItem {
+    time: string;
+    accepted?: {
+        incoming: number;
+        outgoing: number;
+        total: number;
+    };
+    delivered?: {
+        smtp: number;
+        http: number;
+        optimized: number;
+        total: number;
+    };
+    opened?: {
+        total: number;
+    };
+    failed?: {
+        temporary: {
+            espblock: number;
+            total: number;
+        };
+        permanent: {
+            'suppress-bounce': number;
+            'suppress-unsubscribe': number;
+            'suppress-complaint': number;
+            bounce: number;
+            'delayed-bounce': number;
+            webhook: number;
+            optimized: number;
+            total: number;
+        };
+    };
+    clicked?: {
+        total: number;
+    };
+    unsubscribed?: {
+        total: number;
+    };
+    complained?: {
+        total: number;
+    };
+    stored?: {
+        total: number;
+    };
+}
+export interface DomainTagStatAPIResponse {
+    body: {
+        tag: string;
+        description: string;
+        start: string;
+        end: string;
+        resolution: Resolution;
+        stats: DomainTagAPIResponseStatsItem[];
+    };
+}
+export interface DomainTagStatisticItem extends Omit<DomainTagAPIResponseStatsItem, 'time'> {
+    time: Date;
+}
+export interface DomainTagStatisticResult {
+    tag: string;
+    description: string;
+    start: Date;
+    end: Date;
+    resolution: Resolution;
+    stats: DomainTagStatisticItem[];
+}
+export interface DomainTagCountriesAPIResponse {
+    body: {
+        tag: string;
+        country: {
+            [key: string]: {
+                clicked: number;
+                complained: number;
+                opened: number;
+                unique_clicked: number;
+                unique_opened: number;
+                unsubscribed: number;
+            };
+        };
+    };
+}
+export interface DomainTagCountriesAggregation {
+    tag: string;
+    country: {
+        [key: string]: {
+            clicked: number;
+            complained: number;
+            opened: number;
+            unique_clicked: number;
+            unique_opened: number;
+            unsubscribed: number;
+        };
+    };
+}
+export interface DomainTagProvidersAPIResponse {
+    body: {
+        tag: string;
+        provider: {
+            [key: string]: {
+                accepted: number;
+                clicked: number;
+                complained: number;
+                delivered: number;
+                opened: number;
+                unique_clicked: number;
+                unique_opened: number;
+                unsubscribed: number;
+            };
+        };
+    };
+    status: number;
+}
+export interface DomainTagProvidersAggregation {
+    tag: string;
+    provider: {
+        [key: string]: {
+            accepted: number;
+            clicked: number;
+            complained: number;
+            delivered: number;
+            opened: number;
+            unique_clicked: number;
+            unique_opened: number;
+            unsubscribed: number;
+        };
+    };
+}
+export interface DeviceStatistic {
+    clicked: number;
+    complained: number;
+    opened: number;
+    unique_clicked: number;
+    unique_opened: number;
+    unsubscribed: number;
+}
+export interface DevicesTypes {
+    desktop: DeviceStatistic;
+    mobile: DeviceStatistic;
+    tablet: DeviceStatistic;
+    unknown: DeviceStatistic;
+}
+export interface DomainTagDevicesAPIResponse {
+    body: {
+        tag: string;
+        device: DevicesTypes;
+    };
+    status: number;
+}
+export interface DomainTagDevicesAggregation {
+    tag: string;
+    device: DevicesTypes;
+}
+export interface IDomainTagsClient {
+    list(domain: string): Promise<DomainTagsList>;
+    get(domain: string, tag: string): Promise<DomainTagsItem>;
+    update(domain: string, tag: string, description: string): Promise<DomainTagsMessageRes>;
+    destroy(domain: string, tag: string): Promise<DomainTagsMessageRes>;
+    statistic(domain: string, tag: string, query: DomainTagsStatisticQuery): Promise<DomainTagStatistic>;
+    countries(domain: string, tag: string): Promise<DomainTagCountriesAggregation>;
+    providers(domain: string, tag: string): Promise<DomainTagProvidersAggregation>;
+    devices(domain: string, tag: string): Promise<DomainTagDevicesAggregation>;
+}