mailgun.js 12.4.1 → 12.5.0

package/README.md

@@ -357,6 +357,10 @@ The following service methods are available to instantiated clients. The example
           - [get](#get-15)
           - [update](#update-6)
       - [Run Test](#run-test)
+    - [DKIM Management](#dkim-management)
+      - [update](#update-7)
+    - [Bounce Classification](#bounce-classification)
+      - [list](#list-16)
   - [Navigation thru lists](#navigation-thru-lists)
   - [Browser Demo](#browser-demo)
 - [Development](#development)
@@ -4771,6 +4775,7 @@ The following service methods are available to instantiated clients. The example
       [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-sharing--result-)
 
       `mg.inboxPlacements.results.sharing.get('result_id');`
+
       Example:
         ```JS
         mg.inboxPlacements.results.sharing.get('result_id');
@@ -4857,6 +4862,161 @@ The following service methods are available to instantiated clients. The example
     }
   }
 
+### DKIM Management
+- #### update
+  Updates DKIM key rotation configuration for a domain
+
+  [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/dkim-security/put-v1-dkim-management-domains--name--rotation)
+
+  `mg.dkimManagement.update(domain_name, configurationData)`
+
+  Example:
+  ```JS
+    mg.dkimManagement.update('foobar.example.com', {
+      rotation_enabled: true,
+      rotation_interval: '120h0m0s'
+    })
+    .then(data => console.log(data)) // logs response data
+    .catch(err => console.error(err)); //logs any error
+  ```
+
+  Promise returns: DKIMUpdateRotationResult
+  ```JS
+  {
+    domain: {
+      id: 'domain_id',
+      account_id: 'account_id',
+      sid: 'sid',
+      name: 'foobar.example.com',
+      state: 'active',
+      active_selector: 'active_selector',
+      rotation_enabled: 'true',
+      rotation_interval: '120h0m0s',
+      records: [
+        {
+          name: 'record name',
+          type: 'CNAME',
+          identifier: 'DKIM',
+          value: 'record value',
+          comment: 'Customer DKIM CNAME Record'
+        },
+        ....
+      ]
+    }
+  }
+  ```
+
+- #### rotateImmediately
+  Immediately rotate your DKIM key. This will trigger a rotation even if auto-rotation is disabled on the domain.
+
+  [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/dkim-security/post-v1-dkim-management-domains--name--rotate)
+
+  `mg.dkimManagement.rotateImmediately(domain_name)`
+
+  Example:
+  ```JS
+    mg.dkimManagement.rotateImmediately('foobar.example.com')
+    .then(data => console.log(data)) // logs response data
+    .catch(err => console.error(err)); //logs any error
+  ```
+
+  Promise returns: DKIMRotateImmediatelyResult
+  ```JS
+  {
+    message: "ok";
+  }
+  ```
+
+### Bounce Classification
+- #### list
+  Returns bounce classification entities
+
+  [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/bounce-classification/post-v2-bounce-classification-metrics)
+
+  `mg.bounceClassification.list(query)`
+
+  Example:
+  ```JS
+    mg.bounceClassification.bounceClassification({
+      start: new Date('2025-12-01T13:00:00Z'),
+      end: new Date('2025-12-31T13:05:00Z'),
+      include_subaccounts: true,
+      resolution: 'day',
+      duration: '48h',
+      dimensions: [
+        'entity-name',
+        'domain.name'
+      ],
+      metrics: [
+        'critical_bounce_count',
+        'non_critical_bounce_count',
+        'critical_delay_count',
+        'non_critical_delay_count',
+        'delivered_smtp_count',
+        'classified_failures_count',
+        'critical_bounce_rate',
+        'non_critical_bounce_rate',
+        'critical_delay_rate',
+        'non_critical_delay_rate'
+      ],
+      filter: {
+        AND: [
+          {
+            attribute: 'domain.name',
+            comparator: '=',
+            values: [
+              {
+                value: 'example.com'
+              }
+            ]
+          }
+        ]
+      },
+      pagination: {
+        limit: 25,
+        skip: 0,
+        sort: 'entity-name:asc'
+      }
+    })
+    .then(data => console.log(data)) // logs response data
+    .catch(err => console.error(err)); //logs any error
+  ```
+
+  Promise returns: BounceClassificationResult
+  ```JS
+  {
+    start: new Date('2025-12-01T13:00:00.000Z'),
+    end: new Date('2025-12-31T13:05:00.000Z'),
+    resolution: 'day',
+    duration: '720h5m0s',
+    dimensions: [ 'entity-name', 'domain.name' ],
+    pagination: { sort: 'entity-name:asc', skip: 0, limit: 25, total: 1 },
+    items: [
+      {
+        'account.name': 'subaccount name',
+        'entity-name': 'Gmail',
+        'domain.name': 'example.com',
+        'envelope.i-ip-pool-name': 'default',
+        'envelope.sending-ip': '1.2.3.4',
+        timestamp: 'Tue, 02 Dec 2025 22:04:05 +0000',
+        tags: 'daily, campaign1',
+        metrics: {
+            'critical_bounce_count': 10,
+            'non_critical_bounce_count': 20,
+            'critical_delay_count': 30,
+            'non_critical_delay_count': 40,
+            'classified_failures_count': 100,
+            'delivered_smtp_count': 1000,
+            'critical_bounce_rate': 1,
+            'non_critical_bounce_rate': 2,
+            'critical_delay_rate': 3,
+            'non_critical_delay_rate': 4
+        }
+      }
+    ]
+  }
+  ```
+
 ## Pagination
   Most of the methods that return items in a list support pagination.
   There are two ways to receive part of the list:

package/Types/Classes/BounceClassification/BounceClassificationClient.d.ts

@@ -0,0 +1,11 @@
+import Request from '../common/Request.js';
+import { IBounceClassificationClient } from '../../Interfaces/index.js';
+import { BounceClassificationQueryData, BounceClassificationResult } from '../../Types/index.js';
+export default class BounceClassificationClient implements IBounceClassificationClient {
+    request: Request;
+    constructor(request: Request);
+    private prepareDate;
+    private parseQuery;
+    private parseResponse;
+    list(queryData: BounceClassificationQueryData): Promise<BounceClassificationResult>;
+}

package/Types/Classes/DKIM/DKIMManagment.d.ts

@@ -0,0 +1,10 @@
+import { DKIMRotateImmediatelyResult, DKIMRotationData, DKIMUpdateRotationResult } from '../../definitions.js';
+import { IDKIMManagementClient } from '../../Interfaces/DKIM/IDKIMManagementClient.js';
+import Request from '../common/Request.js';
+export default class DKIMManagementClient implements IDKIMManagementClient {
+    request: Request;
+    constructor(request: Request);
+    private prepareBooleanValues;
+    update(domainName: string, data: DKIMRotationData): Promise<DKIMUpdateRotationResult>;
+    rotateImmediately(domainName: string): Promise<DKIMRotateImmediatelyResult>;
+}

package/Types/Classes/MailgunClient.d.ts

@@ -1,7 +1,6 @@
 import Request from './common/Request.js';
 import { MailgunClientOptions, InputFormData } from '../Types/index.js';
-import { IDomainsClient, IWebHooksClient, IMailgunClient, IMailingListsClient, IEventClient, IStatsClient, ISuppressionClient, IMessagesClient, IRoutesClient, IValidationClient, IIPsClient, IIPPoolsClient, ISubaccountsClient, IInboxPlacementsClient, IMetricsClient } from '../Interfaces/index.js';
-import { ILogsClient } from '../Interfaces/Logs/ILogsClient.js';
+import { IDomainsClient, IWebHooksClient, IMailgunClient, IMailingListsClient, IEventClient, IStatsClient, ISuppressionClient, IMessagesClient, IRoutesClient, IValidationClient, IIPsClient, IIPPoolsClient, ISubaccountsClient, IInboxPlacementsClient, IMetricsClient, IDKIMManagementClient, ILogsClient, IBounceClassificationClient } from '../Interfaces/index.js';
 export default class MailgunClient implements IMailgunClient {
     request: Request;
     domains: IDomainsClient;
@@ -19,6 +18,8 @@ export default class MailgunClient implements IMailgunClient {
     subaccounts: ISubaccountsClient;
     inboxPlacements: IInboxPlacementsClient;
     logs: ILogsClient;
+    dkimManagement: IDKIMManagementClient;
+    bounceClassification: IBounceClassificationClient;
     constructor(options: MailgunClientOptions, formData: InputFormData);
     setSubaccount(subaccountId: string): void;
     resetSubaccount(): void;

package/Types/Enums/index.d.ts

@@ -11,12 +11,13 @@ export declare enum SuppressionModels {
 }
 export declare enum WebhooksIds {
     CLICKED = "clicked",
-    COMPLAINED = "complained",
-    DELIVERED = "delivered",
     OPENED = "opened",
+    UNSUBSCRIBED = "unsubscribe",
+    DELIVERED = "delivered",
     PERMANENT_FAIL = "permanent_fail",
     TEMPORARY_FAIL = "temporary_fail",
-    UNSUBSCRIBED = "unsubscribe"
+    COMPLAINED = "complained",
+    ACCEPTED = "accepted"
 }
 export declare enum YesNo {
     YES = "yes",

package/Types/Interfaces/BounceClassification/IBounceClassificationClient.d.ts

@@ -0,0 +1,4 @@
+import { BounceClassificationQueryData, BounceClassificationResult } from '../../Types/index.js';
+export interface IBounceClassificationClient {
+    list(data: BounceClassificationQueryData): Promise<BounceClassificationResult>;
+}

package/Types/Interfaces/BounceClassification/index.d.ts

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

package/Types/Interfaces/DKIM/IDKIMManagementClient.d.ts

@@ -0,0 +1,5 @@
+import { DKIMRotateImmediatelyResult, DKIMRotationData, DKIMUpdateRotationResult } from '../../Types/DKIM/index.js';
+export interface IDKIMManagementClient {
+    update(domainName: string, data: DKIMRotationData): Promise<DKIMUpdateRotationResult>;
+    rotateImmediately(domainName: string): Promise<DKIMRotateImmediatelyResult>;
+}

package/Types/Interfaces/DKIM/index.d.ts

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

package/Types/Interfaces/MailgunClient/IMailgunClient.d.ts

@@ -14,6 +14,8 @@ import { IInboxPlacementsClient } from '../InboxPlacements/index.js';
 import { IMetricsClient } from '../Metrics/MetricsClient.js';
 import type Request from '../../Classes/common/Request.js';
 import { ILogsClient } from '../Logs/ILogsClient.js';
+import { IDKIMManagementClient } from '../DKIM/IDKIMManagementClient.js';
+import { IBounceClassificationClient } from '../BounceClassification/IBounceClassificationClient.js';
 export interface IMailgunClient {
     request: Request;
     domains: IDomainsClient;
@@ -33,4 +35,6 @@ export interface IMailgunClient {
     setSubaccount(subaccountId: string): void;
     resetSubaccount(): void;
     logs: ILogsClient;
+    dkimManagement: IDKIMManagementClient;
+    bounceClassification: IBounceClassificationClient;
 }

package/Types/Interfaces/index.d.ts

@@ -14,3 +14,6 @@ export * from './IPPools/index.js';
 export * from './Subaccounts/index.js';
 export * from './InboxPlacements/index.js';
 export * from './Metrics/MetricsClient.js';
+export * from './Logs/ILogsClient.js';
+export * from './DKIM/IDKIMManagementClient.js';
+export * from './BounceClassification/IBounceClassificationClient.js';

package/Types/Types/BounceClassification/BounceClassification.d.ts

@@ -0,0 +1,73 @@
+export type BounceClassificationQueryDimensions = 'entity-name' | 'domain.name' | 'envelope.sending-ip' | 'account.name' | 'envelope.i-ip-pool-name' | 'tags' | 'tag' | 'recipient-domain' | 'group-id' | 'criticality' | 'severity' | 'category' | 'timestamp';
+export type BounceClassificationQueryMetrics = 'critical_bounce_count' | 'non_critical_bounce_count' | 'critical_delay_count' | 'non_critical_delay_count' | 'delivered_smtp_count' | 'classified_failures_count' | 'critical_bounce_rate' | 'non_critical_bounce_rate' | 'critical_delay_rate' | 'non_critical_delay_rate';
+export type BounceClassificationQueryFilterAttribute = 'entity-name' | 'domain.name' | 'envelope.sending-ip' | 'account.name' | 'envelope.i-ip-pool-name' | 'tags' | 'tag' | 'recipient-domain' | 'group-id' | 'criticality' | 'severity' | 'category';
+export type BounceClassificationQueryFilter = {
+    AND: {
+        attribute: BounceClassificationQueryFilterAttribute;
+        comparator: string;
+        values: {
+            label: string;
+            value: string;
+        }[];
+    }[];
+};
+export type BounceClassificationQueryData = {
+    start?: Date;
+    end?: Date;
+    resolution?: 'hour' | 'day';
+    duration?: string;
+    dimensions?: BounceClassificationQueryDimensions[];
+    metrics?: BounceClassificationQueryMetrics[];
+    filter?: BounceClassificationQueryFilter;
+    'include_subaccounts'?: boolean;
+    'pagination': {
+        sort?: string;
+        skip?: number;
+        limit?: number;
+    };
+};
+export type BounceClassificationAPIQuery = Omit<BounceClassificationQueryData, 'start' | 'end'> & {
+    start?: string;
+    end?: string;
+};
+export type BounceClassificationResultItem = {
+    'account.id': string | null;
+    'account.name': string | null;
+    'entity-name': string | null;
+    'recipient-provider': string | null;
+    'recipient-domain': string | null;
+    'domain.name': string | null;
+    'envelope.i-ip-pool-id': string | null;
+    'envelope.i-ip-pool-name': string | null;
+    'envelope.sending-ip': string | null;
+    timestamp: string | null;
+    tags: string | null;
+    tag: string | null;
+    criticality: string | null;
+    severity: string | null;
+    category: string | null;
+    'group-id': string | null;
+    'sample-text': string | null;
+    explanation: string | null;
+    metrics: {
+        [K in BounceClassificationQueryMetrics]: number;
+    };
+};
+export type BounceClassificationResult = {
+    start: Date;
+    end: Date;
+    resolution: 'hour' | 'day' | 'month';
+    duration?: string;
+    dimensions?: BounceClassificationQueryDimensions[];
+    pagination: {
+        sort: string;
+        skip: number;
+        limit: number;
+        total: number;
+    };
+    items: BounceClassificationResultItem[];
+};
+export type BounceClassificationAPIResponse = Omit<BounceClassificationResult, 'start' | 'end'> & {
+    start: string;
+    end: string;
+};

package/Types/Types/BounceClassification/index.d.ts

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

package/Types/Types/Common/RequestOptions.d.ts

@@ -11,6 +11,7 @@ import type { IpPoolDeleteData } from '../IPPools/index.js';
 import type { MetricsQuery } from '../Metrics/index.js';
 import type { FormDataInput } from './FormData.js';
 import { LogsQuery } from '../Logs/Logs.js';
+import { BounceClassificationAPIQuery } from '../BounceClassification/BounceClassification.js';
 export type OnCallEmptyHeaders = {
     [key: string]: undefined;
 };
@@ -37,7 +38,7 @@ export type GetQueryTypes = IPsListQuery | RoutesListQuery | SubaccountsQuery |
     searchParams?: Array<Array<string>>;
 } | ValidationQuery;
 export type DeleteQueryTypes = DeletedDomainKeysQuery;
-export type PostDataTypes = InboxPlacementsData | MetricsQuery | LogsQuery | string;
+export type PostDataTypes = InboxPlacementsData | MetricsQuery | LogsQuery | BounceClassificationAPIQuery | string;
 export type PutDataTypes = SeedsListsUpdatingData | object | FormDataInput | ConnectionSettings;
 export type RequestData = IpPoolDeleteData | PostDataTypes | PutDataTypes | NodeFormData | FormData;
 export type ContainsPrefix<T extends string> = `${T}${string}`;

package/Types/Types/DKIM/DKIM.d.ts

@@ -0,0 +1,29 @@
+export type DKIMRotationData = {
+    'rotation_enabled': boolean | string;
+    'rotation_interval'?: string;
+};
+type DKIMRecord = {
+    name: string;
+    type: string;
+    identifier: string;
+    value: string;
+    comment: string;
+};
+type DKIMDomain = {
+    id: string;
+    'account_id': string;
+    sid: string;
+    name: string;
+    state: string;
+    'active_selector': string;
+    'rotation_enabled': string;
+    'rotation_interval': string;
+    records: DKIMRecord[];
+};
+export type DKIMUpdateRotationResult = {
+    domain: DKIMDomain;
+};
+export type DKIMRotateImmediatelyResult = {
+    message: string;
+};
+export {};

package/Types/Types/DKIM/index.d.ts

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

package/Types/Types/index.d.ts

@@ -14,3 +14,5 @@ export * from './Suppressions/index.js';
 export * from './Validations/index.js';
 export * from './Webhooks/index.js';
 export * from './Logs/index.js';
+export * from './DKIM/index.js';
+export * from './BounceClassification/index.js';

package/Types/index.js

@@ -464,7 +464,8 @@ var FormDataBuilder = /** @class */ (function () {
                 }
                 if (_this.attachmentsHandler.isStream(objData)) {
                     var blob = _this.attachmentsHandler.getBlobFromStream(objData, options.knownLength);
-                    browserFormData.set(key, blob, options.filename);
+                    // Needs to be append for multiple files, otherwise only last file is attached.
+                    browserFormData.append(key, blob, options.filename);
                 }
             }
         };
@@ -5326,12 +5327,13 @@ var SuppressionModels;
 var WebhooksIds;
 (function (WebhooksIds) {
     WebhooksIds["CLICKED"] = "clicked";
-    WebhooksIds["COMPLAINED"] = "complained";
-    WebhooksIds["DELIVERED"] = "delivered";
     WebhooksIds["OPENED"] = "opened";
+    WebhooksIds["UNSUBSCRIBED"] = "unsubscribe";
+    WebhooksIds["DELIVERED"] = "delivered";
     WebhooksIds["PERMANENT_FAIL"] = "permanent_fail";
     WebhooksIds["TEMPORARY_FAIL"] = "temporary_fail";
-    WebhooksIds["UNSUBSCRIBED"] = "unsubscribe";
+    WebhooksIds["COMPLAINED"] = "complained";
+    WebhooksIds["ACCEPTED"] = "accepted";
 })(WebhooksIds || (WebhooksIds = {}));
 var YesNo;
 (function (YesNo) {
@@ -7207,6 +7209,88 @@ var LogsClient = /** @class */ (function () {
     return LogsClient;
 }());
 
+var DKIMManagementClient = /** @class */ (function () {
+    function DKIMManagementClient(request) {
+        this.request = request;
+    }
+    DKIMManagementClient.prototype.prepareBooleanValues = function (data) {
+        var res = __assign(__assign({}, data), { rotation_enabled: '' });
+        if (Object.keys(data).includes('rotation_enabled')) {
+            res.rotation_enabled = "".concat(data.rotation_enabled);
+        }
+        return res;
+    };
+    DKIMManagementClient.prototype.update = function (domainName, data) {
+        return __awaiter(this, void 0, void 0, function () {
+            var preparedData, response;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        preparedData = this.prepareBooleanValues(data);
+                        return [4 /*yield*/, this.request.putWithFD(urljoin('v1/dkim_management/domains/', domainName, 'rotation'), preparedData)];
+                    case 1:
+                        response = _a.sent();
+                        return [2 /*return*/, response.body];
+                }
+            });
+        });
+    };
+    DKIMManagementClient.prototype.rotateImmediately = function (domainName) {
+        return __awaiter(this, void 0, void 0, function () {
+            var response;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.request.post(urljoin('v1/dkim_management/domains/', domainName, 'rotate'), {})];
+                    case 1:
+                        response = _a.sent();
+                        return [2 /*return*/, response.body];
+                }
+            });
+        });
+    };
+    return DKIMManagementClient;
+}());
+
+var BounceClassificationClient = /** @class */ (function () {
+    function BounceClassificationClient(request) {
+        this.request = request;
+    }
+    BounceClassificationClient.prototype.prepareDate = function (date) {
+        var formattedDate = "".concat(date.toUTCString().slice(0, 25), " -0000"); // expected format 'Wed, 03 Dec 2025 00:00:00 -0000'
+        return formattedDate;
+    };
+    BounceClassificationClient.prototype.parseQuery = function (queryData) {
+        var res = __assign(__assign({}, queryData), { start: undefined, end: undefined, include_subaccounts: undefined });
+        if (queryData.start) {
+            res.start = this.prepareDate(queryData.start);
+        }
+        if (queryData.end) {
+            res.end = this.prepareDate(queryData.end);
+        }
+        return res;
+    };
+    BounceClassificationClient.prototype.parseResponse = function (body) {
+        var res = __assign(__assign({}, body), { start: new Date(body.start), end: new Date(body.end) });
+        return res;
+    };
+    BounceClassificationClient.prototype.list = function (queryData) {
+        return __awaiter(this, void 0, void 0, function () {
+            var preparedQueryData, response;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        preparedQueryData = this.parseQuery(queryData);
+                        return [4 /*yield*/, this.request.post('/v2/bounce-classification/metrics', preparedQueryData)];
+                    case 1:
+                        response = _a.sent();
+                        return [2 /*return*/, this.parseResponse(response.body)];
+                }
+            });
+        });
+    };
+    return BounceClassificationClient;
+}());
+
 var MailgunClient = /** @class */ (function () {
     function MailgunClient(options, formData) {
         var config = __assign({}, options);
@@ -7254,6 +7338,8 @@ var MailgunClient = /** @class */ (function () {
         this.subaccounts = new SubaccountsClient(this.request);
         this.inboxPlacements = new InboxPlacementsClient(this.request, seedsListsClient, inboxPlacementsResultsClient, inboxPlacementsProvidersClient);
         this.logs = new LogsClient(this.request);
+        this.dkimManagement = new DKIMManagementClient(this.request);
+        this.bounceClassification = new BounceClassificationClient(this.request);
     }
     MailgunClient.prototype.setSubaccount = function (subaccountId) {
         var _a;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailgun.js",
-  "version": "12.4.1",
+  "version": "12.5.0",
   "author": "Mailgun",
   "license": "MIT",
   "type": "module",

package/version.md

@@ -1 +1 @@
-12.4.1
+12.5.0