mailgun.js 11.0.0 → 11.1.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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.
 
+## [11.1.0](https://github.com/mailgun/mailgun.js/compare/v11.0.0...v11.1.0) (2025-01-09)
+
+
+### Features
+
+* Adding Secure Tracking API support ([b5ff1e0](https://github.com/mailgun/mailgun.js/commits/b5ff1e0a4c6982b302add9b25712818082a62fd0))
+
 ## [11.0.0](https://github.com/mailgun/mailgun.js/compare/v10.4.0...v11.0.0) (2025-01-09)
 
 

package/Classes/Domains/domainsClient.d.ts

@@ -1,25 +1,20 @@
 import { IDomainTemplatesClient, IDomainTagsClient, IDomainCredentials, IDomainsClient } from '../../Interfaces/Domains';
 import { APIResponse } from '../../Types/Common/ApiResponse';
 import Request from '../common/Request';
-import DomainCredentialsClient from './domainsCredentials';
-import DomainTemplatesClient from './domainsTemplates';
-import DomainTagsClient from './domainsTags';
 import { MessageResponse, DomainTrackingData, UpdatedOpenTracking, DomainsQuery, DomainInfo, ConnectionSettings, UpdatedConnectionSettings, OpenTrackingInfo, ClickTrackingInfo, UnsubscribeTrackingInfo, ReplacementForPool, DKIMAuthorityInfo, UpdatedDKIMAuthority, DKIMSelectorInfo, WebPrefixInfo, UpdatedWebPrefixResponse, TDomain, DomainUpdateInfo, DomainGetQuery, UpdatedDKIMSelectorResult } from '../../Types/Domains';
-import { ILogger } from '../../Interfaces';
+import { ILogger, IDomainTrackingClient } from '../../Interfaces';
 export default class DomainsClient implements IDomainsClient {
     request: Request;
     domainCredentials: IDomainCredentials;
     domainTemplates: IDomainTemplatesClient;
     domainTags: IDomainTagsClient;
+    domainTracking: IDomainTrackingClient;
     private logger;
-    constructor(request: Request, domainCredentialsClient: DomainCredentialsClient, domainTemplatesClient: DomainTemplatesClient, domainTagsClient: DomainTagsClient, logger?: ILogger);
+    constructor(request: Request, domainCredentialsClient: IDomainCredentials, domainTemplatesClient: IDomainTemplatesClient, domainTagsClient: IDomainTagsClient, domainTracking: IDomainTrackingClient, logger?: ILogger);
     private _handleBoolValues;
     private _parseMessage;
     private parseDomainList;
     private _parseDomain;
-    private _parseTrackingSettings;
-    private _parseTrackingUpdate;
-    private _isOpenTrackingInfoWitPlace;
     list(query?: DomainsQuery): Promise<TDomain[]>;
     get(domain: string, query?: DomainGetQuery): Promise<TDomain>;
     create(data: DomainInfo): Promise<TDomain>;
@@ -28,7 +23,15 @@ export default class DomainsClient implements IDomainsClient {
     destroy(domain: string): Promise<MessageResponse>;
     getConnection(domain: string): Promise<ConnectionSettings>;
     updateConnection(domain: string, data: ConnectionSettings): Promise<UpdatedConnectionSettings>;
+    /**
+    * @deprecated 'domains.getTracking' method is deprecated, and will be removed.
+    * Please use 'domains.domainTracking.getTracking' instead.
+    */
     getTracking(domain: string): Promise<DomainTrackingData>;
+    /**
+    * @deprecated 'domains.updateTracking' method is deprecated, and will be removed.
+    * Please use 'domains.domainTracking.updateTracking' instead.
+    */
     updateTracking(domain: string, type: string, data: OpenTrackingInfo | ClickTrackingInfo | UnsubscribeTrackingInfo): Promise<UpdatedOpenTracking>;
     /**
     * @deprecated "domains.getIps" method is deprecated, and will be removed in the future releases.

package/Classes/Domains/domainsTracking.d.ts

@@ -0,0 +1,15 @@
+import { IDomainTrackingClient } from '../../Interfaces';
+import { ClickTrackingInfo, DomainTrackingData, GenerateDomainTrackingCertificateResponse, GetDomainTrackingCertificateResponse, OpenTrackingInfo, RegenerateDomainTrackingCertificateResponse, UnsubscribeTrackingInfo, UpdatedOpenTracking } from '../../Types';
+import Request from '../common/Request';
+export default class DomainTrackingClient implements IDomainTrackingClient {
+    request: Request;
+    constructor(request: Request);
+    private _parseTrackingSettings;
+    private _parseTrackingUpdate;
+    private _isOpenTrackingInfoWitPlace;
+    get(domain: string): Promise<GetDomainTrackingCertificateResponse>;
+    generate(domain: string): Promise<GenerateDomainTrackingCertificateResponse>;
+    regenerate(domain: string): Promise<RegenerateDomainTrackingCertificateResponse>;
+    getTracking(domain: string): Promise<DomainTrackingData>;
+    updateTracking(domain: string, type: string, data: OpenTrackingInfo | ClickTrackingInfo | UnsubscribeTrackingInfo): Promise<UpdatedOpenTracking>;
+}

package/Interfaces/Domains/DomainTracking.d.ts

@@ -0,0 +1,8 @@
+import { ClickTrackingInfo, DomainTrackingData, GenerateDomainTrackingCertificateResponse, GetDomainTrackingCertificateResponse, OpenTrackingInfo, RegenerateDomainTrackingCertificateResponse, UnsubscribeTrackingInfo, UpdatedOpenTracking } from '../../Types';
+export interface IDomainTrackingClient {
+    get(domain: string): Promise<GetDomainTrackingCertificateResponse>;
+    generate(domain: string): Promise<GenerateDomainTrackingCertificateResponse>;
+    regenerate(domain: string): Promise<RegenerateDomainTrackingCertificateResponse>;
+    getTracking(domain: string): Promise<DomainTrackingData>;
+    updateTracking(domain: string, type: string, data: OpenTrackingInfo | ClickTrackingInfo | UnsubscribeTrackingInfo): Promise<UpdatedOpenTracking>;
+}

package/Interfaces/Domains/DomainsClient.d.ts

@@ -3,10 +3,12 @@ import { ClickTrackingInfo, ConnectionSettings, DKIMAuthorityInfo, DKIMSelectorI
 import { IDomainCredentials } from './DomainCredentials';
 import { IDomainTagsClient } from './DomainTags';
 import { IDomainTemplatesClient } from './DomainTemplates';
+import { IDomainTrackingClient } from './DomainTracking';
 export interface IDomainsClient {
     domainCredentials: IDomainCredentials;
     domainTemplates: IDomainTemplatesClient;
     domainTags: IDomainTagsClient;
+    domainTracking: IDomainTrackingClient;
     list(query?: DomainsQuery): Promise<TDomain[]>;
     get(domain: string, query?: DomainGetQuery): Promise<TDomain>;
     create(data: DomainInfo): Promise<TDomain>;

package/Interfaces/Domains/index.d.ts

@@ -2,3 +2,4 @@ export * from './DomainCredentials';
 export * from './DomainTags';
 export * from './DomainTemplates';
 export * from './DomainsClient';
+export * from './DomainTracking';

package/README.md

@@ -149,6 +149,9 @@ The following service methods are available to instantiated clients. The example
       - [createVersion](#createversion)
       - [updateVersion](#updateversion)
       - [destroyVersion](#destroyversion)
+    - [domain tracking](#domain-tracking)
+      - [getTracking](#gettracking-1)
+      - [updateTracking](#updatetracking-1)
     - [events](#events)
       - [get](#get-2)
         - [Example with Date and *Filter field*](#example-with-date-and-filter-field)
@@ -906,133 +909,11 @@ The following service methods are available to instantiated clients. The example
   }
   ```
 
-
 - #### getTracking
-  Mailgun offers tracking for clicks, unsubscribes, and opens, with optional HTTPS protocol support on tracking URLs. To enable HTTPS, Mailgun uses Let’s Encrypt with HTTP-01 challenges through your existing tracking CNAME record to issue a TLS certificate. This setup also includes support for HTTP Strict Transport Security (HSTS) for enhanced security.
-
-  `mg.domains.getTracking(domainAddress)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Tracking/#tag/Domain-Tracking)
-
-  Example:
-
-  ```JS
-  mg.domains.getTracking('foobar.example.com')
-    .then(msg => console.log(msg)) // logs response data
-    .catch(err => console.error(err)); // logs any error
-  ```
-
-  Promise returns:
-
-  ```JS
-  {
-    "click": {
-      "active": false
-    },
-    "open": {
-      "active": false
-    },
-    "unsubscribe": {
-      "active": false,
-      "html_footer": "\n<br>\n<p><a href=\"%unsubscribe_url%\">unsubscribe</a></p>\n",
-      "text_footer": "\n\nTo unsubscribe click: <%unsubscribe_url%>\n\n"
-    }
-  }
-  ```
+  `domains.getTracking` method is deprecated, and will be removed. Please use `domains.domainTracking.getTracking` instead.
 
 - #### updateTracking
-  A common method to turn on/off the click, open, and unsubscribe tracking at the domain level.
-
-  `mg.domains.updateTracking(domain, trackingType, data)`
-
-  - Open Tracking Example:
-
-    [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Tracking/#tag/Domain-Tracking/operation/PUT-v3-domains--name--tracking-open)
-    ```js
-    mg.domains.updateTracking('foobar.example.com', 'open', {
-      active: true,
-      place_at_the_top: true,
-    })
-      .then(msg => console.log(msg)) // logs response data
-      .catch(err => console.error(err)); // logs any error
-    ```
-
-    Open tracking data object properties:
-
-    | Property | Description                                |
-    |:----------|:-------------------------------------------|
-    | active    | Boolean, enables or disables open tracking |
-    | place_at_the_top| Setting this param to true will place the open tracking pixel at the top of the HTML body when inserted into the email mime. Omit this param to keep current setting. |
-
-    Promise returns:
-
-    ```JS
-    {
-      message: 'Tracking settings have been updated',
-      open: {
-        active: true,
-        place_at_the_top: true,
-      }
-    }
-    ```
-
-  - Click Tracking Example:
-
-    [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Tracking/#tag/Domain-Tracking/operation/PUT-v3-domains--name--tracking-click)
-    ```JS
-    mg.domains.updateTracking('foobar.example.com', 'click', {active: true})
-      .then(msg => console.log(msg)) // logs response data
-      .catch(err => console.error(err)); // logs any error
-    ```
-
-    Click tracking data object properties:
-
-    | Property | Description                                 |
-    |:----------|:--------------------------------------------|
-    | active    | Boolean, enables or disables click tracking |
-
-    Promise returns:
-
-    ```JS
-    {
-      message: 'Tracking settings have been updated',
-      click: {
-        active: true
-      }
-    }
-    ```
-
-  - Unsubscribe Tracking Example
-
-    [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Tracking/#tag/Domain-Tracking/operation/PUT-v3-domains--name--tracking-unsubscribe)
-    ```js
-    mg.domains.updateTracking('foobar.example.com', 'unsubscribe', {
-        active: true,
-        html_footer: "\n<br>\n<p><a href=\"%unsubscribe_url%\">unsubscribe</a></p>\n",
-        text_footer: "\n\nTo unsubscribe click: <%unsubscribe_url%>\n\n"
-      })
-      .then(msg => console.log(msg)) // logs response data
-      .catch(err => console.error(err)); // logs any error
-    ```
-
-    Unsubscribe Tracking data object properties:
-
-    | Property   | Description                                                   |
-    |:------------|:--------------------------------------------------------------|
-    | active      | Boolean, enables or disables unsubscribe tracking             |
-    | html_footer | string appended to html emails for managing unsubscribe links |
-    | text_footer | string appended to html emails for managing unsubscribe links |
-
-    Promise returns:
-
-    ```JS
-    {
-      message: 'Tracking settings have been updated',
-      unsubscribe: {
-        active: true,
-        html_footer: '\n<br>\n<p><a href=\'%unsubscribe_url%\">unsubscribe</a></p>\n',
-        text_footer: '\n\nTo unsubscribe click: <%unsubscribe_url%>\n\n'
-      }
-    }
-    ```
+   `domains.updateTracking` method is deprecated, and will be removed. Please use `domains.domainTracking.updateTracking` instead.
 
 - #### getConnection
   Returns domain's delivery connection settings.
@@ -1644,6 +1525,207 @@ The following service methods are available to instantiated clients. The example
     }
     ```
 
+### Domain tracking
+
+- #### getTracking
+
+  Mailgun offers tracking for clicks, unsubscribes, and opens, with optional HTTPS protocol support on tracking URLs. To enable HTTPS, Mailgun uses Let’s Encrypt with HTTP-01 challenges through your existing tracking CNAME record to issue a TLS certificate. This setup also includes support for HTTP Strict Transport Security (HSTS) for enhanced security.
+
+  `mg.domains.domainTracking.getTracking(domainAddress)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Tracking/#tag/Domain-Tracking)
+
+  Example:
+
+  ```JS
+  mg.domains.domainTracking.getTracking('foobar.example.com')
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns:
+
+  ```JS
+  {
+    "click": {
+      "active": false
+    },
+    "open": {
+      "active": false
+    },
+    "unsubscribe": {
+      "active": false,
+      "html_footer": "\n<br>\n<p><a href=\"%unsubscribe_url%\">unsubscribe</a></p>\n",
+      "text_footer": "\n\nTo unsubscribe click: <%unsubscribe_url%>\n\n"
+    }
+  }
+  ```
+
+- #### updateTracking
+
+  A common method to turn on/off the click, open, and unsubscribe tracking at the domain level.
+
+  `mg.domains.domainTracking.updateTracking(domain, trackingType, data)`
+
+  - Open Tracking Example:
+
+    [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Tracking/#tag/Domain-Tracking/operation/PUT-v3-domains--name--tracking-open)
+    ```js
+    mg.domains.domainTracking.updateTracking('foobar.example.com', 'open', {
+      active: true,
+      place_at_the_top: true,
+    })
+      .then(msg => console.log(msg)) // logs response data
+      .catch(err => console.error(err)); // logs any error
+    ```
+
+    Open tracking data object properties:
+
+    | Property | Description                                |
+    |:----------|:-------------------------------------------|
+    | active    | Boolean, enables or disables open tracking |
+    | place_at_the_top| Setting this param to true will place the open tracking pixel at the top of the HTML body when inserted into the email mime. Omit this param to keep current setting. |
+
+    Promise returns:
+
+    ```JS
+    {
+      message: 'Tracking settings have been updated',
+      open: {
+        active: true,
+        place_at_the_top: true,
+      }
+    }
+    ```
+
+  - Click Tracking Example:
+
+    [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Tracking/#tag/Domain-Tracking/operation/PUT-v3-domains--name--tracking-click)
+    ```JS
+    mg.domains.domainTracking.updateTracking('foobar.example.com', 'click', {active: true})
+      .then(msg => console.log(msg)) // logs response data
+      .catch(err => console.error(err)); // logs any error
+    ```
+
+    Click tracking data object properties:
+
+    | Property | Description                                 |
+    |:----------|:--------------------------------------------|
+    | active    | Boolean, enables or disables click tracking |
+
+    Promise returns:
+
+    ```JS
+    {
+      message: 'Tracking settings have been updated',
+      click: {
+        active: true
+      }
+    }
+    ```
+
+  - Unsubscribe Tracking Example
+
+    [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Tracking/#tag/Domain-Tracking/operation/PUT-v3-domains--name--tracking-unsubscribe)
+    ```js
+    mg.domains.domainTracking.updateTracking('foobar.example.com', 'unsubscribe', {
+        active: true,
+        html_footer: "\n<br>\n<p><a href=\"%unsubscribe_url%\">unsubscribe</a></p>\n",
+        text_footer: "\n\nTo unsubscribe click: <%unsubscribe_url%>\n\n"
+      })
+      .then(msg => console.log(msg)) // logs response data
+      .catch(err => console.error(err)); // logs any error
+    ```
+
+    Unsubscribe Tracking data object properties:
+
+    | Property   | Description                                                   |
+    |:------------|:--------------------------------------------------------------|
+    | active      | Boolean, enables or disables unsubscribe tracking             |
+    | html_footer | string appended to html emails for managing unsubscribe links |
+    | text_footer | string appended to html emails for managing unsubscribe links |
+
+    Promise returns:
+
+    ```JS
+    {
+      message: 'Tracking settings have been updated',
+      unsubscribe: {
+        active: true,
+        html_footer: '\n<br>\n<p><a href=\'%unsubscribe_url%\">unsubscribe</a></p>\n',
+        text_footer: '\n\nTo unsubscribe click: <%unsubscribe_url%>\n\n'
+      }
+    }
+    ```
+
+- #### get
+  Get x509 TLS certificate and status
+
+  `mg.domains.domainTracking.get(domainAddress)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Tracking/#tag/Domain-Tracking/operation/httpapi.(*HttpAPI).getStatusV2-fm-8)
+
+  Example:
+
+  ```JS
+  mg.domains.domainTracking.get('foobar.example.com')
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns:
+
+  ```JS
+  {
+    responseStatusCode: 200,
+    status: 'expired',
+    error: 'x509 certificate has expired',
+    certificate: '{CERT}';
+  }
+  ```
+
+- #### generate
+  Initiates generation of a TLS certificate for the tracking domain in a background task. Once generation is enqueued, you may poll the status endpoint in location field to check for success
+
+  `mg.domains.domainTracking.generate(domainAddress)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Tracking/#tag/Domain-Tracking/operation/httpapi.(*HttpAPI).generateStatusV2-fm-8)
+
+  Example:
+
+  ```JS
+  mg.domains.domainTracking.generate('foobar.example.com')
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns:
+
+  ```JS
+  {
+    message: 'Initiated x509 key pair generation',
+    location: '/v2/x509/example.com/status',
+    status: 202,
+  }
+  ```
+
+- #### regenerate
+  Initiates regeneration of an expired TLS certificate for the tracking domain in a background task. Once generation is enqueued, you may poll status endpoint in location field to check for success. This will not regenerate an existing certificate that is still valid
+
+  `mg.domains.domainTracking.regenerate(domainAddress)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Tracking/#tag/Domain-Tracking/operation/httpapi.(*HttpAPI).generateStatusV2-fm-8)
+
+  Example:
+
+  ```JS
+  mg.domains.domainTracking.regenerate('foobar.example.com')
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns:
+
+  ```JS
+  {
+    message: 'Initiated x509 key pair generation',
+    location: '/v2/x509/example.com/status',
+    status: 202,
+  }
+  ```
+
 ### Events
 
 - #### get

package/Types/Domains/DomainTracking.d.ts

@@ -47,3 +47,19 @@ export type UnsubscribeTrackingInfo = {
     html_footer?: string;
     text_footer?: string;
 };
+export type GetDomainTrackingCertificateResponse = {
+    responseStatusCode: number;
+    status: string;
+    error: string;
+    certificate: string;
+};
+export type GenerateDomainTrackingCertificateResponse = {
+    message: string;
+    location: string;
+    status: number;
+};
+export type RegenerateDomainTrackingCertificateResponse = {
+    message: string;
+    location: string;
+    status: number;
+};

package/Types/SecureTracking/SecureTracking.d.ts

@@ -0,0 +1,13 @@
+export type GetDomainTrackingCertificateResponse = {
+    status: string;
+    error: string;
+    certificate: string;
+};
+export type GenerateDomainTrackingCertificateResponse = {
+    message: string;
+    location: string;
+};
+export type RegenerateDomainTrackingCertificateResponse = {
+    message: string;
+    location: string;
+};

package/Types/SecureTracking/index.d.ts

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