mailgun.js 10.3.0 → 11.0.0

package/README.md

@@ -127,61 +127,82 @@ The following service methods are available to instantiated clients. The example
       - [get](#get)
       - [create](#create-1)
       - [update](#update)
+      - [verify](#verify)
       - [destroy](#destroy)
       - [getTracking](#gettracking)
       - [updateTracking](#updatetracking)
+      - [getConnection](#getconnection)
+      - [updateConnection](#updateconnection)
+      - [updateDKIMAuthority](#updatedkimauthority)
+      - [updateDKIMSelector](#updatedkimselector)
       - [getIps](#getips)
       - [assignIp](#assignip)
-    - [events](#events)
+    - [domain templates](#domain-templates)
+      - [list](#list-1)
       - [get](#get-1)
+      - [create](#create-2)
+      - [update](#update-1)
+      - [destroy](#destroy-1)
+      - [destroyAll](#destroyall)
+      - [listVersions](#listversions)
+      - [getVersion](#getversion)
+      - [createVersion](#createversion)
+      - [updateVersion](#updateversion)
+      - [destroyVersion](#destroyversion)
+    - [events](#events)
+      - [get](#get-2)
         - [Example with Date and *Filter field*](#example-with-date-and-filter-field)
     - [stats](#stats)
+      - [Stats Options](#stats-options)
       - [getDomain](#getdomain)
       - [getAccount](#getaccount)
+    - [metrics](#metrics)
+      - [getAccount](#getaccount-1)
+      - [getAccountUsage](#getaccountusage)
     - [suppressions](#suppressions)
-      - [list](#list-1)
+      - [list](#list-2)
         - [Bounces Example](#bounces-example)
         - [Unsubscribes Example](#unsubscribes-example)
         - [Complaints Example](#complaints-example)
-      - [get](#get-2)
+      - [get](#get-3)
         - [Bounces Example](#bounces-example-1)
         - [Unsubscribes Example](#unsubscribes-example-1)
         - [Complaints Example](#complaints-example-1)
-      - [create](#create-2)
+      - [create](#create-3)
         - [Bounces Example](#bounces-example-2)
         - [Unsubscribes Example](#unsubscribes-example-2)
           - [Unsubscribe from one tag](#unsubscribe-from-one-tag)
           - [Unsubscribe from particular tags](#unsubscribe-from-particular-tags)
         - [Complaints Example](#complaints-example-2)
-      - [destroy](#destroy-1)
+      - [destroy](#destroy-2)
         - [Bounces Example](#bounces-example-3)
         - [Unsubscribes Example](#unsubscribes-example-3)
         - [Complaints Example](#complaints-example-3)
     - [webhooks](#webhooks)
-      - [list](#list-2)
-      - [get](#get-3)
-      - [create](#create-3)
-      - [update](#update-1)
-      - [destroy](#destroy-2)
-    - [routes](#routes)
       - [list](#list-3)
       - [get](#get-4)
       - [create](#create-4)
       - [update](#update-2)
       - [destroy](#destroy-3)
-    - [validate](#validate)
-      - [get](#get-5)
-    - [multiple validation](#multiple-validation)
-      - [create](#create-5)
+    - [routes](#routes)
       - [list](#list-4)
       - [get](#get-5)
+      - [create](#create-5)
+      - [update](#update-3)
       - [destroy](#destroy-4)
-    - [mailing lists](#mailing-lists)
-      - [list](#list-5)
+    - [validate](#validate)
       - [get](#get-6)
+    - [multiple validation](#multiple-validation)
       - [create](#create-6)
-      - [update](#update-3)
+      - [list](#list-5)
+      - [get](#get-7)
       - [destroy](#destroy-5)
+    - [mailing lists](#mailing-lists)
+      - [list](#list-6)
+      - [get](#get-8)
+      - [create](#create-7)
+      - [update](#update-4)
+      - [destroy](#destroy-6)
     - [mailing list members](#mailing-list-members)
       - [listMembers](#listmember)
       - [getMember](#getmember)
@@ -190,38 +211,38 @@ The following service methods are available to instantiated clients. The example
       - [updateMember](#updatemember)
       - [destroyMember](#destroymember)
     - [subaccounts](#subaccounts)
-      - [list](#list-6)
-      - [get](#get-8)
-      - [create](#create-7)
+      - [list](#list-7)
+      - [get](#get-9)
+      - [create](#create-8)
       - [enable](#enable)
       - [disable](#disable)
-    - [Inbox Placements](#inbox-placements)
+    - [inbox placements](#inbox-placements)
       - [SeedsLists](#seedslists)
-        - [list](#list-7)
-        - [get](#get-9)
-        - [create](#create-8)
-        - [update](#update-4)
-        - [destroy](#destroy-6)
+        - [list](#list-8)
+        - [get](#get-10)
+        - [create](#create-9)
+        - [update](#update-5)
+        - [destroy](#destroy-7)
         - [SeedsLists Attributes](#attributes)
-          - [list](#list-8)
-          - [get](#get-10)
-        - [SeedsLists Filters](#filters)
           - [list](#list-9)
+          - [get](#get-11)
+        - [SeedsLists Filters](#filters)
+          - [list](#list-10)
       - [Providers](#providers)
-        - [list](#list-10)
-      - [Results](#results)
         - [list](#list-11)
-        - [get](#get-11)
-        - [destroy](#destroy-7)
+      - [Results](#results)
+        - [list](#list-12)
+        - [get](#get-12)
+        - [destroy](#destroy-8)
         - [getResultByShareId](#getresultbyshareid)
         - [Results Attributes](#attributes-1)
-          - [list](#list-12)
-          - [get](#get-12)
-        - [Results Filters](#filters-1)
           - [list](#list-13)
-        - [Sharing](#sharing)
           - [get](#get-13)
-          - [update](#update-5)
+        - [Results Filters](#filters-1)
+          - [list](#list-14)
+        - [Sharing](#sharing)
+          - [get](#get-14)
+          - [update](#update-6)
       - [Run Test](#run-test)
   - [Navigation thru lists](#navigation-thru-lists)
   - [Browser Demo](#browser-demo)
@@ -517,10 +538,11 @@ The following service methods are available to instantiated clients. The example
   ```
 
 ### Domains
+  Domains API manages domains, domain keys and DNS verification.
 
 - #### list
-
-  `mg.domains.list(query)` - [api docs](https://documentation.mailgun.com/en/latest/api-domains.html)
+  Get the list of domains. Can be filtered by state or authority. Sorting is optional. The list is paginated and limited to 1000 items per page.
+  `mg.domains.list(query)` - [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domains/#tag/Domains/operation/GET-v4-domains)
 
   Example:
 
@@ -534,18 +556,23 @@ The following service methods are available to instantiated clients. The example
 
   ```JS
   [{
-    created_at: 'Sun, 19 Oct 2014 18:49:36 GMT',
     name: 'testing.example.com',
-    receiving_dns_records: null,
     require_tls: true,
-    sending_dns_records: null,
     skip_verification: true,
-    smtp_login: 'postmaster@testing.example.com',
-    smtp_password: 'password',
-    spam_action: 'disabled',
     state: 'unverified',
-    type: 'custom',
     wildcard: true
+    spam_action: 'disabled',
+    created_at: 'Sun, 19 Oct 2014 18:49:36 GMT',
+    smtp_password: undefined,
+    smtp_login: 'postmaster@testing.example.com',
+    type: 'custom',
+    receiving_dns_records: null,
+    sending_dns_records: null,
+    id: '697d01d38712cf0322bb24d1',
+    is_disabled: false,
+    web_prefix: 'test',
+    web_scheme: 'https',
+    use_automatic_sender_security: true
   }]
   ```
 
@@ -555,159 +582,248 @@ The following service methods are available to instantiated clients. The example
   |:----------|:------------------------------------------------------|
   | limit     | Maximum number of records to return. (100 by default) |
   | skip      | Number of records to skip. (0 by default)             |
+  | state     | To only get domains with a specific state. Can be either active, unverified or disabled. |
+  | sort      | Valid sort options are **name** which defaults to asc order, **name:asc**, or **name:desc**. If sorting is not specified domains are returned in reverse creation date order. |
+  | authority | To only get domains with a specific authority. If state is specified then only state filtering will be proceed |
+  | search    | Search domains by the given partial or complete name. Does not support wildcards|
 
 - #### get
+  Fetches representation of a domain that includes details about the domain's state and settings.
 
-  `mg.domains.get(domain)`
+  `mg.domains.get(domain, query)`  - [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domains/#tag/Domains/operation/GET-v4-domains--name-)
 
   Example:
 
   ```JS
-  mg.domains.get('testing.example.com')
-    .then(domains => console.log(domains)) // logs domain object
+  mg.domains.get('testing.example.com', {
+    extended: true
+  })
+    .then(domain => console.log(domain)) // logs domain object
     .catch(err => console.error(err)); // logs any error
   ```
 
+   Query object may have next properties:
+
+  | Property | Description                                           |
+  |:----------|:------------------------------------------------------|
+  | extended  | Default to false. If set to true, domain payload will include dkim_host, mailfrom_host and pod |
+  | with_dns  | Default to true, domain payload will include sending and receiving dns records payload|
+
   Promise returns: Domain instance
 
   ```JS
   {
-    created_at: 'Sun, 19 Oct 2014 18:49:36 GMT',
     name: 'testing.example.com',
-    receiving_dns_records: [{
-        "name": "testing.example.com",
-        "record_type": "TXT",
-        "valid": "unknown",
-        "value": "v=spf1 include:mailgun.org ~all"
-      },
-      {
-        "name": "k1._domainkey.testing.example.com",
-        "record_type": "TXT",
-        "valid": "unknown",
-        "value": "k=rsa; 123456"
-      },
-      {
-        "name": "email.testing.example.com",
-        "record_type": "CNAME",
-        "valid": "unknown",
-        "value": "mailgun.org"
-      }],
     require_tls: true,
-    sending_dns_records: [{
-        "priority": "10",
-        "record_type": "MX",
-        "valid": "unknown",
-        "value": "mxa.mailgun.org"
-      },
-      {
-        "priority": "10",
-        "record_type": "MX",
-        "valid": "unknown",
-        "value": "mxb.mailgun.org"
-      }],
     skip_verification: true,
-    smtp_login: 'postmaster@testing.example.com',
-    smtp_password: 'password',
-    spam_action: 'disabled',
     state: 'unverified',
-    type: 'custom',
     wildcard: true,
-    id: '64a4291ebbe4ec7e1d78bc80',
+    spam_action: 'disabled',
+    created_at: new Date('Sun, 19 Oct 2014 18:49:36 GMT'),
+    smtp_password: undefined,
+    smtp_login: 'postmaster@testing.example.com',
+    type: 'custom',
+    receiving_dns_records: [ // may be null if with_dns is set to false.
+      {
+        is_active: true,
+        cached: [],
+        priority: '10',
+        record_type: 'TXT',
+        valid: "unknown",
+        value: "dns_record_value"
+      },
+      ...
+      ],
+    sending_dns_records: [ // may be null if with_dns is set to false.
+      {
+        is_active: true,
+        cached: [],
+        name: 'dns_record_name',
+        record_type: 'CNAME',
+        valid: 'unknown',
+        value: 'dns_record_value'
+      },
+      ...
+      ],
+    id: '697d01d38712cf0322bb24d1',
     is_disabled: false,
     web_prefix: 'email',
-    web_scheme: 'http'
+    web_scheme: 'http',
+    use_automatic_sender_security: true,
+    dkim_host: 'dkim_host_value', // absent if 'extended' was not set to true.
+    mailfrom_host: 'mailfrom_host_value', // absent if 'extended' was not set to true.
   }
   ```
 
 - #### create
+  Creates a domain for sending emails
 
-  `mg.domains.create(data)`
+  `mg.domains.create(data)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domains/#tag/Domains/operation/POST-v4-domains)
 
   Example:
 
   ```js
-  mg.domains.create({name: 'foobar.example.com'})
-    .then(msg => console.log(msg)) // logs response data
+  mg.domains.create({
+    name: 'foobar.example.com',
+    dkim_key_size: 1024,
+    dkim_selector: 's1',
+    encrypt_incoming_message: true,
+    force_dkim_authority: false,
+    force_root_dkim_host: false,
+    wildcard: true,
+    pool_id: 'pool_id',
+    ips: '',
+    spam_action: 'tag',
+    smtp_password: 'smtp_password_value',
+    use_automatic_sender_security: true,
+    web_prefix: 'test',
+    web_scheme: 'https',
+  })
+    .then(data => console.log(data)) // logs response data
     .catch(err => console.error(err)); // logs any error
   ```
 
   Create method accepts data object with next properties:
 
-  | Parameter 	| Description 	|
-  |---	|---	|
-  | name 	| Name of the domain (ex. domain.com) 	|
-  | smtp_password 	| Password for SMTP authentication 	|
-  | spam_action 	| `disabled`, `block`, or `tag`<br>If `disabled`, no spam filtering will occur for inbound messages.<br>If `block`, inbound spam messages will not be delivered.<br>If `tag`, inbound messages will be tagged with a spam header. [Spam Filter](https://documentation.mailgun.com/en/latest/user_manual.html#um-spam-filter)<br>The default is `disabled`. 	|
-  | wildcard 	| Can be string `'true'` or `'false'` or `boolean`<br>Determines whether the domain will accept email for sub-domains when sending messages.<br>The default is `false`. 	|
-  | force_dkim_authority 	| Can be string `'true'` or `'false'` or `boolean`<br>If set to `true`, the domain will be the DKIM authority for itself even if the root domain is registered on the same mailgun account<br>If set to `false`, the domain will have the same DKIM authority as the root domain registered on the same mailgun account<br>The default is `false`. 	|
-  | dkim_key_size 	| **1024** or **2048**<br>Set the length of your domain’s generated DKIM key<br>The default is **1024** 	|
-  | ips 	| An optional, comma-separated list of IP addresses to be assigned to this domain. If not specified, all dedicated IP addresses on the account will be assigned. If the request cannot be fulfilled (e.g. a requested IP is not assigned to the account, etc), a 400 will be returned. 	|
-  | pool_id 	| The id of the IP Pool that you wish to assign to the domain. The pool must contain at least 1 IP. (Note: IP Pools are only available on certain plans; see http://mailgun.com/pricing) 	|
-  | web_scheme 	| String with `http` or `https`<br>Set your **open**, **click** and **unsubscribe** URLs to use `http` or `https`<br>The default is `http` 	|
+  | Parameter   | Description   |
+  |---  |---  |
+  | name (required) | Name of the domain (ex. domain.com) |
+  | dkim_host_name  | Set the DKIM host name for the domain that is being created. Note, the value must be a valid domain name, and can be the domain name being created, a subdomain of the domain being created, or the root domain. This parameter cannot be used in conjunction with `force_dkim_authority` or `force_root_dkim_host`. |
+  | dkim_key_size   | **1024** or **2048**<br>Set the length of your domain’s generated DKIM key<br>The default is **1024**   |
+  | dkim_selector | Explicitly set the value of the DKIM selector for the domain being created. If the domain key does not already exist, one will be created. The selector must be a valid atom per RFC2822. e.g valid value foobar, invalid value foo.bar https://datatracker.ietf.org/doc/html/rfc2822#section-3.2.4|
+  | encrypt_incoming_message  | Enable encrypting incoming messages for the given domain. This cannot be altered via API after being set for security purposes. Reach out to Support to disable if necessary. Default to false|
+  | force_dkim_authority| If set to true, the domain will be the DKIM authority for itself even if the root domain is registered on the same mailgun account. If set to false, the domain will have the same DKIM authority as the root domain registered on the same mailgun account. Default to false. |
+  | force_root_dkim_host | If set to true, the root domain will be the DKIM Host for the domain being created even if the root domain itself is not registered with Mailgun. The domain being created will still need to pass domain verification with valid spf records for the domain and valid DKIM record for the root domain. This does not effect the smtp mail-from host for the domain being created. The mail-from host will remain the domain name being created, not the root domain.|
+  | wildcard  | Determines whether the domain will accept email for sub-domains when sending messages. Default to false. |
+  | pool_id   | Requested IP Pool to be assigned to the domain at creation. |
+  | ips   | An optional, comma-separated list of IP addresses to be assigned to this domain. If not specified, all dedicated IP addresses on the account will be assigned. If the request cannot be fulfilled (e.g. a requested IP is not assigned to the account, etc), a 400 will be returned.  |
+  | spam_action   | `disabled`, `block`, or `tag`<br>If `disabled`, no spam filtering will occur for inbound messages.<br>If `block`, inbound spam messages will not be delivered.<br>If `tag`, inbound messages will be tagged with a spam header. [Spam Filter](https://documentation.mailgun.com/en/latest/user_manual.html#um-spam-filter)<br>The default is `disabled`.  |
+  | smtp_password   | Password for SMTP authentication  |
+  | use_automatic_sender_security | Enable Automatic Sender Security. This requires setting DNS CNAME entries for DKIM keys instead of a TXT record. Defaults to false. |
+  | web_prefix | Sets your open, click and unsubscribe URLs domain name prefix. Links rewritten or added by Mailgun in your emails will look like ://./... Default to email |
+  | web_scheme  |Sets your open, click and unsubscribe URLs to use http or https. Value either `http` or `https`. Defaults to http. In order for https to work, you must have a valid cert created for your domain. See Domain Tracking for TLS cert generation. |
 
   Promise returns:
 
   ```JS
-  name: 'foobar.example.com',
-  require_tls: false,
-  skip_verification: false,
-  state: 'unverified',
-  wildcard: false,
-  spam_action: 'disabled',
-  created_at: 'Tue, 04 Jul 2023 14:09:18 GMT',
-  smtp_password: undefined,
-  smtp_login: 'postmaster@foobar.example.com',
-  type: 'custom',
-  receiving_dns_records: [{
-      "name": "foobar.example.com",
-      "record_type": "TXT",
-      "valid": "unknown",
-      "value": "v=spf1 include:mailgun.org ~all"
-    },
-    {
-      "name": "k1._domainkey.foobar.example.com",
-      "record_type": "TXT",
-      "valid": "unknown",
-      "value": "k=rsa; 123456"
-    },
-    {
-      "name": "email.foobar.example.com",
-      "record_type": "CNAME",
-      "valid": "unknown",
-      "value": "mailgun.org"
-    }
-  ],
-  sending_dns_records: [{
-      "priority": "10",
-      "record_type": "MX",
-      "valid": "unknown",
-      "value": "mxa.mailgun.org"
-    },
-    {
-      "priority": "10",
-      "record_type": "MX",
-      "valid": "unknown",
-      "value": "mxb.mailgun.org"
-  }],
-  id: '64a4291ebbe4ec7e1d78bc80',
-  is_disabled: false,
-  web_prefix: 'email',
-  web_scheme: 'http'
+  {
+    name: 'foobar.example.com',
+    require_tls: false,
+    skip_verification: false,
+    state: 'unverified',
+    wildcard: true,
+    spam_action: 'tag',
+    created_at: 2025-01-08T12:52:29.000Z,
+    smtp_password: undefined,
+    smtp_login: new Date('postmaster@foobar.example.com'),
+    type: 'custom',
+    receiving_dns_records: [
+      {
+        is_active: true,
+        cached: [],
+        priority: '10',
+        record_type: 'MX',
+        valid: 'unknown',
+        value: 'dns_record_value'
+      },
+      ...
+    ],
+    sending_dns_records: [
+      {
+        is_active: false,
+        cached: [],
+        name: 'sending_dns_record_name',
+        record_type: 'CNAME',
+        valid: 'unknown',
+        value: 'sending_dns_record_value'
+      },
+      ...
+    ],
+    id: '64a4291ebbe4ec7e1d78bc80',
+    is_disabled: false,
+    web_prefix: 'test',
+    web_scheme: 'https',
+    use_automatic_sender_security: true
+  }
+  ```
+
+- #### verify
+  Verify the domains DNS records (includes A, CNAME, SPF, DKIM and MX records) to ensure the domain is ready and able to send
+
+  `mg.domains.verify(domainAddress)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domains/#tag/Domains/operation/PUT-v4-domains--name--verify)
+
+  Example:
+
+  ```JS
+  mg.domains.destroy('foobar.example.com')
+    .then(data => console.log(data)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns:
+
+  ```JS
+  {
+    name: 'foobar.example.com',
+    require_tls: false,
+    skip_verification: false,
+    state: 'active',
+    wildcard: false,
+    spam_action: 'tag',
+    created_at: new Date('2017-10-05T14:55:20.000Z'),
+    smtp_password: undefined,
+    smtp_login: 'postmaster@foobar.example.com',
+    type: 'custom',
+    receiving_dns_records: [
+      {
+        is_active: true,
+        cached: [Array],
+        priority: '10',
+        record_type: 'MX',
+        valid: 'valid',
+        value: 'receiving_dns_record_value'
+      },
+      ...
+    ],
+    sending_dns_records: [
+      {
+        is_active: true,
+        cached: [],
+        name: 'foobar.example.com',
+        record_type: 'CNAME',
+        valid: 'unknown',
+        value: 'sending_dns_record_value'
+      },
+      ...
+    ],
+    id: '64a5880eere4eg7e1d85bc69',
+    is_disabled: false,
+    web_prefix: 'email',
+    web_scheme: 'https',
+    use_automatic_sender_security: true
+  }
   ```
 
+
 - #### update
+  Update domains configuration like smtp credentials, enable/disable automatic sender security, spam actions, wildcard, or tracking web scheme.
 
-  `mg.domains.update(domain, options)`
+  `mg.domains.update(domain, options)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domains/#tag/Domains/operation/PUT-v4-domains--name-)
 
   Example:
 
   ```js
   mg.domains.update('foobar.example.com',{
-      wildcard: 'true',
+      mailfrom_host: 'mailfrom_host_value',
+      message_ttl: 20,
+      smtp_password: 'smtp_password_value'
+      spam_action: 'tag',
+      use_automatic_sender_security: true
       web_scheme: 'http',
-      spam_action: 'disabled',
+      web_prefix: 'web_prefix_value'
+      wildcard: 'true',
     })
-    .then(msg => console.log(msg)) // logs response data
+    .then(data => console.log(data)) // logs response data
     .catch(err => console.error(err)); // logs any error
   ```
 
@@ -715,8 +831,13 @@ The following service methods are available to instantiated clients. The example
 
   | Property    | Description                                                                                                                                   |
   |:--------------|:----------------------------------------------------------------------------------------------------------------------------------------------|
+  | mailfrom_host | The hostname to update to. Must be in lower case |
+  | message_ttl   | Duration of the message retrieval TTL in seconds |
+  | smtp_password | Updates the domain's SMTP credentials with the given string |
   | spam_action   | Can be string with value `disabled`, `block`, or `tag`. If *disabled*, no spam filtering will occur for inbound messages. If `block`, inbound spam messages will not be delivered. If `tag`, inbound messages will be tagged with a spam header. See [Spam Filter](https://documentation.mailgun.com/en/latest/user_manual.html#um-spam-filter).|
+  | use_automatic_sender_security | enable or disable Automatic Sender Security. If enabled, requires setting DNS CNAME entries for DKIM keys instead of a TXT record. Domain must be reverified after changing this field. Defaults to `false`|
   | web_scheme | Can be string with value `http` or `https`. Set your **open**, **click** and **unsubscribe** URLs to use `http` or `https`. The default is `http`|
+  | web_prefix | Web prefix to be used for tracking. Must be a valid atom. Nothing will be updated if omitted |
   | wildcard   | Can be string `'true'` or `'false'` or `boolean`. Determines whether the domain will accept email for sub-domains. The default is `false`.|
 
   Promise returns:
@@ -729,7 +850,7 @@ The following service methods are available to instantiated clients. The example
     state: 'unverified',
     wildcard: true,
     spam_action: 'disabled',
-    created_at: 'Tue, 04 Jul 2023 14:09:18 GMT',
+    created_at: new Date('2025-01-08T12:52:29.000Z'),
     smtp_password: undefined,
     smtp_login: 'postmaster@foobar.example.com',
     type: 'custom',
@@ -740,16 +861,9 @@ The following service methods are available to instantiated clients. The example
         priority: '10',
         record_type: 'MX',
         valid: 'unknown',
-        value: 'mxa.mailgun.org'
+        value: 'receiving_dns_record_value'
       },
-      {
-        is_active: true,
-        cached: [],
-        priority: '10',
-        record_type: 'MX',
-        valid: 'unknown',
-        value: 'mxb.mailgun.org'
-      }
+      ...
     ],
     sending_dns_records: [
       {
@@ -758,214 +872,778 @@ The following service methods are available to instantiated clients. The example
         name: 'foobar.example.com',
         record_type: 'TXT',
         valid: 'unknown',
-        value: 'v=spf1 include:mailgun.org ~all'
+        value: 'sending_dns_record_value'
       },
-      {
-        is_active: true,
-        cached: [],
-        name: 'email.foobar.example.com',
-        record_type: 'CNAME',
-        valid: 'unknown',
-        value: 'mailgun.org'
-      }
+      ...
     ],
     id: '64a5880eere4eg7e1d85bc69',
     is_disabled: false,
-    web_prefix: 'email',
-    web_scheme: 'http'
+    web_prefix: 'test',
+    web_scheme: 'https',
+    use_automatic_sender_security: true
   }
   ```
 
+
+
 - #### destroy
+  The domain must not be disabled or used as an authority for an other domain. Sandbox domain can't be deleted.
+  `mg.domains.destroy(domainAddress)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domains/#tag/Domains/operation/DELETE-v3-domains--name-)
+
+  Example:
+
+  ```JS
+  mg.domains.destroy('foobar.example.com')
+    .then(data => console.log(data)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns message:
+
+  ```JS
+  {
+    message: "Domain will be deleted in the background"
+  }
+  ```
+
+
+- #### 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"
+    }
+  }
+  ```
+
+- #### 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'
+      }
+    }
+    ```
+
+- #### getConnection
+  Returns domain's delivery connection settings.
+
+  `mg.domains.getConnection(domainAddress)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Connection/#tag/Domain-Connection/operation/GET-v3-domains--name--connection)
+
+  Example:
+
+  ```JS
+  mg.domains.getConnection(domainAddress)
+    .then(data => console.log(data)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns:
+
+  ```JS
+  {
+    require_tls: false,
+    skip_verification: false
+  }
+  ```
+
+- #### updateConnection
+  Update a domain's TLS connection settings.
+
+  `mg.domains.updateConnection(domainAddress, data)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Connection/#tag/Domain-Connection/operation/PUT-v3-domains--name--connection)
+
+  Example:
+
+  ```JS
+  mg.domains.updateConnection(domainAddress, {
+    require_tls: true;
+    skip_verification: false;
+  })
+    .then(data => console.log(data)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns:
+
+  ```JS
+  {
+    message: 'Domain connection settings have been updated, may take 10 minutes to fully propagate',
+    require_tls: false,
+    skip_verification: false
+  }
+  ```
+
+- #### updateDKIMAuthority
+  You can delegate the domain authority to an other domain. Domain's authority is set to itself by default.
+
+  `mg.domains.updateDKIMAuthority(domainAddress, data)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Keys/#tag/Domain-Keys/operation/PUT-v3-domains--name--dkim-authority)
+
+  Example:
+
+  ```JS
+  mg.domains.updateDKIMAuthority(domainAddress, {
+    self: true
+  })
+    .then(data => console.log(data)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Data object accepts next properties:
+
+  | Property    | Description                                                                                                                                   |
+  |:--------------|:----------------------------------------------------------------------------------------------------------------------------------------------|
+  | self | Change the DKIM authority for a domain. If set to true, the domain will be the DKIM authority for itself even if the root domain is registered on the same mailgun account If set to false, the domain will have the same DKIM authority as the root domain registered on the same mailgun account |
+
+  Promise returns:
+
+  ```JS
+  {
+  message: 'Domain DKIM authority has been changed',
+  sending_dns_records: [
+    {
+      is_active: true,
+      cached: [],
+      name: 'sending_dns_record_name',
+      record_type: 'TXT',
+      valid: 'unknown',
+      value: 'sending_dns_record_value'
+    },
+    ...
+  ],
+  changed: true
+  }
+  ```
+
+- #### updateDKIMSelector
+  Selector is the unique identifier of your key. It has to be different from other keys selector.
+
+  `mg.domains.updateDKIMSelector(domainAddress, data)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Keys/#tag/Domain-Keys/operation/PUT-v3-domains--name--dkim-selector)
+
+  Example:
+
+  ```JS
+  mg.domains.updateDKIMSelector(domainAddress, {
+    dkimSelector: 'dkimSelector_value'
+  })
+    .then(data => console.log(data)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Data object accepts next properties:
+
+  | Property    | Description                                                                                                                                   |
+  |:--------------|:----------------------------------------------------------------------------------------------------------------------------------------------|
+  | dkimSelector | Selector is the unique identifier of your key. It has to be different from other keys selector. |
+
+  Promise returns:
+
+  ```JS
+  {
+    message: 'DKIM selector changed',
+    status: 200
+  }
+  ```
+
+- #### getIps
+    **Deprecated, and will be removed in the future releases**
+
+    `mg.domains.getIps(domain)`
+
+    Example:
+
+    ```js
+    mg.domains.getIps('foobar.example.com')
+      .then(msg => console.log(msg)) // logs response data
+      .catch(err => console.error(err)); // logs any error
+    ```
+
+    Promise returns:
+
+    ```JS
+    ["192.168.0.1", "192.168.0.2"]
+    ```
+
+- #### assignIp
+   **Deprecated, and will be removed in the future releases**
+  `mg.domains.assignIp(domain, ip)`
+
+  Example:
+
+  ```JS
+  mg.domains.assignIp('foobar.example.com', "192.168.0.3")
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+
+  ```JS
+  {
+    message: 'success',
+    status: 200,
+  }
+  ```
+
+- #### deleteIp
+  **Deprecated, and will be removed in the future releases**
+  `mg.domains.deleteIp(domain, ip)`
+
+  Example:
+
+  ```JS
+  mg.domains.deleteIp('foobar.example.com', "192.168.0.3")
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  ```JS
+  {
+    message: 'success'
+  }
+  ```
+
+### Domain templates
+
+- #### list
+  Returns a list of templates for the domain.
+
+  `mg.domains.domainTemplates.list('domainId', query)` - [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Templates/#tag/Templates/operation/httpapi.(*TemplateAPIControler).GetPage-fm-9)
+
+  Example:
+
+  ```js
+  mg.domains.domainTemplates.list('domainId',{
+    limit: 10
+  })
+    .then(domainTemplates => console.log(domainTemplates)) // logs array of domain templates
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Query data object may have next properties:
+
+  | Property | Description                                           |
+  |:----------|:------------------------------------------------------|
+  | limit     | Maximum number of records to return. (100 by default) |
+  | page      | params from previous response's 'paging' object. Value must be stringified as query params. e.g. '?page=first','?page=next&p=name-of-last-item'|
+
+  Promise returns: object with domain's templates
+  ```JS
+  {
+    items: [
+      {
+        name: 'template_name',
+        description: 'template description ',
+        createdAt: new Date('2021-08-24T22:26:55.000Z'),
+        createdBy: '',
+        id: '48d63154-8c8f-4104-ab14-687d01dbf296'
+      },
+      ...
+    ]
+  }
+  ```
+
+- #### get
+
+  Returns metadata information about the stored template specified in the url. If the active flag is provided, the content of the active version of the template is returned.
+
+  `mg.domains.domainTemplates.get('domainId', 'templateName', query)`  [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Templates/#tag/Templates/operation/httpapi.(*TemplateAPIControler).Get-fm-6)
+
+  Example:
+
+  ```js
+  mg.domains.domainTemplates.get('domainId', 'template_name', {
+     active: 'yes'
+  }).then(data => console.log(data)) // logs template
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Query data object may have next properties:
+
+  | Property | Description                                           |
+  |:----------|:------------------------------------------------------|
+  | active    | If this flag is set to yes the active version of the template is included in the response. |
+
+  Promise returns: object with domain template and active version
+  ```JS
+  {
+    name: 'template_name',
+    description: 'This is the description of the template',
+    createdAt: new Date('2021-08-24T22:26:55.000Z'),
+    createdBy: '',
+    id: '46565d87-68b6-4edb-8b3c-34554af4bb77'
+    version: {
+      tag: 'tag',
+      template: '<html>template content</html>',
+      engine: 'handlebars',
+      mjml: '',
+      createdAt: new Date('2021-08-22T22:26:55.000Z'),
+      comment: 'Version comment',
+      active: true,
+      id: '3efd2b85-0f41-4a1d-9898-05d7e7459c4a',
+      headers: {
+        From: 'from value'
+      }
+    }
+  }
+  ```
+
+- #### create
+  Store a new template, including its name, description and (optionally) the template content.
+  If the template content is provided, a new version is automatically created and becomes the active version.
 
-  `mg.domains.destroy(domainAddress)`
+  `mg.domains.domainTemplates.create(domainId, templateData)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Templates/#tag/Templates/operation/httpapi.(*TemplateAPIControler).Post-fm-4)
 
   Example:
 
-  ```JS
-  mg.domains.destroy('foobar.example.com')
-    .then(msg => console.log(msg)) // logs response data
+  ```js
+  mg.domains.domainTemplates.create('domainId', {
+    name: 'template_name',
+    createdBy: '',
+    tag: 'tag',
+    template: '<html>template content</html>',
+    description: 'template description',
+    comment: 'Version comment',
+    headers: JSON.stringify({
+      From: 'from value'
+    }),
+    engine: 'handlebars'
+  }).then(data => console.log(data)) // logs created template
     .catch(err => console.error(err)); // logs any error
   ```
 
-  Promise returns:
+  Template data object may have next properties:
+
+  | Property | Description                                           |
+  |:----------|:------------------------------------------------------|
+  | name (required)    | Name of the template being stored. Supports utf-8 characters and name will be down cased. |
+  | createdBy    | Optional metadata field api user can indicate who created the template. |
+  | tag    | Initial tag of the created version. If the template parameter is provided and the tag is missing, the default value **initial** is used. |
+  | template    | Content of the template. |
+  | description    | Description of the template being stored |
+  | comment    | Version comment. This is valid only if a new version is being created. (template parameter is provided.) |
+  | headers    | Key Value json dictionary of headers to be stored with the template. Where key is the header name and value is the header value. The header names **From**, **Subject**, and **Reply-To** are the only ones currently supported. These headers will be inserted into the mime at the time we attempt delivery.Headers set at the message level will override headers set on the template. e.g. Setting the From header at the time of sending will override the From header saved on the template. Additionally, headers generated by templates are not reflected on the accepted event as they are not prepended to the message until the message is prepped for delivery. if a From header is not provided either in the message or template, we will default to postmaster@your-sending-domain.tld |
+  | engine    | The template engine to be used when rendering the template. Supported value are handlebars and go (golang template). The default if parameter is not provided is handlebars. |
+
+  Promise returns: created domain template and active version
 
   ```JS
   {
-    message: "Domain has been deleted"
+    name: 'template_name',
+    description: 'template description',
+    createdAt: new Date('2025-01-03T12:33:10.000Z'),
+    createdBy: '',
+    id: '46565d87-68b6-4edb-8b3c-34554af4bb77',
+    version: {
+      tag: 'tag',
+      template: '<html>template content</html>',
+      engine: 'handlebars',
+      mjml: '',
+      createdAt: new Date('2025-01-03T12:33:10.000Z'),
+      comment: 'Version comment',
+      active: true,
+      id: '3efd2b85-0f41-4a1d-9898-05d7e7459c4a',
+      headers: { From: 'from value' }
+    }
   }
   ```
 
-- #### getTracking
+- #### update
+  Update the description of a template.
 
-  `mg.domains.getTracking(domainAddress)`
+  `mg.domains.domainTemplates.update('domainId', 'templateName', data)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Templates/#tag/Templates/operation/httpapi.(*TemplateAPIControler).Put-fm-12)
 
   Example:
 
-  ```JS
-  mg.domains.getTracking('foobar.example.com')
-    .then(msg => console.log(msg)) // logs response data
+  ```js
+  mg.domains.domainTemplates.update('domainId', 'templateName', {
+    description: 'new template description',
+  }).then(data => console.log(data)) // logs data
     .catch(err => console.error(err)); // logs any error
   ```
 
-  Promise returns:
+  Data object may have next properties:
+
+  | Property | Description                                           |
+  |:----------|:------------------------------------------------------|
+  | description    | Update description of the template being updated. |
 
+  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"
-    }
+    status: 200,
+    message: 'template has been updated',
+    templateName: 'template_name'
   }
   ```
 
-- #### updateTracking
-
-  `mg.domains.updateTracking(domain, trackingType, data)`
+- #### destroy
+  Delete the template specified in the url. NOTE: This method deletes all versions of the specified template.
 
-  - Open Tracking Example:
+  `mg.domains.domainTemplates.destroy('domainId', 'templateName')` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Templates/#tag/Templates/operation/httpapi.(*TemplateAPIControler).Delete-fm-13)
 
-    ```js
-    mg.domains.updateTracking('foobar.example.com', 'open', {active: true})
-      .then(msg => console.log(msg)) // logs response data
-      .catch(err => console.error(err)); // logs any error
-    ```
+  Example:
 
-    Open tracking data object properties:
+  ```js
+  mg.domains.domainTemplates.destroy('domainId', 'templateName')
+    .then(data => console.log(data)) // logs data
+    .catch(err => console.error(err)); // logs any error
+  ```
 
-    | Property | Description                                |
-    |:----------|:-------------------------------------------|
-    | active    | Boolean, enables or disables open tracking |
+  Promise returns:
+  ```JS
+  {
+    status: 200,
+    message: 'template has been deleted',
+    templateName: 'template_name'
+  }
+  ```
 
-    Promise returns:
+- #### destroyAll
+  Delete all templates and their versions for the domain.
 
-    ```JS
-    {
-      message: 'Tracking settings have been updated',
-      open: {
-        active: true
-      }
-    }
-    ```
+  `mg.domains.domainTemplates.destroyAll('domainId')` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Templates/#tag/Templates/operation/httpapi.(*TemplateAPIControler).DeleteAll-fm-15)
 
-  - Click Tracking Example:
+  Example:
 
-    ```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
-    ```
+  ```js
+  mg.domains.domainTemplates.destroyAll('domainId')
+    .then(data => console.log(data)) // logs data
+    .catch(err => console.error(err)); // logs any error
+  ```
 
-    Click tracking data object properties:
+  Promise returns:
+  ```JS
+  {
+    status: 200,
+    message: "templates have been deleted"
+  }
+  ```
 
-    | Property | Description                                 |
-    |:----------|:--------------------------------------------|
-    | active    | Boolean, enables or disables click tracking |
+- #### listVersions
+  Returns a paginated list of template versions.
 
-    Promise returns:
+  `mg.domains.domainTemplates.listVersions('domainId', 'template_name', queryData)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Templates/#tag/Templates/operation/httpapi.(*TemplateAPIControler).GetVersionsPage-fm-8)
 
-    ```JS
-    {
-      message: 'Tracking settings have been updated',
-      click: {
-        active: true
-      }
-    }
-    ```
+  Example:
 
-  - Unsubscribe Tracking Example:
+  ```js
+  mg.domains.domainTemplates.listVersions('domainId', 'template_name', {
+    limit: 10,
+  })
+    .then(data => console.log(data)) // logs data
+    .catch(err => console.error(err)); // logs any error
+  ```
 
-    ```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
-    ```
+  Query data object may have next properties:
 
-    Unsubscribe Tracking data object properties:
+  | Property | Description                                           |
+  |:----------|:------------------------------------------------------|
+  | limit     | Maximum number of records to return. (100 by default) |
+  | page      | params from previous response's 'paging' object. Value must be stringified as query params. e.g. '?page=first','?page=next&p=name-of-last-item'|
 
-    | 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
+  {
+    template: {
+      name: 'template_name',
+      description: 'template description',
+      createdAt: new Date('2025-01-03T12:33:10.000Z'),
+      createdBy: '',
+      id: '46565d87-68b6-4edb-8b3c-34554af4bb77',
+      versions: [
+        {
+        tag: 'tag',
+        engine: 'handlebars',
+        mjml: '',
+        createdAt:  new Date('2025-01-03T12:33:10.000Z'),
+        comment: 'Version comment',
+        active: true,
+        id: 'b3f09533-a03f-4e10-9aac-a91115297b6c'
+        }
+       ]
+    }
+  }
+  ```
 
-    Promise returns:
+- #### getVersion
 
-    ```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"
-      }
-    }
-    ```
+  Retrieve the information and content of the specified version of a template.
 
-- #### getIps
-    `mg.domains.getIps(domain)`
+  `mg.domains.domainTemplates.getVersion('domainId', 'template_name', 'tag')` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Templates/#tag/Templates/operation/httpapi.(*TemplateAPIControler).GetVersion-fm-7)
 
-    Example:
+  Example:
 
-    ```js
-    mg.domains.getIps('foobar.example.com')
-      .then(msg => console.log(msg)) // logs response data
-      .catch(err => console.error(err)); // logs any error
-    ```
+  ```js
+  mg.domains.domainTemplates.getVersion('domainId', 'template_name','tag')
+    .then(data => console.log(data)) // logs data
+    .catch(err => console.error(err)); // logs any error
+  ```
 
-    Promise returns:
+  Promise returns:
+  ```JS
+  {
+    template: {
+      name: 'template_name',
+      description: 'template description',
+      createdAt: new Date('2025-01-03T12:33:10.000Z'),
+      createdBy: '',
+      id: '46565d87-68b6-4edb-8b3c-34554af4bb77',
+      versions: [
+        {
+          tag: 'tag',
+          template: '<html>template content</html>',
+          engine: 'handlebars',
+          mjml: '',
+          createdAt: new Date('2025-01-03T12:33:10.000Z'),
+          comment: 'Version comment',
+          active: true,
+          id: 'b3f09533-a03f-4e10-9aac-a91115297b6c',
+          headers: {
+            From: 'from value'
+          }
+        }
+      ]
+    }
+  }
+  ```
 
-    ```JS
-    ["192.168.0.1", "192.168.0.2"]
-    ```
+- #### createVersion
+  Adds a new template version. If the template doesn’t contain any other versions, the first version becomes active. A template can store up to 40 versions.
 
-- #### assignIp
-  `mg.domains.assignIp(domain, ip)`
+  `mg.domains.domainTemplates.createVersion('domainId', 'template_name', versionData)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Templates/#tag/Templates/operation/httpapi.(*TemplateAPIControler).PostVersion-fm-5)
 
   Example:
 
-  ```JS
-  mg.domains.assignIp('foobar.example.com', "192.168.0.3")
-    .then(msg => console.log(msg)) // logs response data
+  ```js
+  mg.domains.domainTemplates.createVersion('domainId', 'template_name',{
+    {
+      template: `<html>template content</html>`,
+      tag: 'v1',
+      engine: 'handlebars',
+      comment: 'comment',
+      active: 'yes',
+      headers: JSON.stringify({
+        From: 'from value'
+      })
+    }
+  })
+    .then(data => console.log(data)) // logs data
     .catch(err => console.error(err)); // logs any error
   ```
 
+  Template version data object may have next properties:
 
+  | Property | Description                                           |
+  |:----------|:------------------------------------------------------|
+  | template    | Content of the template. |
+  | tag    | Initial tag of the created version. If the template parameter is provided and the tag is missing, the default value **initial** is used. |
+  | engine    | The template engine to be used when rendering the template. Supported value are handlebars and go (golang template). The default if parameter is not provided is handlebars. |
+  | comment    | Version comment. This is valid only if a new version is being created. (template parameter is provided.) |
+  | active     | If this flag is set to yes, this version becomes active. |
+  | headers    | Key Value json dictionary of headers to be stored with the template. Where key is the header name and value is the header value. The header names **From**, **Subject**, and **Reply-To** are the only ones currently supported. These headers will be inserted into the mime at the time we attempt delivery.Headers set at the message level will override headers set on the template. e.g. Setting the From header at the time of sending will override the From header saved on the template. Additionally, headers generated by templates are not reflected on the accepted event as they are not prepended to the message until the message is prepped for delivery. if a From header is not provided either in the message or template, we will default to postmaster@your-sending-domain.tld |
+
+  Promise returns:
   ```JS
   {
-    message: 'success',
     status: 200,
+    message: 'new version of the template has been stored',
+    template: l {
+      name: 'template_name',
+      description: 'new template description',
+      createdAt: new Date('2025-01-03T12:33:10.000Z'),
+      createdBy: '',
+      id: '46565d87-68b6-4edb-8b3c-34554af4bb77',
+      version: {
+        tag: 'v1',
+        template: '<html>template content</html>',
+        engine: 'handlebars',
+        mjml: '',
+        createdAt: new Date('2025-01-03T13:41:26.000Z'),
+        comment: 'comment',
+        active: true,
+        id: '3efd2b85-0f41-4a1d-9898-05d7e7459c4a',
+        headers: [Object]
+      }
+    }
   }
   ```
 
-- #### deleteIp
-  `mg.domains.deleteIp(domain, ip)`
+- #### updateVersion
+  Update information or content of the specific template version.
+  Existing fields not included in the request will not be changed
+
+  `mg.domains.domainTemplates.updateVersion('domainId', 'template_name', 'tag' , versionData)` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Templates/#tag/Templates/operation/httpapi.(*TemplateAPIControler).PutVersion-fm-11)
 
   Example:
 
-  ```JS
-  mg.domains.deleteIp('foobar.example.com', "192.168.0.3")
-    .then(msg => console.log(msg)) // logs response data
+  ```js
+  mg.domains.domainTemplates.updateVersion('domainId', 'template_name', 'v1',{
+    {
+      template: `<html>template content</html>`,
+      engine: 'handlebars',
+      comment: 'comment',
+      active: 'yes',
+      headers: JSON.stringify({
+        From: 'from value'
+      })
+    }
+  })
+    .then(data => console.log(data)) // logs data
     .catch(err => console.error(err)); // logs any error
   ```
 
+  Template version data object may have next properties:
+
+  | Property | Description                                           |
+  |:----------|:------------------------------------------------------|
+  | template    | Content of the template. |
+  | engine    | The template engine to be used when rendering the template. Supported value are handlebars and go (golang template). The default if parameter is not provided is handlebars. |
+  | comment    | Version comment. This is valid only if a new version is being created. (template parameter is provided.) |
+  | active     | If this flag is set to yes, this version becomes active. |
+  | headers    | Key Value json dictionary of headers to be stored with the template. Where key is the header name and value is the header value. The header names **From**, **Subject**, and **Reply-To** are the only ones currently supported. These headers will be inserted into the mime at the time we attempt delivery.Headers set at the message level will override headers set on the template. e.g. Setting the From header at the time of sending will override the From header saved on the template. Additionally, headers generated by templates are not reflected on the accepted event as they are not prepended to the message until the message is prepped for delivery. if a From header is not provided either in the message or template, we will default to postmaster@your-sending-domain.tld |
+
+  Promise returns:
   ```JS
   {
-    message: 'success'
+     status: 200,
+     message: 'version has been updated',
+     templateName: 'template_name',
+     templateVersion: {
+      tag: 'v1'
+     }
   }
   ```
 
+- #### destroyVersion
+  Delete a specific template version.
+
+  `mg.domains.domainTemplates.destroyVersion('domainId', 'template_name', 'tag' )` [api docs](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Templates/#tag/Templates/operation/httpapi.(*TemplateAPIControler).DeleteVersion-fm-14)
+
+  Example:
+
+  ```js
+  mg.domains.domainTemplates.destroyVersion('domainId', 'template_name', 'v1')
+    .then(data => console.log(data)) // logs data
+    .catch(err => console.error(err)); // logs any error
+  ```
+  Promise returns:
+    ```JS
+    {
+      status: 200,
+      message: 'version has been deleted',
+      templateName: 'template_name',
+      templateVersion: { tag: 'v1' }
+    }
+    ```
+
 ### Events
 
 - #### get
@@ -1023,7 +1701,7 @@ The following service methods are available to instantiated clients. The example
   ```
 
 ### Stats
-  - Stats Options
+- #### Stats Options
 
     | Parameter  | Description                                                                                                                |
     |:-----------|:---------------------------------------------------------------------------------------------------------------------------|
@@ -1110,6 +1788,145 @@ The following service methods are available to instantiated clients. The example
   }
   ```
 
+
+  ```
+
+### Metrics
+  Mailgun collects many different events and generates event metrics which are available in your Control Panel. This data is also available via our analytics metrics [API endpoint](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Metrics/#tag/Metrics).
+
+- #### getAccount
+  Gets filtered metrics for an account
+
+  `mg.metrics.getAccount(MetricsQuery);`
+
+  Example:
+  ```JS
+    mg.metrics.getAccount({
+      start: '2024-12-16T10:47:51.661Z',
+      end: '2024-12-23T10:47:51.661Z',
+      resolution: 'hour',
+      metrics: ['opened_count'],
+      filter: {
+        AND: [{
+          attribute: 'domain',
+          comparator: 'contains',
+          values: [{
+            value: 'mailgun'
+          }]
+        }]
+      },
+      include_subaccounts: true,
+      include_aggregates: true
+    })
+    .then(data => console.log(data)) // logs response data
+    .catch(err => console.error(err)); //logs any error
+  ```
+  *getAccount* method accepts data object with next properties:
+  | Property    | Type |Description                                                                                                                                   |
+  |:--------------|:-----|:-----------------------------------------------------------------------------------------------------------------------------------|
+  | start      | String that contains date in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14 or JS Date object | A start date (default: 7 days before current time)|
+  | end        | String that contains date in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14 or JS Date object | An end date (default: current time)|
+  | resolution | String | A resolution in the format of 'day' 'hour' 'month'. Default is day.|
+  | duration   | String | A duration in the format of '1d' '2h' '2m'. If duration is provided then it is calculated from the end date and overwrites the start date.|
+  | dimensions | Array of strings | Attributes of the metric data such as 'subaccount'.|
+  | metrics    | Array of strings | Name of the metrics to receive the stats for such as 'processed_count'.|
+  | filter    | object | Filters to apply to the query. The 'AND' property is required and should contains array of filters objects. See this [document](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Metrics/#tag/Metrics/operation/api.(*MetricsAPI).PostMetricQuery-fm-3!path=filter&t=request) for an object shape. |
+  | include_subaccounts | Boolean | Include stats from all subaccounts. |
+  | include_aggregates  | Boolean | Include top-level aggregate metrics.|
+
+  Promise returns: MetricsResult
+
+  ```JS
+  {
+    start: new Date('2024-12-16T01:00:00.000Z'),
+    end: new Date('2024-12-23T00:00:00.000Z'),
+    resolution: 'hour',
+    dimensions: [ 'time' ],
+    pagination: { sort: '', skip: 0, limit: 1500, total: 1 },
+    items: [
+      {
+        dimensions: [{
+          {
+            dimension: 'time',
+            value: 'Sat, 21 Dec 2024 17:00:00 +0000',
+            display_value: 'Sat, 21 Dec 2024 17:00:00 +0000'
+          }
+        }],
+        metrics: { opened_count: 1 }
+      },
+      ...
+    ],
+    aggregates: { metrics: { opened_count: 1 } },
+    status: 200
+  }
+  ```
+
+- #### getAccountUsage
+  Gets filtered **usage metrics** for an account
+  `mg.metrics.getAccountUsage(MetricsQuery);`
+
+  Example:
+  ```JS
+    mg.metrics.getAccountUsage({
+      start: '2024-12-16T10:47:51.661Z',
+      end: '2024-12-23T10:47:51.661Z',
+      resolution: 'hour',
+      metrics: ['opened_count'],
+      filter: {
+        AND: [{
+          attribute: 'domain',
+          comparator: 'contains',
+          values: [{
+            value: 'mailgun'
+          }]
+        }]
+      },
+      include_subaccounts: true,
+      include_aggregates: true
+    })
+    .then(data => console.log(data)) // logs response data
+    .catch(err => console.error(err)); //logs any error
+  ```
+  *getAccountUsage* method accepts data object with next properties:
+  | Property    | Type |Description                                                                                                                                   |
+  |:--------------|:-----|:-----------------------------------------------------------------------------------------------------------------------------------|
+  | start      | String that contains date in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14 or JS Date object | A start date (default: 7 days before current time)|
+  | end        | String that contains date in RFC 2822 format: https://datatracker.ietf.org/doc/html/rfc2822.html#page-14 or JS Date object | An end date (default: current time)|
+  | resolution | String | A resolution in the format of 'day' 'hour' 'month'. Default is day.|
+  | duration   | String | A duration in the format of '1d' '2h' '2m'. If duration is provided then it is calculated from the end date and overwrites the start date.|
+  | dimensions | Array of strings | Attributes of the metric data such as 'subaccount'.|
+  | metrics    | Array of strings | Name of the metrics to receive the stats for such as 'processed_count'.|
+  | filter    | object | Filters to apply to the query. The 'AND' property is required and should contains array of filters objects. See this [document](https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Metrics/#tag/Metrics/operation/api.(*MetricsAPI).PostMetricQuery-fm-3!path=filter&t=request) for an object shape. |
+  | include_subaccounts | Boolean | Include stats from all subaccounts. |
+  | include_aggregates  | Boolean | Include top-level aggregate metrics.|
+
+  Promise returns: MetricsResult
+
+  ```JS
+  {
+    start: new Date('2024-12-16T01:00:00.000Z'),
+    end: new Date('2024-12-23T00:00:00.000Z'),
+    resolution: 'hour',
+    dimensions: [ 'time' ],
+    pagination: { sort: '', skip: 0, limit: 1500, total: 1 },
+    items: [
+      {
+        dimensions: [{
+          {
+            dimension: 'time',
+            value: 'Sat, 21 Dec 2024 17:00:00 +0000',
+            display_value: 'Sat, 21 Dec 2024 17:00:00 +0000'
+          }
+        }],
+        metrics: { opened_count: 1 }
+      },
+      ...
+    ],
+    aggregates: { metrics: { opened_count: 1 } },
+    status: 200
+  }
+  ```
+
 ### Suppressions
 
 - #### list
@@ -3165,7 +3982,6 @@ A client to manage members within a specific mailing list.
       results: 'link to result page',
     }
   }
-  ```
 
 ## Navigation thru lists
   Most of the methods that return items in a list support pagination.