mailgun.js 9.2.1 → 9.4.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 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.
 
+## [9.4.0](https://github.com/mailgun/mailgun.js/compare/v9.3.0...v9.4.0) (2023-12-13)
+
+
+### Features
+
+* Add subaccounts ([3ca1d56](https://github.com/mailgun/mailgun.js/commits/3ca1d56955f7651bcba758c75cdbee3be48d5748))
+
+
+### Bug Fixes
+
+* **deps-dev:** bump @babel/traverse from 7.22.5 to 7.23.2 ([53f3e8f](https://github.com/mailgun/mailgun.js/commits/53f3e8fd673857b75ab0844bb1e04e016dad6ed5))
+* **deps:** bump axios from 1.3.3 to 1.6.0 ([729032d](https://github.com/mailgun/mailgun.js/commits/729032d7a19ec307255c401bd698f5e7835925fb))
+
+
+### Other changes
+
+* Update the formatting, merge headers to avoid overriding ([6e46eca](https://github.com/mailgun/mailgun.js/commits/6e46ecac1742660673931a99735988e4ffb046ce))
+
+## [9.3.0](https://github.com/mailgun/mailgun.js/compare/v9.2.1...v9.3.0) (2023-09-18)
+
+
+### Features
+
+* Update webhook.update method to allow multiple URLs ([633bce9](https://github.com/mailgun/mailgun.js/commits/633bce9f2a7a704972251af16aeafdc73d5cbbde))
+
+
+### Other changes
+
+* Update docs ([3a3b8d8](https://github.com/mailgun/mailgun.js/commits/3a3b8d8a9ced9f6a2d63ce42010980d20cfaf815))
+
 ### [9.2.1](https://github.com/mailgun/mailgun.js/compare/v9.2.0...v9.2.1) (2023-08-16)
 
 

package/Classes/MailgunClient.d.ts

@@ -1,6 +1,5 @@
-import { MailgunClientOptions } from '../Types/MailgunClient';
-import { InputFormData } from '../Types/Common';
-import { IDomainsClient, IWebHooksClient, IMailgunClient, IMailingListsClient, IEventClient, IStatsClient, ISuppressionClient, IMessagesClient, IRoutesClient, IValidationClient, IIPsClient, IIPPoolsClient } from '../Interfaces';
+import { MailgunClientOptions, InputFormData } from '../Types';
+import { IDomainsClient, IWebHooksClient, IMailgunClient, IMailingListsClient, IEventClient, IStatsClient, ISuppressionClient, IMessagesClient, IRoutesClient, IValidationClient, IIPsClient, IIPPoolsClient, ISubaccountsClient } from '../Interfaces';
 export default class MailgunClient implements IMailgunClient {
     private request;
     domains: IDomainsClient;
@@ -14,5 +13,8 @@ export default class MailgunClient implements IMailgunClient {
     ips: IIPsClient;
     ip_pools: IIPPoolsClient;
     lists: IMailingListsClient;
+    subaccounts: ISubaccountsClient;
     constructor(options: MailgunClientOptions, formData: InputFormData);
+    setSubaccount(subaccountId: string): void;
+    resetSubaccount(): void;
 }

package/Classes/Messages.d.ts

@@ -1,4 +1,4 @@
-import { MailgunMessageData, MessagesSendAPIResponse, MessagesSendResult } from '../Types/Messages';
+import { MailgunMessageData, MessagesSendAPIResponse, MessagesSendResult } from '../Types';
 import Request from './common/Request';
 import { IMessagesClient } from '../Interfaces';
 export default class MessagesClient implements IMessagesClient {

package/Classes/Subaccounts.d.ts

@@ -0,0 +1,13 @@
+import Request from './common/Request';
+import { ISubaccountsClient } from '../Interfaces';
+import { SubaccountListResponseData, SubaccountResponseData, SubaccountsQuery } from '../Types';
+export default class SubaccountsClient implements ISubaccountsClient {
+    request: Request;
+    static SUBACCOUNT_HEADER: string;
+    constructor(request: Request);
+    list(query?: SubaccountsQuery): Promise<SubaccountListResponseData>;
+    get(id: string): Promise<SubaccountResponseData>;
+    create(name: string): Promise<SubaccountResponseData>;
+    enable(id: string): Promise<SubaccountResponseData>;
+    disable(id: string): Promise<SubaccountResponseData>;
+}

package/Classes/Webhooks.d.ts

@@ -5,7 +5,8 @@ import Request from './common/Request';
 export declare class Webhook implements WebhookResult {
     id: string;
     url: string | undefined;
-    constructor(id: string, url: string | undefined);
+    urls: string[];
+    constructor(id: string, url: string | undefined, urls: string[]);
 }
 export default class WebhooksClient implements IWebHooksClient {
     request: Request;
@@ -16,6 +17,6 @@ export default class WebhooksClient implements IWebHooksClient {
     list(domain: string, query: WebhooksQuery): Promise<WebhookList>;
     get(domain: string, id: WebhooksIds): Promise<WebhookResult>;
     create(domain: string, id: string, url: string, test?: boolean): Promise<WebhookResult | WebhookValidationResponse>;
-    update(domain: string, id: string, url: string): Promise<WebhookResult>;
+    update(domain: string, id: string, urlValues: string | string[]): Promise<WebhookResult>;
     destroy(domain: string, id: string): Promise<WebhookResult>;
 }

package/Classes/common/Request.d.ts

@@ -1,6 +1,5 @@
 import * as NodeFormData from 'form-data';
-import { RequestOptions, InputFormData, APIResponse } from '../../Types/Common';
-import { IpPoolDeleteData } from '../../Types/IPPools';
+import { RequestOptions, InputFormData, APIResponse, IpPoolDeleteData } from '../../Types';
 declare class Request {
     private username;
     private key;
@@ -14,6 +13,8 @@ declare class Request {
     private getResponseBody;
     private joinAndTransformHeaders;
     private makeHeadersFromObject;
+    setSubaccountHeader(subaccountId: string): void;
+    resetSubaccountHeader(): void;
     query(method: string, url: string, query?: Record<string, unknown> | Array<Array<string>>, options?: Record<string, unknown>): Promise<APIResponse>;
     command(method: string, url: string, data?: Record<string, unknown> | Record<string, unknown>[] | string | NodeFormData | FormData, options?: Record<string, unknown>, addDefaultHeaders?: boolean): Promise<APIResponse>;
     get(url: string, query?: Record<string, unknown> | Array<Array<string>>, options?: Record<string, unknown>): Promise<APIResponse>;

package/Interfaces/MailgunClient/IMailgunClient.d.ts

@@ -9,6 +9,7 @@ import { IValidationClient } from '../Validations';
 import { IIPsClient } from '../IPs';
 import { IIPPoolsClient } from '../IPPools';
 import { IMailingListsClient } from '../MailingLists';
+import { ISubaccountsClient } from '../Subaccounts';
 export interface IMailgunClient {
     domains: IDomainsClient;
     webhooks: IWebHooksClient;
@@ -21,4 +22,7 @@ export interface IMailgunClient {
     ips: IIPsClient;
     ip_pools: IIPPoolsClient;
     lists: IMailingListsClient;
+    subaccounts: ISubaccountsClient;
+    setSubaccount(subaccountId: string): void;
+    resetSubaccount(): void;
 }

package/Interfaces/Subaccounts/ISubaccountsClient.d.ts

@@ -0,0 +1,8 @@
+import { SubaccountListResponseData, SubaccountResponseData, SubaccountsQuery } from '../../Types';
+export interface ISubaccountsClient {
+    list(query?: SubaccountsQuery): Promise<SubaccountListResponseData>;
+    get(id: string): Promise<SubaccountResponseData>;
+    create(name: string): Promise<SubaccountResponseData>;
+    disable(id: string): Promise<SubaccountResponseData>;
+    enable(id: string): Promise<SubaccountResponseData>;
+}

package/Interfaces/Subaccounts/index.d.ts

@@ -0,0 +1 @@
+export * from './ISubaccountsClient';

package/Interfaces/Webhooks/IWebHooksClient.d.ts

@@ -4,6 +4,6 @@ export interface IWebHooksClient {
     list(domain: string, query: WebhooksQuery): Promise<WebhookList>;
     get(domain: string, id: WebhooksIds): Promise<WebhookResult>;
     create(domain: string, id: string, url: string, test: boolean): Promise<WebhookResult | WebhookValidationResponse>;
-    update(domain: string, id: string, url: string): Promise<WebhookResult>;
+    update(domain: string, id: string, url: string | string[]): Promise<WebhookResult>;
     destroy(domain: string, id: string): Promise<WebhookResult>;
 }

package/Interfaces/index.d.ts

@@ -11,3 +11,4 @@ export * from './Messages';
 export * from './Routes';
 export * from './IPs';
 export * from './IPPools';
+export * from './Subaccounts';

package/README.md

@@ -10,6 +10,7 @@ __Table of Contents__
   - [Install](#install)
   - [Setup Client](#setup-client)
     - [Available Imports](#imports)
+    - [Using Subaccounts](#using-subaccounts)
     - [Types imports](#types-imports)
     - [Interfaces and Enums imports](#interfaces-and-enums-imports)
   - [Generated docs](#generated-docs)
@@ -56,6 +57,17 @@ Once the package is installed, you can import the library using `import` or `req
   const mailgun = new Mailgun(FormData);
   const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
 ```
+### Using Subaccounts
+Primary accounts can make API calls on behalf of their subaccounts. [API documentation](https://documentation.mailgun.com/en/latest/subaccounts.html#subaccounts)
+```js
+  import * as FormData from 'form-data';
+  import Mailgun from 'mailgun.js';
+  const mailgun = new Mailgun(FormData);
+  const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
+  mg.setSubaccount('subaccount-id');
+  // then, if you need to reset it back to the primary account:
+  mg.resetSubaccount();
+```
 ### Types imports
 Starting from version **9.0.0.** Types can be includes as named import:
 ```TS
@@ -152,6 +164,12 @@ The following service methods are available to instantiated clients. The example
       - [createMembers](#createmembers)
       - [updateMember](#updatemember)
       - [destroyMember](#destroymember)
+    - [subaccounts](#subaccounts)
+      - [list](#list-6)
+      - [get](#get-8)
+      - [create](#create-7)
+      - [enable](#enable)
+      - [disable](#disable)
   - [Navigation thru lists](#navigation-thru-lists)
   - [Browser Demo](#browser-demo)
 - [Development](#development)
@@ -1335,7 +1353,7 @@ Method naming conventions:
 
   ```JS
   {
-    'open': { 'url': 'http://requestb.in' }
+    'open': { 'url': 'http://requestb.in', 'urls': ['trackclick.com'] }
   }
   ```
 
@@ -1355,7 +1373,7 @@ Method naming conventions:
 
   ```JS
   {
-    'open': { 'url': 'http://requestb.in' }
+    'open': { 'url': 'http://requestb.in', 'urls': ['http://requestb.in'] }
   }
   ```
 
@@ -1392,10 +1410,24 @@ Method naming conventions:
 
   ```JS
   {
-    'open': { 'url': 'http://requestb.in' }
+    'open': { 'url': 'http://requestb.in', 'urls': ['http://requestb.in'] }
   }
   ```
 
+  ```js
+  mg.webhooks.update('foobar.example.com', 'open', ['http://requestb.in', 'http://requestb1.in' ]) // bounce, deliver, drop, spam, unsubscribe, click, open
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns:
+  ```JS
+  {
+    'open': { 'url': 'http://requestb.in', 'urls': ['http://requestb.in', 'http://requestb1.in'] }
+  }
+  ```
+
+
 - #### destroy
 
   `mg.webhooks.destroy(domain, id)`
@@ -1412,7 +1444,7 @@ Method naming conventions:
 
   ```JS
   {
-    'open': { 'url': 'http://requestb.in' }
+    'open': { 'url': 'http://requestb.in', 'urls': ['http://requestb.in']}
   }
   ```
 
@@ -2030,6 +2062,115 @@ A client to manage members within a specific mailing list.
     message: 'Mailing list member has been deleted'
   }
   ```
+### Subaccounts
+
+  A client to manage subaccounts.
+
+- #### list
+
+  `mg.subaccounts.list(query)` - [api docs](https://documentation.mailgun.com/en/latest/subaccounts.html)
+
+  Example:
+
+  ```js
+  mg.subaccounts.list()
+    .then(subaccounts => console.log(subaccounts)) // logs array of subaccounts
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns: array of Subaccounts instances
+
+  ```JS
+  [
+    { id: "XYZ", name: "test.subaccount1", status: "open" },
+    { id: "YYY", name: "test.subaccount2", status: "open" }
+  ]
+  ```
+
+  Query data may have next properties:
+
+  | Property | Description                                                            |
+  |:---------|:-----------------------------------------------------------------------|
+  | limit    | Maximum number of records to return. (10 by default)                   |
+  | skip     | Number of records to skip. (0 by default)                              |
+  | sort     | "asc" or "desc".                                                       |
+  | enabled  | Returns all enabled/disabled subaccounts. (Defaults to all if omitted) |
+
+- #### get
+
+  `mg.subaccounts.get(subaccount_id)`
+
+  Example:
+
+  ```JS
+  mg.subaccounts.get('123')
+    .then(subaccount => console.log(subaccount)) // logs subaccount object
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns: Subaccount instance
+
+  ```JS
+  { id: "123", name: "test.subaccount1", status: "open" }
+  ```
+
+- #### create
+
+  `mg.subaccounts.create(name)`
+
+  Example:
+
+  ```js
+  mg.subaccounts.create('foobar')
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns: Subaccount instance
+
+  ```JS
+  { id: "123", name: "foobar", status: "open" }
+  ```
+
+  Create method accepts data object with next properties:
+
+  | Parameter 	 | Description 	                                             |
+  |-------------|-----------------------------------------------------------|
+  | name 	     | Name of the subaccount being created (ex. 'mysubaccount') 	 |
+
+- #### enable
+
+  `mg.subaccounts.enable(subaccount_id)`
+
+  Example:
+
+  ```js
+  mg.subaccounts.enable('123')
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+  Promise returns: Subaccount instance
+
+  ```JS
+  { id: "123", name: "foobar", status: "open" }
+  ```
+
+- #### disable
+
+  `mg.subaccounts.disable(subaccount_id)`
+
+  Example:
+
+  ```js
+  mg.subaccounts.disable('123')
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+  Promise returns: Subaccount instance
+
+  ```JS
+  { id: "123", name: "foobar", status: "disabled" }
+  ```
 
 ## Navigation thru lists
   Most of the methods that return items in a list support pagination.
@@ -2197,7 +2338,6 @@ A client to manage members within a specific mailing list.
     );
     ```
 
-
 ## Browser Demo
 
 ![image](https://cloud.githubusercontent.com/assets/399776/10718632/e8fe56e4-7b34-11e5-84c8-cfcfde978711.png)

package/Types/Subaccounts/Subaccounts.d.ts

@@ -0,0 +1,18 @@
+export type SubaccountsQuery = {
+    enabled?: boolean;
+    limit?: number;
+    skip?: number;
+    sort?: 'asc' | 'desc';
+};
+export type SubaccountListItem = {
+    id: string;
+    name: string;
+    status: string;
+};
+export type SubaccountListResponseData = {
+    subaccounts: SubaccountListItem[];
+    total: number;
+};
+export type SubaccountResponseData = {
+    subaccount: SubaccountListItem;
+};

package/Types/Subaccounts/index.d.ts

@@ -0,0 +1 @@
+export * from './Subaccounts';

package/Types/Webhooks/Webhooks.d.ts

@@ -25,5 +25,9 @@ export type WebhookValidationResponse = {
 };
 export type WebhookResult = {
     id: string;
+    /**
+     * @deprecated url property is deprecated. Use "urls" instead.
+     */
     url: string | undefined;
+    urls: string[];
 };

package/Types/index.d.ts

@@ -8,6 +8,7 @@ export * from './MailingLists';
 export * from './Messages';
 export * from './Routes';
 export * from './Stats';
+export * from './Subaccounts';
 export * from './Suppressions';
 export * from './Validations';
 export * from './Webhooks';

package/index.d.ts

@@ -1,6 +1,5 @@
 import { IMailgunClient } from './Interfaces';
-import { InputFormData } from './Types/Common';
-import { MailgunClientOptions } from './Types/MailgunClient';
+import { InputFormData, MailgunClientOptions } from './Types';
 export * as Enums from './Enums';
 export * from './Types';
 export * as Interfaces from './Interfaces';