mailgun.js 12.3.1 → 12.4.1

package/README.md

@@ -259,6 +259,8 @@ The following service methods are available to instantiated clients. The example
     - [events](#events)
       - [get](#get-3)
         - [Example with Date and *Filter field*](#example-with-date-and-filter-field)
+    - [logs](#logs)
+      - [list](#list-3)
     - [stats](#stats)
       - [Stats Options](#stats-options)
       - [getDomain](#getdomain)
@@ -267,7 +269,7 @@ The following service methods are available to instantiated clients. The example
       - [getAccount](#getaccount-1)
       - [getAccountUsage](#getaccountusage)
     - [suppressions](#suppressions)
-      - [list](#list-3)
+      - [list](#list-4)
         - [Bounces Example](#bounces-example)
         - [Unsubscribes Example](#unsubscribes-example)
         - [Complaints Example](#complaints-example)
@@ -286,13 +288,13 @@ The following service methods are available to instantiated clients. The example
         - [Unsubscribes Example](#unsubscribes-example-3)
         - [Complaints Example](#complaints-example-3)
     - [webhooks](#webhooks)
-      - [list](#list-4)
+      - [list](#list-5)
       - [get](#get-5)
       - [create](#create-5)
       - [update](#update-2)
       - [destroy](#destroy-4)
     - [routes](#routes)
-      - [list](#list-5)
+      - [list](#list-6)
       - [get](#get-6)
       - [create](#create-6)
       - [update](#update-3)
@@ -301,11 +303,11 @@ The following service methods are available to instantiated clients. The example
       - [get](#get-7)
     - [multiple validation](#multiple-validation)
       - [create](#create-7)
-      - [list](#list-6)
+      - [list](#list-7)
       - [get](#get-8)
       - [destroy](#destroy-6)
     - [mailing lists](#mailing-lists)
-      - [list](#list-7)
+      - [list](#list-8)
       - [get](#get-9)
       - [create](#create-8)
       - [update](#update-4)
@@ -318,7 +320,7 @@ The following service methods are available to instantiated clients. The example
       - [updateMember](#updatemember)
       - [destroyMember](#destroymember)
     - [subaccounts](#subaccounts)
-      - [list](#list-8)
+      - [list](#list-9)
       - [get](#get-10)
       - [create](#create-9)
       - [enable](#enable)
@@ -329,28 +331,28 @@ The following service methods are available to instantiated clients. The example
       - [updateSubaccountFeature](#updatesubaccountfeature)
     - [inbox placements](#inbox-placements)
       - [SeedsLists](#seedslists)
-        - [list](#list-9)
+        - [list](#list-10)
         - [get](#get-11)
         - [create](#create-10)
         - [update](#update-5)
         - [destroy](#destroy-9)
         - [SeedsLists Attributes](#attributes)
-          - [list](#list-10)
+          - [list](#list-11)
           - [get](#get-12)
         - [SeedsLists Filters](#filters)
-          - [list](#list-11)
+          - [list](#list-12)
       - [Providers](#providers)
-        - [list](#list-12)
-      - [Results](#results)
         - [list](#list-13)
+      - [Results](#results)
+        - [list](#list-14)
         - [get](#get-13)
         - [destroy](#destroy-10)
         - [getResultByShareId](#getresultbyshareid)
         - [Results Attributes](#attributes-1)
-          - [list](#list-14)
+          - [list](#list-15)
           - [get](#get-14)
         - [Results Filters](#filters-1)
-          - [list](#list-15)
+          - [list](#list-16)
         - [Sharing](#sharing)
           - [get](#get-15)
           - [update](#update-6)
@@ -2252,7 +2254,7 @@ The following service methods are available to instantiated clients. The example
 ### Events
 
 - #### get
-  ***Deprecated, and will be removed in the future releases***
+  ***Deprecated, and will be removed in the future releases. Use [Logs](#logs) instead**
 
   [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/events)
 
@@ -2309,6 +2311,93 @@ The following service methods are available to instantiated clients. The example
   }
   ```
 
+### Logs
+  Mailgun keeps track of every inbound and outbound message event and stores this log data. This data can be queried and filtered to provide insights into the health of your email infrastructure.
+
+  - #### list
+    Gets customer event logs for an account
+
+    [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/stats)
+
+    ```mg.logs.list(query)```
+
+    Example:
+
+    ```JS
+    mg.logs.list({
+      start: new Date('2025-11-17T13:00:00Z'), // required
+      end: new Date('2025-11-30T13:05:00Z'), // required
+      include_totals: true,
+      events: ['accepted'], // opened, delivered, etc.
+      include_subaccounts: false,
+      pagination: {
+        token: 'page token from response',
+        limit: 5,
+        sort: 'timestamp:asc'
+      },
+      filter: {
+        AND: [
+          {
+            attribute: 'domain',
+            comparator: '=',
+            values: [
+              {
+                label: 'example.com',
+                value: 'example.com'
+              }
+            ]
+          }
+        ]
+      }
+    }).then(data => console.log(data)) // logs response
+      .catch(err => console.error(err)); // logs any error
+    ```
+
+    Promise returns:
+    ```JS
+    {
+      start: new Date('2025-11-17T13:00:00.000Z'),
+      end: new Date('2025-11-30T13:05:00.000Z'),
+      status: 200,
+      pagination: {
+        next: 'page token for next page',
+        last: 'page token for last page'
+      },
+      items: [
+        {
+          id: 'JDhSWf9mT5OFxCkZfpDU5d',
+          event: 'accepted',
+          '@timestamp': new Date('2024-07-08T16:30:18.530Z'),
+          account: {
+            id: '12345'
+          },
+          delivery-status: {
+            message: 'Turret client: server connection failed',
+            'attempt-no': 5,
+            code: 680,
+            'session-seconds': 15.026,
+            'retry-seconds': 145
+          },
+          domain: {
+            name: 'example.com'
+          },
+          recipient: 'example@gmail.com',
+          'recipient-domain': 'gmail.com',
+          'recipient-provider': 'Gmail',
+          envelope: {
+            sender: 'bob@example.com',
+            transport: 'smtp',
+            'sending-ip': '198.52.100.1',
+            targets: 'bob@example.com'
+          }
+        },
+        ...
+      ],
+      aggregates: {}
+    }
+    ```
+
+
 ### Stats
   ***Deprecated, and will be removed in the future releases***
 
@@ -4675,6 +4764,7 @@ The following service methods are available to instantiated clients. The example
         ```
 
   - #### Sharing
+
     - #### get
       The sharing status of a result.
 

package/Types/Classes/Events.d.ts

@@ -1,10 +1,11 @@
 import NavigationThruPages from './common/NavigationThruPages.js';
 import { EventsList, EventsQuery, EventsResponse } from '../Types/Events/index.js';
 import Request from './common/Request.js';
-import { IEventClient } from '../Interfaces/index.js';
+import { IEventClient, ILogger } from '../Interfaces/index.js';
 export default class EventClient extends NavigationThruPages<EventsList> implements IEventClient {
     request: Request;
-    constructor(request: Request);
+    private logger;
+    constructor(request: Request, logger?: ILogger);
     protected parseList(response: EventsResponse): EventsList;
     get(domain: string, query?: EventsQuery): Promise<EventsList>;
 }

package/Types/Classes/Logs/LogsClient.d.ts

@@ -0,0 +1,12 @@
+import Request from '../common/Request.js';
+import { LogsList, LogsQuery } from '../../Types/Logs/Logs.js';
+import { ILogsClient } from '../../Interfaces/Logs/ILogsClient.js';
+export default class LogsClient implements ILogsClient {
+    request: Request;
+    constructor(request: Request);
+    private parseListResponse;
+    private prepareDate;
+    private parseQuery;
+    private validateQuery;
+    list(queryData: LogsQuery): Promise<LogsList>;
+}

package/Types/Classes/MailgunClient.d.ts

@@ -1,6 +1,7 @@
 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';
 export default class MailgunClient implements IMailgunClient {
     request: Request;
     domains: IDomainsClient;
@@ -17,6 +18,7 @@ export default class MailgunClient implements IMailgunClient {
     lists: IMailingListsClient;
     subaccounts: ISubaccountsClient;
     inboxPlacements: IInboxPlacementsClient;
+    logs: ILogsClient;
     constructor(options: MailgunClientOptions, formData: InputFormData);
     setSubaccount(subaccountId: string): void;
     resetSubaccount(): void;

package/Types/Interfaces/Logs/ILogsClient.d.ts

@@ -0,0 +1,4 @@
+import { LogsList, LogsQuery } from '../../Types/Logs/index.js';
+export interface ILogsClient {
+    list(query: LogsQuery): Promise<LogsList>;
+}

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

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

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

@@ -13,6 +13,7 @@ import { ISubaccountsClient } from '../Subaccounts/index.js';
 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';
 export interface IMailgunClient {
     request: Request;
     domains: IDomainsClient;
@@ -31,4 +32,5 @@ export interface IMailgunClient {
     inboxPlacements: IInboxPlacementsClient;
     setSubaccount(subaccountId: string): void;
     resetSubaccount(): void;
+    logs: ILogsClient;
 }

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

@@ -10,6 +10,7 @@ import type { ValidationQuery } from '../Validations/index.js';
 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';
 export type OnCallEmptyHeaders = {
     [key: string]: undefined;
 };
@@ -36,7 +37,7 @@ export type GetQueryTypes = IPsListQuery | RoutesListQuery | SubaccountsQuery |
     searchParams?: Array<Array<string>>;
 } | ValidationQuery;
 export type DeleteQueryTypes = DeletedDomainKeysQuery;
-export type PostDataTypes = InboxPlacementsData | MetricsQuery | string;
+export type PostDataTypes = InboxPlacementsData | MetricsQuery | LogsQuery | 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/Logs/Logs.d.ts

@@ -0,0 +1,172 @@
+export type LogsFilterValue = {
+    label: string;
+    value: string;
+};
+export type LogsFilter = {
+    AND: {
+        attribute: string;
+        comparator: string;
+        values: LogsFilterValue[];
+    }[];
+};
+export type LogsQuery = {
+    start?: Date;
+    end?: Date;
+    events?: string[];
+    'metric_events'?: string[];
+    'include_subaccounts'?: boolean;
+    'include_totals'?: boolean;
+    pagination?: {
+        sort?: string;
+        token?: string;
+        limit?: number;
+    };
+    filter?: LogsFilter;
+};
+export type LogsParsedQuery = Omit<LogsQuery, 'start' | 'end'> & {
+    start?: string;
+    end?: string;
+};
+export type LogsDeliveryStatus = {
+    message?: string;
+    'attempt-no'?: number;
+    'code'?: number;
+    'bounce-type'?: string;
+    description?: string;
+    'session-seconds'?: number;
+    'retry-seconds'?: number;
+    'enhanced-code'?: string;
+    'mx-host'?: string;
+    'certificate-verified'?: boolean;
+    'tls'?: boolean;
+    'utf8'?: boolean;
+    'first-delivery-attempt-seconds'?: number;
+    'last-code'?: number;
+    'last-message'?: string;
+};
+export type LogsEvent = {
+    id: string;
+    event: string;
+    '@timestamp': string;
+    account?: {
+        'parent-id': string;
+        'id': string;
+    };
+    campaigns?: {
+        id: string;
+        name: string;
+    }[];
+    tags?: string[];
+    method?: string;
+    'originating-ip'?: string;
+    'api-key-id'?: string;
+    'delivery-status'?: LogsDeliveryStatus;
+    'i-delivery-optimizer'?: string;
+    domain: {
+        name: string;
+    };
+    recipient?: string;
+    'recipient-domain'?: string;
+    'recipient-provider'?: string;
+    envelope?: {
+        sender?: string;
+        transport?: string;
+        'sending-ip'?: string;
+        targets?: string;
+        'i-ip-pool-id'?: string;
+    };
+    storage?: {
+        region?: string;
+        env?: string;
+        key?: string;
+        url?: string[];
+    };
+    template?: {
+        name?: string;
+        version?: string;
+        'is-text'?: boolean;
+    };
+    'log-level'?: string;
+    'user-variables'?: string;
+    'message'?: {
+        headers?: {
+            to: string;
+            'message-id': string;
+            from: string;
+            subject: string;
+        };
+        attachments?: {
+            filename?: string;
+            'content-type'?: string;
+            size?: number;
+        }[];
+        recipients?: string[];
+        size?: number;
+        'scheduled-for'?: number;
+    };
+    flags?: {
+        'is-authenticated': boolean;
+        'is-system-test': boolean;
+        'is-routed': boolean;
+        'is-amp'?: boolean;
+        'is-test-mode': boolean;
+        'is-delayed-bounce': boolean;
+        'is-callback': boolean;
+        'is-encrypted': boolean;
+    };
+    'primary-dkim'?: string;
+    ip?: string;
+    geolocation?: {
+        city?: string;
+        country?: string;
+        region?: string;
+        timezone?: string;
+    };
+    'client-info'?: {
+        'client-name'?: string;
+        'client-os'?: string;
+        'client-type'?: string;
+        'device-type'?: string;
+        'user-agent'?: string;
+        ip?: string;
+        bot?: string;
+    };
+    severity?: string;
+    reason?: string;
+    routes?: {
+        actions?: string;
+        description?: string;
+        expression?: string;
+        id?: string;
+        priority?: number;
+        match?: {
+            recipient?: string;
+        };
+    };
+    'mailing-list'?: {
+        address?: string;
+        'list-id'?: string;
+        sid?: string;
+    };
+    url?: string;
+};
+export type LogsEventItem = Omit<LogsEvent, '@timestamp'> & {
+    '@timestamp': Date;
+};
+export type LogsList = {
+    start: Date;
+    end: Date;
+    items: LogsEventItem[];
+    pagination: {
+        previous?: string;
+        first?: string;
+        last?: string;
+        next?: string;
+        total?: number;
+    };
+    aggregates: {
+        all: number;
+        metrics: object;
+    };
+    status: number;
+};

package/Types/Types/Logs/index.d.ts

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

package/Types/Types/index.d.ts

@@ -13,3 +13,4 @@ export * from './Subaccounts/index.js';
 export * from './Suppressions/index.js';
 export * from './Validations/index.js';
 export * from './Webhooks/index.js';
+export * from './Logs/index.js';

package/Types/index.js

@@ -5216,9 +5216,11 @@ var NavigationThruPages = /** @class */ (function () {
 
 var EventClient = /** @class */ (function (_super) {
     __extends(EventClient, _super);
-    function EventClient(request) {
+    function EventClient(request, logger) {
+        if (logger === void 0) { logger = console; }
         var _this = _super.call(this, request) || this;
         _this.request = request;
+        _this.logger = logger;
         return _this;
     }
     EventClient.prototype.parseList = function (response) {
@@ -5231,6 +5233,7 @@ var EventClient = /** @class */ (function (_super) {
     EventClient.prototype.get = function (domain, query) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
+                this.logger.warn('"events.get" method is deprecated. Please use "logs.list" instead');
                 return [2 /*return*/, this.requestListWithPages(urljoin('/v3', domain, 'events'), query)];
             });
         });
@@ -7113,6 +7116,97 @@ var DomainKeysClient = /** @class */ (function (_super) {
     return DomainKeysClient;
 }(NavigationThruPages));
 
+var LogsClient = /** @class */ (function () {
+    function LogsClient(request) {
+        this.request = request;
+    }
+    LogsClient.prototype.parseListResponse = function (response) {
+        var parsedResponse = {
+            start: new Date(response.body.start),
+            end: new Date(response.body.end),
+            status: response.status,
+            pagination: response.body.pagination,
+            items: response.body.items.map(function (item) {
+                var responseItem = __assign(__assign({}, item), { '@timestamp': new Date(item['@timestamp']) });
+                return responseItem;
+            }),
+            aggregates: response.body.aggregates
+        };
+        return parsedResponse;
+    };
+    LogsClient.prototype.prepareDate = function (date) {
+        // 'Wed, 03 Dec 2025 00:00:00 -0000'
+        var formattedDate = "".concat(date.toUTCString().slice(0, 25), " -0000");
+        return formattedDate;
+    };
+    LogsClient.prototype.parseQuery = function (queryData) {
+        var res = __assign(__assign({}, queryData), { start: '', end: '' });
+        if (queryData.start) {
+            res.start = this.prepareDate(queryData.start);
+        }
+        if (queryData.end) {
+            res.end = this.prepareDate(queryData.end);
+        }
+        return res;
+    };
+    LogsClient.prototype.validateQuery = function (queryData) {
+        if (!queryData) {
+            throw APIError.getUserDataError('Missed parameter "query"', '"logs.list": Query data is required');
+        }
+        if (queryData === null || queryData === void 0 ? void 0 : queryData.start) {
+            if ((!((queryData === null || queryData === void 0 ? void 0 : queryData.start) instanceof Date) || Number.isNaN(queryData.start.getTime()))) {
+                throw APIError.getUserDataError('Incorrect type', '"logs.list": Type of "start" must be valid JS Data object');
+            }
+        }
+        else {
+            throw APIError.getUserDataError('Missed property', '"logs.list": "start" property is required');
+        }
+        if (queryData === null || queryData === void 0 ? void 0 : queryData.end) {
+            if ((!((queryData === null || queryData === void 0 ? void 0 : queryData.end) instanceof Date) || Number.isNaN(queryData.end.getTime()))) {
+                throw APIError.getUserDataError('Incorrect type', '"logs.list": Type of "end" must be valid JS Data object');
+            }
+        }
+        if (queryData.filter) {
+            if (!queryData.filter.AND) {
+                throw APIError.getUserDataError('Incorrect filter', '"logs.list": Logs filter must have AND operator');
+            }
+            if (!Array.isArray(queryData.filter.AND) || queryData.filter.AND.length === 0) {
+                throw APIError.getUserDataError('Incorrect filter', '"logs.list": Logs filter AND operator must be an array');
+            }
+            queryData.filter.AND.forEach(function (condition) {
+                if (!condition.attribute || !condition.comparator || !condition.values) {
+                    throw APIError.getUserDataError('Incorrect filter', '"logs.list": Each condition in Logs filter AND operator must have attribute, comparator and values');
+                }
+                if (!Array.isArray(condition.values) || condition.values.length === 0) {
+                    throw APIError.getUserDataError('Incorrect filter', '"logs.list": Values in each condition of Logs filter AND operator must be an array');
+                }
+                condition.values.forEach(function (value) {
+                    if (!value.label || !value.value) {
+                        throw APIError.getUserDataError('Incorrect filter', '"logs.list": Each value in Logs filter condition must have label and value');
+                    }
+                });
+            });
+        }
+    };
+    LogsClient.prototype.list = function (queryData) {
+        return __awaiter(this, void 0, void 0, function () {
+            var preparedQuery, response;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        this.validateQuery(queryData);
+                        preparedQuery = this.parseQuery(queryData);
+                        return [4 /*yield*/, this.request.post(urljoin('/v1/analytics/logs'), preparedQuery)];
+                    case 1:
+                        response = _a.sent();
+                        return [2 /*return*/, this.parseListResponse(response)];
+                }
+            });
+        });
+    };
+    return LogsClient;
+}());
+
 var MailgunClient = /** @class */ (function () {
     function MailgunClient(options, formData) {
         var config = __assign({}, options);
@@ -7159,6 +7253,7 @@ var MailgunClient = /** @class */ (function () {
         this.validate = new ValidateClient(this.request, multipleValidationClient);
         this.subaccounts = new SubaccountsClient(this.request);
         this.inboxPlacements = new InboxPlacementsClient(this.request, seedsListsClient, inboxPlacementsResultsClient, inboxPlacementsProvidersClient);
+        this.logs = new LogsClient(this.request);
     }
     MailgunClient.prototype.setSubaccount = function (subaccountId) {
         var _a;

package/package.json

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

package/version.md

@@ -1 +1 @@
-12.3.1
+12.4.1