Testing some Mailgun awesomness!
" }) .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` - MIME Example: ```js mg.messages.create('sandbox-123.mailgun.org', { from: "Excited User
Set the length of your domain’s generated DKIM key
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`
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. [Spam Filter](https://documentation.mailgun.com/en/latest/user_manual.html#um-spam-filter)
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: 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 [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domains/put-v4-domains--name--verify) `mg.domains.verify(domainAddress)` 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: [], 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. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domains/put-v4-domains--name-) `mg.domains.update(domain, options)` Example: ```js mg.domains.update('foobar.example.com',{ mailfrom_host: 'mailfrom_host_value', message_ttl: 20, smtp_password: 'smtp_password_value' spam_action: 'tag', use_automatic_sender_security: true web_scheme: 'http', web_prefix: 'web_prefix_value' wildcard: 'true', }) .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); // logs any error ``` Update method accepts data object with next properties: | 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: ```JS { name: 'foobar.example.com', require_tls: false, skip_verification: false, state: 'unverified', wildcard: true, spam_action: 'disabled', created_at: new Date('2025-01-08T12:52:29.000Z'), smtp_password: undefined, smtp_login: 'postmaster@foobar.example.com', type: 'custom', receiving_dns_records: [ { is_active: true, cached: [], priority: '10', record_type: 'MX', valid: 'unknown', value: 'receiving_dns_record_value' }, ... ], sending_dns_records: [ { is_active: true, cached: [], name: 'foobar.example.com', record_type: 'TXT', valid: 'unknown', value: 'sending_dns_record_value' }, ... ], id: '64a5880eere4eg7e1d85bc69', is_disabled: false, 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. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domains/delete-v3-domains--name-) `mg.domains.destroy(domainAddress)` 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 `domains.getTracking` method is deprecated, and will be removed. Please use `domains.domainTracking.getTracking` instead. - #### updateTracking `domains.updateTracking` method is deprecated, and will be removed. Please use `domains.domainTracking.updateTracking` instead. - #### getConnection ***Deprecated, and will be removed in the future releases*** Returns domain's delivery connection settings. [API Reference](https://mailgun-docs.redoc.ly/docs/mailgun/api-reference/domain/operation/httpapi.(*T).GetDomainConnection-fm-14-0/) `mg.domains.getConnection(domainAddress)` 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 ***Deprecated, and will be removed in the future releases*** Update a domain's TLS connection settings. [API Reference](https://mailgun-docs.redoc.ly/docs/mailgun/api-reference/domain/operation/httpapi.(*T).UpdateDomainConnection-fm-15-0/) `mg.domains.updateConnection(domainAddress, data)` 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 `domains.updateDKIMAuthority` method is deprecated, and will be removed. Please use `domains.domainKeys.updateDKIMAuthority` [instead](#updatedkimauthority-1). - #### updateDKIMSelector `domains.updateDKIMSelector` method is deprecated, and will be removed. Please use `domains.domainKeys.updateDKIMSelector` [instead](#updatedkimselector-1). - #### 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. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/templates/get-v3--domain-name--templates) `mg.domains.domainTemplates.list('domainId', query)` 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. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/templates/get-v3--domain-name--templates--template-name-) `mg.domains.domainTemplates.get('domainId', 'templateName', query)` 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: 'template content', 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. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/templates/post-v3--domain-name--templates) `mg.domains.domainTemplates.create(domainId, templateData)` Example: ```js mg.domains.domainTemplates.create('domainId', { name: 'template_name', createdBy: '', tag: 'tag', template: 'template content', 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 ``` 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 { 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: 'template content', 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' } } } ``` - #### update Update the description of a template. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/templates/put-v3--domain-name--templates--template-name-) `mg.domains.domainTemplates.update('domainId', 'templateName', data)` Example: ```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 ``` Data object may have next properties: | Property | Description | |:----------|:------------------------------------------------------| | description | Update description of the template being updated. | Promise returns: ```JS { status: 200, message: 'template has been updated', templateName: 'template_name' } ``` - #### destroy Delete the template specified in the url. NOTE: This method deletes all versions of the specified template. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/templates/delete-v3--domain-name--templates--template-name-) `mg.domains.domainTemplates.destroy('domainId', 'templateName')` Example: ```js mg.domains.domainTemplates.destroy('domainId', 'templateName') .then(data => console.log(data)) // logs data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { status: 200, message: 'template has been deleted', templateName: 'template_name' } ``` - #### destroyAll Delete all templates and their versions for the domain. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/templates/delete-v3--domain-name--templates) `mg.domains.domainTemplates.destroyAll('domainId')` Example: ```js mg.domains.domainTemplates.destroyAll('domainId') .then(data => console.log(data)) // logs data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { status: 200, message: "templates have been deleted" } ``` - #### listVersions Returns a paginated list of template versions. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/templates/get-v3--domain-name--templates--template-name--versions) `mg.domains.domainTemplates.listVersions('domainId', 'template_name', queryData)` 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 ``` 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: ```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' } ] } } ``` - #### getVersion Retrieve the information and content of the specified version of a template. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/templates/get-v3--domain-name--templates--template-name--versions--version-name-) `mg.domains.domainTemplates.getVersion('domainId', 'template_name', 'tag')` Example: ```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: ```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: 'template content', 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' } } ] } } ``` - #### 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. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/templates/post-v3--domain-name--templates--template-name--versions) `mg.domains.domainTemplates.createVersion('domainId', 'template_name', versionData)` Example: ```js mg.domains.domainTemplates.createVersion('domainId', 'template_name',{ { template: `template content`, 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 { 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: 'template content', engine: 'handlebars', mjml: '', createdAt: new Date('2025-01-03T13:41:26.000Z'), comment: 'comment', active: true, id: '3efd2b85-0f41-4a1d-9898-05d7e7459c4a', headers: [Object] } } } ``` - #### updateVersion Update information or content of the specific template version. Existing fields not included in the request will not be changed [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/templates/put-v3--domain-name--templates--template-name--versions--version-name-) `mg.domains.domainTemplates.updateVersion('domainId', 'template_name', 'tag' , versionData)` Example: ```js mg.domains.domainTemplates.updateVersion('domainId', 'template_name', 'v1',{ { template: `template content`, 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 { status: 200, message: 'version has been updated', templateName: 'template_name', templateVersion: { tag: 'v1' } } ``` - #### destroyVersion Delete a specific template version. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/templates/delete-v3--domain-name--templates--template-name--versions--version-name-) `mg.domains.domainTemplates.destroyVersion(domainId, templateName, tag)` 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' } } ``` ### 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. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-tracking/get-v3-domains--name--tracking) `mg.domains.domainTracking.getTracking(domainAddress)` 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
\n\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 Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-tracking/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 Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-tracking/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 Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-tracking/put-v3-domains--name--tracking-unsubscribe) ```js mg.domains.domainTracking.updateTracking('foobar.example.com', 'unsubscribe', { active: true, html_footer: "\n
\n\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
\n\n', text_footer: '\n\nTo unsubscribe click: <%unsubscribe_url%>\n\n' } } ``` - #### get Get x509 TLS certificate and status [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-tracking/get-v2-x509--domain--status) `mg.domains.domainTracking.get(domainAddress)` 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. Domain address must be formatted as `webPrefix.domainName` from domains settings [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-tracking/post-v2-x509--domain-) `mg.domains.domainTracking.generate(domainAddress)` Example: ```JS mg.domains.domainTracking.generate('email.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. Domain address must be formatted as `webPrefix.domainName` from domains settings [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-tracking/put-v2-x509--domain-) `mg.domains.domainTracking.regenerate(domainAddress)` Example: ```JS mg.domains.domainTracking.regenerate('email.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, } ``` ### Domain Keys - #### list List all domain keys for your domain, including active/inactive and valid/invalid ones. `mg.domains.domainKeys.list(domainAddress, data)` [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-keys/get-v4-domains--authority-name--keys) Example: ```JS mg.domains.domainKeys.list(domainAddress) .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { items: [ { signing_domain: 'authority.domain.tld', selector: 's1', dns_record: { is_active: true, cached: [], name: 's1._domainkey.authority.domain.tld', record_type: 'TXT', valid: 'unknown', value: 'expected dns value' } }, ], status: 200 } ``` - #### listAll List domain keys, and optionally filter by signing domain or selector. The page & limit data is only required when paging through the data. `mg.domains.domainKeys.listAll(filterData)` [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-keys/get-v1-dkim-keys) Example: ```JS mg.domains.domainKeys.listAll( { signingDomain: 'authority.domain.tld', // optional selector: 's1', // optional } ) .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { items: [ { signing_domain: 'authority.domain.tld', selector: 's1', dns_record: { is_active: true, cached: [], name: 's1._domainkey.authority.domain.tld', record_type: 'TXT', valid: 'unknown', value: 'expected dns value' } }, ], status: 200 } ``` - #### create Create a domain key. *Note that once private keys are created or imported they are never exported. Alternatively, you can import an existing PEM file containing a RSA private key in PKCS #1, ASn.1 DER format. Note, the pem can be passed as a file attachment or as a form-string parameter.* `mg.domains.domainKeys.create(newKeyData)` [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-keys/post-v1-dkim-keys) Example: ```JS mg.domains.domainKeys.create( { signingDomain: 'authority.domain.tld', selector: 's1', bits: '2048' // optional } ) .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { signing_domain: 'authority.domain.tld', selector: 's1', dns_record: { is_active: true, cached: [], name: 's1._domainkey.authority.domain.tld', record_type: 'TXT', valid: 'unknown', value: 'expected dns value' }, status: 200 } ``` - #### activate Activate a key to be used to DKIM sign emails with. *Note: dns records must be valid for a domain key to be activated* `mg.domains.domainKeys.activate(domainAddress, selector)` [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-keys/put-v4-domains--authority-name--keys--selector--activate) Example: ```JS mg.domains.domainKeys.activate('authority.domain.tld', 's1') .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { message: 'domain key activated', authority: 'authority.domain.tld', selector: 's1', active: true, status: 200, } ``` - #### deactivate Deactivating for a specified authority and/or selector means a key won't be used for signing email anymore, even if they are valid. `mg.domains.domainKeys.deactivate(domainAddress, selector)` [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-keys/put-v4-domains--authority-name--keys--selector--deactivate) Example: ```JS mg.domains.domainKeys.deactivate('authority.domain.tld', 's1') .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { message: 'domain key deactivated', authority: 'authority.domain.tld', selector: 's1', active: true, status: 200, } ``` - #### destroy Delete a key. **Domain keys are not recoverable after deletion so use with care** `mg.domains.domainKeys.destroy(domainAddress, selector)` [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-keys/delete-v1-dkim-keys) Example: ```JS mg.domains.domainKeys.destroy('authority.domain.tld', 's1') .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { message: 'success' } ``` - #### updateDKIMAuthority You can delegate the domain authority to an other domain. Domain's authority is set to itself by default. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-keys/put-v3-domains--name--dkim-authority) `mg.domains.domainKeys.updateDKIMAuthority(domainAddress, data)` Example: ```JS mg.domains.domainKeys.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. [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/domain-keys/put-v3-domains--name--dkim-selector) `mg.domains.domainKeys.updateDKIMSelector(domainAddress, data)` Example: ```JS mg.domains.domainKeys.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 } ``` ### Events - #### get ***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) `mg.events.get(domain, data)` Example: ```js mg.events.get('foobar.example.com', { page: 'mypageid', event: 'opened' }).then(data => console.log(data.items)) // logs array of event objects .catch(err => console.error(err)); // logs any error ``` Options: | Parameter | Description | |:----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | page | Fetches the specified page of log records, assuming that the URL was returned by the previous request | | begin | The beginning of the search time range. It can be specified as a string (see Date Format) or linux epoch seconds. Refer to Time Range for details. | | end | The end of the search time range. It can be specified as a string (see Date Format) or linux epoch seconds. Refer to Time Range for details. | | ascending | Defines the direction of the search time range if the range end time is not specified. Can be either yes or no. Refer to Time Range for details. | | limit | Number of entries to return. (300 max) | | **field** | **field** is the name of the *[Filter Field](https://mailgun-docs.redoc.ly/docs/mailgun/user-manual/events/#filter-field)*. The value of the parameter should be a valid Filter Expression. Several field filters can be specified in one request. If the same field is mentioned, more then once, then all its filter expressions are combined with AND operator. | - #### Example with Date and *Filter field* ```js const date = new Date(2023, 7, 2, 0, 0, 0, 0); // Wed Aug 02 2023 00:00:00 GMT+0300 const events = await mg.events.get('foobar.example.com', { begin: date.toUTCString(), // 'Tue, 01 Aug 2023 21:00:00 GMT' ascending: 'yes', limit: 5, event: 'delivered' }); ``` Promise returns: items (array of event objects), pages (paging keys grouped by id) ```JS { items: [{ type: 'accepted', summary: 'got it', content: { more: 'data' }, timestamp: Wed Nov 19 2014 10:32:57 GMT-0800 (PST) }, }], pages: { first: { id: 'first', number: 'W3siYSI6IGZhbHNlLC', url: 'apiurl' }, last: { id: 'last', number: 'W3siYSI6IGZhbHNlLC', url: 'apiurl' }, next: { id: 'next', number: W3siYSI6IGZhbHNlLC'', url: 'apiurl' }, previous: { id: 'previous', number: 'W3siYSI6IGZhbHNlLC', url: 'apiurl' } } } ``` ### 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*** [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/stats) - #### Stats Options | Parameter | Description | |:-----------|:---------------------------------------------------------------------------------------------------------------------------| | event | The type of the event. For a complete list of all events written to the log see the `Event Types` table below. (Required) | | start | The starting time. Should be in :rfc:`2822#page-14` or unix epoch format. Default: 7 days from the current time. | | end | The ending date. Should be in :rfc:`2822#page-14` or unix epoch format. Default: current time. | | resolution | Can be either ``hour``, ``day`` or ``month``. Default: ``day`` | | duration | Period of time with resolution encoded. If provided, overwrites the start date. See list below. | Duration is a string that represents a period of time with some resolution. It has a format `[0-9]+[m,d,h]` where - `h` - an hour - `d` - a day - `m` - a month Examples: - `24h` - a period of 24 hours (a day) with hourly resolution - `1d` - a period of 1 day with daily resolution - `2m` - a period of 2 months with monthly resolution Event Types | Event Type | Description | |:-------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | accepted | Mailgun accepted the request to send/forward the email and the message has been placed in queue. | | delivered | Mailgun sent the email and it was accepted by the recipient email server. | | failed | Mailgun could not deliver the email to the recipient email server. | | opened | The email recipient opened the email and enabled image viewing. Open tracking must be enabled in the Mailgun control panel, and the CNAME record must be pointing to mailgun.org. | | clicked | The email recipient clicked on a link in the email. Click tracking must be enabled in the Mailgun control panel, and the CNAME record must be pointing to mailgun.org. | | unsubscribed | The email recipient clicked on the unsubscribe link. Unsubscribe tracking must be enabled in the Mailgun control panel. | | complained | The email recipient clicked on the spam complaint button within their email client. Feedback loops enable the notification to be received by Mailgun. | | stored | Mailgun has stored an incoming message - #### getDomain [API Reference](https://mailgun-docs.redoc.ly/docs/mailgun/api-reference/openapi-final/tag/Stats/#tag/Stats/operation/GET-v3--domain--stats-total) `mg.stats.getDomain(domain, query)` Example: ```js mg.stats.getDomain('foobar.example.com', {event: ['delivered', 'accepted', 'failed', 'complained']}) .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { start: Sun Mar 15 2015 17:00:00 GMT-0700 (PDT), end: Sun Mar 22 2015 17:00:00 GMT-0700 (PDT), resolution: 'day', stats: [{ time: Sun Mar 15 2015 17:00:00 GMT-0700 (PDT), delivered: { smtp: 2, http: 1, total: 3 } }] } ``` - #### getAccount [API Reference](https://mailgun-docs.redoc.ly/docs/mailgun/api-reference/openapi-final/tag/Stats/#tag/Stats/operation/GET-v3-stats-total) `mg.stats.getDomain(domain, query)` Example: ```js mg.stats.getDomain('foobar.example.com', {event: ['delivered', 'accepted', 'failed', 'complained']}) .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { start: Sun Mar 15 2015 17:00:00 GMT-0700 (PDT), end: Sun Mar 22 2015 17:00:00 GMT-0700 (PDT), resolution: 'day', stats: [{ time: Sun Mar 15 2015 17:00:00 GMT-0700 (PDT), delivered: { smtp: 2, http: 1, total: 3 } }] } ``` ``` ### 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 Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/metrics). - #### getAccount Gets filtered metrics for an account [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/metrics/post-v1-analytics-metrics) `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/send/mailgun/metrics/post-v1-analytics-metrics#metrics/post-v1-analytics-metrics/t=request&path=filter) 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 [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/metrics/post-v1-analytics-usage-metrics) `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/send/mailgun/metrics/post-v1-analytics-metrics#metrics/post-v1-analytics-metrics/t=request&path=filter) 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 `mg.suppressions.list(domain, suppressionType, query?)` - #### Bounces Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/bounces/get-v3--domainid--bounces) ```js mg.suppressions.list('foobar.example.com', 'bounces') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` - #### Unsubscribes Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/unsubscribe/get-v3--domainid--unsubscribes) ```js mg.suppressions.list('foobar.example.com', 'unsubscribes') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` - #### Complaints Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/complaints/get-v3--domainid--complaints) ```js mg.suppressions.list('foobar.example.com', 'complaints') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { items: [ { type: "bounces", address: "unknown@unknown.com", code: 550, error: "No such mailbox", created_at: Fri Oct 21 2011 04:02:55 GMT-0700 (PDT) }], pages: { first: { id: "first", page: "", address: "", url: "apiurl" }, last: { id: "last", page: "", address: "", url: "apiurl" }, next: { id: "next", page: "", address: "", url: "apiurl" }, previous: { id: "prev", page: "", address: "", url: "apiurl" } } } ``` - #### get `mg.suppressions.get(domain, suppressionType, address)` - #### Bounces Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/bounces/get-v3--domainid--bounces--address-) ```js mg.suppressions.get('foobar.example.com', 'bounces', 'address@example.com') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` - #### Unsubscribes Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/unsubscribe/get-v3--domainid--unsubscribes--address-) ```js mg.suppressions.get('foobar.example.com', 'unsubscribes', 'address@example.com') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` - #### Complaints Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/complaints/get-v3--domainid--complaints--address-) ```js mg.suppressions.get('foobar.example.com', 'complaints', 'address@example.com') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Response example: ```JS { type: "bounces", address: "address?@unknown.com", tags: [ "*" ], created_at: Fri Oct 21 2011 05:02:55 GMT-0700 (PDT) } ``` - #### create `mg.suppressions.create(domain, suppressionType, data || data[])` - #### Bounces Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/bounces/post-v3--domainid--bounces) ```JS mg.suppressions.create('foobar.example.com', 'bounces', [{address: 'bob@example.com'}]) .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Bounces Options: Contains an array with the following object properties | Parameter | Description | |:-----------|:--------------------------------------------------------------------------------| | address | Valid email address | | code | Error code (optional, default: 550) | | error | Error description (optional, default: empty string) | | created_at | Timestamp of a bounce event in RFC2822 format (optional, default: current time) | Promise returns: ```js { message: "1 address has been added to the bounces table" } ``` - #### Unsubscribes Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/unsubscribe/post-v3--domainid--unsubscribes) ```js mg.suppressions.create('foobar.example.com', 'unsubscribes', {address: 'bob@example.com'}) .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Unsubscribes Options: Contains an array with the following object properties | Parameter | Description | |:-----------|:-----------------------------------------------------------------------------------------------------------------| | address | Valid email address | | tag | Tag to unsubscribe from, use * to unsubscribe an address from all domain’s correspondence (optional, default: *) | | tags | Array with tags to unsubscribe from | | created_at | Timestamp of a bounce event in RFC2822 format (optional, default: current time) | Promise returns: ```JS { message: "1 address has been added to the unsubscribes table" } ``` - #### Unsubscribe from one tag ```js mg.suppressions.create('foobar.example.com', 'unsubscribes', {address: 'bob@example.com', tag: 'your_tag_to_unsubscribe']}) .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { message: "1 address has been added to the unsubscribes table" } ``` - #### Unsubscribe from particular tags ```js mg.suppressions.create('foobar.example.com', 'unsubscribes', [{address: 'bob@example.com', tags: ['your_tag_to_unsubscribe', 'another_tag_to_unsubscribe']}]) .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { message: "1 address has been added to the unsubscribes table" } ``` - #### Complaints Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/complaints/post-v3--domainid--complaints) ```JS mg.suppressions.create('foobar.example.com', 'complaints', [{address: 'bob@example.com'}]) .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Complaints Options: Contains an array with the following object properties | Parameter | Description | |:-----------|:-----------------------------------------------------------------------------------------------------------------| | address | Valid email address | | created_at | Timestamp of a bounce event in RFC2822 format (optional, default: current time) | Promise returns: ```JS { message: "1 address has been added to the complaints table" } ``` - #### upload `mg.suppressions.upload(domain, suppressionType, file)` - #### Bounces file upload example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/bounces/post-v3--domainid--bounces-import) ```JS const fsPromises = require('fs').promises; const path = require('path'); const filepath = path.resolve(__dirname, '../bounces-list.csv'); (async () =>{ try { const file = { filename: 'bounces-list.csv', data: await fsPromises.readFile(filepath) } const result = mg.suppressions.upload('foobar.example.com', 'bounces', file) console.log(result); } catch (error) { console.error(error); } })() ``` Example of `bounces-list.csv` file structure : ```CSV address, code, error, created_at bob@example.com,error code,error description,"Tue, 20 Jan 2026 14:00:00 +0000" anotherBob@example.com,,, ``` Promise returns: ```JS { message: "file uploaded successfully for processing. standby..." } ``` - #### Unsubscribes file upload example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/unsubscribe/post-v3--domainid--unsubscribes-import) ```JS const fsPromises = require('fs').promises; const path = require('path'); const filepath = path.resolve(__dirname, '../unsubscribes-list.csv'); (async () =>{ try { const file = { filename: 'unsubscribes-list.csv', data: await fsPromises.readFile(filepath) } const result = mg.suppressions.upload('foobar.example.com', 'unsubscribes', file) console.log(result); } catch (error) { console.error(error); } })() ``` Example of `unsubscribes-list.csv` file structure : ```CSV address, tags, created_at bob@example.com,tag to unsubscribe from,"Tue, 20 Jan 2026 14:00:00 +0000" anotherBob@example.com,, ``` Promise returns: ```JS { message: "file uploaded successfully for processing. standby..." } - #### Complaints file upload example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/complaints/post-v3--domainid--complaints-import) ```JS const fsPromises = require('fs').promises; const path = require('path'); const filepath = path.resolve(__dirname, '../complaints-list.csv'); (async () =>{ try { const file = { filename: 'complaints-list.csv', data: await fsPromises.readFile(filepath) } const result = mg.suppressions.upload('foobar.example.com', 'complaints', file) console.log(result); } catch (error) { console.error(error); } })() ``` Example of `complaints-list.csv` file structure : ```CSV address, created_at bob@example.com,"Tue, 20 Jan 2026 14:00:00 +0000" anotherBob@example.com,, ``` Promise returns: ```JS { message: "file uploaded successfully for processing. standby..." } - #### WhiteLists file upload example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/allowlist) ```JS const fsPromises = require('fs').promises; const path = require('path'); const filepath = path.resolve(__dirname, '../whitelists-list.csv'); (async () =>{ try { const file = { filename: 'whitelists-list.csv', data: await fsPromises.readFile(filepath) } const result = mg.suppressions.upload('foobar.example.com', 'whitelists', file) console.log(result); } catch (error) { console.error(error); } })() ``` Example of `whitelists-list.csv` file structure : ```CSV address, created_at bob@example.com,"Tue, 20 Jan 2026 14:00:00 +0000" anotherBob@example.com,, ``` Promise returns: ```JS { message: "file uploaded successfully for processing. standby..." } - #### destroy `mg.suppressions.destroy(domain, suppressionType, address)` - #### Bounces Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/bounces/delete-v3--domainid--bounces--address-) ```JS mg.suppressions.destroy('foobar.example.com', 'bounces', 'bob@example.com') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { message: "Bounced address has been removed", value: "", address: "bob@example.com", status: 200 } ``` - #### Unsubscribes Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/unsubscribe/delete-v3--domainid--unsubscribes--address-) ```js mg.suppressions.destroy('foobar.example.com', 'unsubscribes', 'bob@example.com') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { message: 'Unsubscribe event has been removed', value: '', address: 'bob@example.com', status: 200 } ``` - #### Complaints Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/complaints/delete-v3--domainid--complaints--address-) ```js mg.suppressions.destroy('foobar.example.com', 'complaints', 'bob@example.com') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS message: 'Spam complaint has been removed', value: '', address: 'bob@example.com', status: 200 ``` - #### destroyAll `mg.suppressions.destroyAll(domain, suppressionType)` - #### Bounces Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/bounces/delete-v3--domainid--bounces) ```js mg.suppressions.destroyAll('foobar.example.com', 'bounces') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { message: 'Bounced addresses for this domain have been removed', status: 200 } ``` - #### Unsubscribes Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/unsubscribe/delete-v3--domainid--unsubscribes) ```js mg.suppressions.destroyAll('foobar.example.com', 'unsubscribes') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { message: 'Unsubscribe addresses for this domain have been removed', status: 200 } ``` - #### Complaints Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/complaints/delete-v3--domainid--complaints) ```js mg.suppressions.destroyAll('foobar.example.com', 'complaints') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { message: 'Complaint addresses for this domain have been removed', status: 200 } ``` - #### Whitelists Example: [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/allowlist/delete-v3--domainid--whitelists) ```js mg.suppressions.destroyAll('foobar.example.com', 'whitelists') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { message: 'Allowlist addresses/domains for this domain have been removed', status: 200 } ``` ### Webhooks - #### list [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/mailgun/webhooks/get-v3-domains--domain--webhooks) `mg.webhooks.list(domain, query)` Example: ```js mg.webhooks.list('foobar.example.com') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { open: { 'url': 'http://requestb.in' }, click: { 'url': 'http://requestb.in' }, bounce: { 'url': 'http://requestb.in' }, deliver: { 'url': 'http://requestb.in' }, drop: { 'url': 'http://requestb.in' }, spam: { 'url': 'http://requestb.in' }, unsubscribe: { 'url': 'http://requestb.in' }, click: { 'url': 'http://requestb.in' }, open: { 'url': 'http://requestb.in' }, } ``` - #### get [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/mailgun/webhooks/get-v3-domains--domain-name--webhooks--webhook-name-) `mg.webhooks.get(domain, id)` Example: ```js mg.webhooks.get('foobar.example.com', 'open') // bounce, deliver, drop, spam, unsubscribe, click, open .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { 'open': { 'url': 'http://requestb.in', 'urls': ['trackclick.com'] } } ``` - #### create [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/mailgun/webhooks/post-v3-domains--domain--webhooks) `mg.webhooks.create(domain, id, data, test)` Example: ```js mg.webhooks.create('foobar.example.com', 'open', 'http://requestb.in') // bounce, deliver, drop, spam, unsubscribe, click, open .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { 'open': { 'url': 'http://requestb.in', 'urls': ['http://requestb.in'] } } ``` Test Webhook Example: ```JS mg.webhooks.get('foobar.example.com', 'open', 'http://requestb.in', true) // bounce, deliver, drop, spam, unsubscribe, click, open .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { 'code': '500', 'message': 'Hi!' } ``` - #### update [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/mailgun/webhooks/put-v3-domains--domain-name--webhooks--webhook-name-) `mg.webhooks.update(domain, id, url, test)` Example: ```js mg.webhooks.update('foobar.example.com', 'open', 'http://requestb.in') // bounce, deliver, drop, spam, unsubscribe, click, open .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { 'open': { 'url': 'http://requestb.in', 'urls': ['http://requestb.in'] } } ``` ```js mg.webhooks.update('foobar.example.com', 'open', ['http://requestb.in', 'http://requestb1.in' ]) // bounce, deliver, drop, spam, unsubscribe, click, open .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { 'open': { 'url': 'http://requestb.in', 'urls': ['http://requestb.in', 'http://requestb1.in'] } } ``` - #### destroy [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/mailgun/webhooks/delete-v3-domains--domain-name--webhooks--webhook-name-) `mg.webhooks.destroy(domain, id)` Example: ```JS mg.webhooks.update('foobar.example.com', 'open') // bounce, deliver, drop, spam, unsubscribe, click, open .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { 'open': { 'url': 'http://requestb.in', 'urls': ['http://requestb.in']} } ``` ### Routes - #### list [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/routes/get-v3-routes) `mg.routes.list(query)` Example: ```JS mg.routes.list() .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS [ { actions: [ 'forward("http://myhost.com/messages/")', 'stop()' ], created_at: 'Mon, 26 Oct 2015 03:56:51 GMT', description: 'sample', expression: 'match_recipient(".*@example.com")', id: '562da483125730608a7d1719', priority: 0 } ] ``` - #### get [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/routes/get-v3-routes-id) `mg.routes.get(id)` Example: ```js mg.routes.get('562da483125730608a7d1719') .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: response body ```JS { actions: [ 'forward("http://myhost.com/messages/")', 'stop()' ], created_at: 'Mon, 26 Oct 2015 03:56:51 GMT', description: 'sample', expression: 'match_recipient(".*@example.com")', id: '562da483125730608a7d1719', priority: 0 } ``` - #### create [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/routes/post-v3-routes) `mg.routes.create(options)` Example: ```JS mg.routes.create({ priority: 0, description: 'sample', expression: 'match_recipient(".*@example.org")', action: ['forward("http://myhost.com/messages/")', 'stop()'] }) .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: response body ```js { actions: [ 'forward("http://myhost.com/messages/")', 'stop()' ], created_at: 'Mon, 26 Oct 2015 03:56:51 GMT', description: 'sample', expression: 'match_recipient(".*@example.com")', id: '562da483125730608a7d1719', priority: 0 } ``` - #### update [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/routes/put-v3-routes-id) `mg.routes.update(id, options)` Example: ```JS mg.routes.update('562da483125730608a7d1719', { priority: 0, description: 'sample', expression: 'match_recipient(".*@example.org")', action: ['forward("http://myhost.com/messages/")', 'stop()'] }) .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: response body ```JS { actions: [ 'forward("http://myhost.com/messages/")', 'stop()' ], created_at: 'Mon, 26 Oct 2015 03:56:51 GMT', description: 'sample', expression: 'match_recipient(".*@example.com")', id: '562da483125730608a7d1719', message: 'Route has been updated', priority: 0 } ``` - #### destroy [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/routes/delete-v3-routes-id) `mg.routes.destroy(id)` Example: ```js mg.routes.destroy('562da483125730608a7d1719') .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: response body ```JS { id: '562da483125730608a7d1719', message: 'Route has been deleted' } ``` - #### matchAddress [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/routes/get-v3-routes-match) `mg.routes.matchAddress(address)` Example: ```js mg.routes.matchAddress('test@example.com') .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: response body ```JS { actions: [ 'forward("http://myhost.com/messages/")', 'stop()' ], created_at: 'Mon, 26 Oct 2015 03:56:51 GMT', description: 'sample', expression: 'match_recipient(".*@example.com")', id: '562da483125730608a7d1719', priority: 0 } ``` ### Validation - #### get [API Reference](https://documentation.mailgun.com/docs/validate/single-valid-ir) `mg.validate.get(address)` Example: ```JS mg.validate.get('foo@mailgun.net') .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: response body ```JS { address: 'alice@example.com', did_you_mean: null, is_valid: false, parts: { display_name: null, domain: null, local_part: null } } ``` ### Multiple validation [API Reference](https://documentation.mailgun.com/docs/validate/bulk-valid-ir) - #### create `mg.validate.multipleValidation.create('name_of_the_list', { file })` ```js const fsPromises = require('fs').promises; const filepath = path.resolve(__dirname, '../path_to_your_file_with_emails_list.csv'); ... (async () => { try { const file = { filename: 'test.csv', data: await fsPromises.readFile(filepath) }; const validateBulkResult = await mg.validate.multipleValidation.create('name_of_the_list', { file }); console.log('validateBulkResult', validateBulkResult); } catch (error) { console.error(error); } })(); ``` Response shape: ```JSON { "id": "name_of_the_list", "message": "The validation job was submitted." } ``` - #### list `mg.validate.multipleValidation.list()` ```js mg.validate.multipleValidation.list() .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Response shape: ```JSON { "jobs": [ { "created_at": 1643965937, "download_url": { "csv": "csv-url", "json": "json-url" }, "id": "name_of_the_list", "quantity": 40, "records_processed": 40, "status": "uploaded", "summary": { "result": { "catch_all": 0, "deliverable": 0, "do_not_send": 0, "undeliverable": 0, "unknown": 40 }, "risk": { "high": 0, "low": 0, "medium": 0, "unknown": 40 } } } ], "paging": { "first": "https://api.mailgun.net/v4/address/validate/bulk?limit=100&page=first&pivot=", "last": "https://api.mailgun.net/v4/address/validate/bulk?limit=100&page=last&pivot=", "next": "https://api.mailgun.net/v4/address/validate/bulk?limit=100&page=next&pivot=b4808b5b-1111-2222-3333-6cd0b63f41ea", "prev": "https://api.mailgun.net/v4/address/validate/bulk?limit=100&page=prev&pivot=" }, "total": 1 } ``` - #### get `mg.validate.multipleValidation.get('name_of_the_list')` ```js mg.validate.multipleValidation.get('name_of_the_list') .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Response shape: ```JSON { "created_at": 1643965937, "download_url": { "csv": "csv-url", "json": "json-url" }, "id": "name_of_the_list", "quantity": 40, "records_processed": 40, "responseStatusCode": 200, "status": "uploaded", "summary": { "result": { "catch_all": 0, "deliverable": 0, "do_not_send": 0, "undeliverable": 0, "unknown": 40 }, "risk": { "high": 0, "low": 0, "medium": 0, "unknown": 40 } } } ``` - #### destroy `mg.validate.multipleValidation.destroy('name_of_the_list');` cancels bulk validation job ```JS mg.validate.multipleValidation.destroy('name_of_the_list'); .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Response shape: ```JS { body: "Validation job canceled.", status: 200 } ``` ### Mailing lists A client to manage mailing lists. - #### list [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/get-v3-lists) `mg.lists.list(query?)` Example: ```js mg.lists.list() .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Example with query: ```js mg.lists.list({ page: '?page=first', limit: 10 }) .then(data => console.log(data)) .catch(err => console.error(err)); ``` Allowed query properties: - `limit` - `page` Promise returns: response body ```JS [ { access_level: 'readonly', address: 'noreply@sample.com', created_at: 'Wed, 27 Oct 2021 21:59:21 -0000', description: '', members_count: 0, name: '', reply_preference: 'list' } ] ``` - #### listByAddress [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/get-v3-lists) `mg.lists.listByAddress(query)` Example: ```js mg.lists.listByAddress({ address: 'test@example.com', skip: 2, limit: 10 }) .then(data => console.log(data)) .catch(err => console.error(err)); ``` Allowed query properties: - `address` - `skip` - `limit` Promise returns: response body ```JS { items: [ { access_level: 'readonly', address: 'noreply@sample.com', created_at: 'Wed, 27 Oct 2021 21:59:21 -0000', description: '', members_count: 0, name: '', reply_preference: 'list' } ], status: 200 } ``` - #### get [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/get-v3-lists-address) `mg.lists.get(mailListAddress)` Example: ```JS mg.lists.get('noreply@sample.com') .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { access_level: 'readonly', address: 'noreply@sample.com', created_at: 'Thu, 28 Oct 2021 00:16:56 -0000', description: '', members_count: 0, name: '', reply_preference: 'list' } ``` - #### create [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/post-v3-lists) `mg.lists.create(data)` Example: ```js mg.lists.create({ address: 'reply@sample.com', name: 'Reply Address', // optional, modifiable on website description: 'Mailing lists for repliable address', // optional, modifiable on website access_level: 'readonly', // optional, modifiable on website reply_preference: 'list', // optional, modifiable on website }) .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { access_level: 'readonly', address: 'reply@sample.com', created_at: 'Thu, 28 Oct 2021 03:12:17 -0000', description: 'Mailing lists for repliable address', members_count: 0, name: 'Reply Address', reply_preference: 'list' } ``` - #### update [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/put-v3-lists-address) `mg.lists.update(mailListAddress)` Example: ```js mg.lists.update('reply@sample.com', { address: 'foo@sample.com', name: 'Foo', // optional, modifiable on website description: 'Foo bar bat', // optional, modifiable on website access_level: 'members', // optional, modifiable on website reply_preference: 'sender', // optional, modifiable on website }) .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { access_level: 'members', address: 'foo@sample.com', created_at: 'Thu, 28 Oct 2021 03:21:15 -0000', description: 'Foo bar bat', members_count: 0, name: 'Foo', reply_preference: 'sender' } ``` - #### destroy [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/delete-v3-lists-address) `mg.lists.destroy(mailListAddress)` Example: ```js mg.lists.destroy('foo@sample.com') .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: response body ```JS { address: 'foo@sample.com', message: 'Mailing list has been removed' } ``` ### Mailing list members A client to manage members within a specific mailing list. - #### listMembers [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/get-lists-string:list_address-members) `mg.lists.members.listMembers(mailListAddress)` Example: ```js mg.lists.members.listMembers('reply@sample.com') .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS [ { address: 'foo@bar.com', name: 'Jane Doe', subscribed: true, vars: { age: 50 } } ] ``` - #### listMembersByAddress [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/get-v3-lists) `mg.lists.members.listMembersByAddress(mailListAddress, query)` Example: ```js mg.lists.members.listMembersByAddress('reply@sample.com', { address: 'foo@bar.com', skip: 0, limit: 10 }) .then(data => console.log(data)) .catch(err => console.error(err)); ``` Promise returns: ```JS { items: [ { address: 'foo@bar.com', name: 'Jane Doe', subscribed: true, vars: { age: 50 } } ], total_count: 1, status: 200 } ``` - #### getMember [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/get-lists-list_address-members-member_address) `mg.lists.members.getMember(mailListAddress, mailListMemberAddress)` Example: ```JS mg.lists.members.getMember('reply@sample.com', 'foo@bar.com') .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { address: 'foo@bar.com', name: 'Jane Doe', subscribed: true, vars: { age: 50 } } ``` - #### createMember [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/post-lists-string:list_address-members) `mg.lists.members.createMember(mailListAddress, data)` Example: ```JS mg.lists.members.createMember('reply@sample.com', { address: 'bat@bar.com', name: 'John Smith', // optional, modifiable on website vars: {hobby: "chess"}, // optional, modifiable on website subscribed: 'no', // optional, modifiable on website upsert: 'yes', // optional, choose yes to insert if not exist, or update it exist }) .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: response body ```JS { address: 'bat@bar.com', name: 'John Smith', subscribed: false, vars: { hobby: 'chess' } } ``` - #### createMembers [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/post-lists-list_address-members.json) `mg.lists.members.createMembers(mailListAddress, data)` Example: ```JS mg.lists.members.createMembers('reply@sample.com', { members: [ { address: "bot1@foobar.com", name: "Bot1 Superbot", vars: {location: "loc1"}, subscribed: true, }, { address: "bot2@foobar.com", name: "Bot2 Superbot", vars: {location: "loc2"}, subscribed: false, }, ], upsert: "yes", }) .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: ```JS { list: { access_level: 'readonly', address: 'reply@sample.com', created_at: 'Thu, 28 Oct 2021 03:21:15 -0000', description: 'For reply purpose', members_count: 2, name: 'Reply', reply_preference: 'list' }, message: 'Mailing list has been updated', 'task-id': '575b943c37a211ec8a520242ac11000a' } ``` - #### updateMember [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/put-lists-list_address-members-member_address) `mg.lists.members.updateMember(mailListAddress, mailListMemberAddress, data)` Example: ```JS mg.lists.members.updateMember('reply@sample.com', 'bot1@foobar.com', { address: 'bot0@barfoo.com', name: 'Bot0 Normalbot', // optional, modifiable on website vars: {location: "space"}, subscribed: false, }) .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: response body ```JS { address: 'bot0@barfoo.com', name: 'Bot0 Normalbot', subscribed: false, vars: { location: 'space' } } ``` - #### destroyMember [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/mailing-lists/delete-lists-list_address-members-member_address) `mg.lists.members.destroyMember(mailListAddress, mailListMemberAddress)` Example: ```JS mg.lists.members.destroyMember('reply@sample.com', 'bot2@foobar.com') .then(data => console.log(data)) // logs response body .catch(err => console.error(err)); // logs any error ``` Promise returns: response body ```JS { member: { address: 'bot2@foobar.com' }, message: 'Mailing list member has been deleted' } ``` ### Subaccounts A client to manage subaccounts. - #### list [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/subaccounts/get-v5-accounts-subaccounts) `mg.subaccounts.list(query)` Example: ```js mg.subaccounts.list() .then(subaccounts => console.log(subaccounts)) // logs array of subaccounts .catch(err => console.error(err)); // logs any error ``` Promise returns: array of Subaccounts instances ```JS [ { id: "XYZ", name: "test.subaccount1", status: "open" }, { id: "YYY", name: "test.subaccount2", status: "open" } ] ``` Query data may have next properties: | Property | Description | |:---------|:-----------------------------------------------------------------------| | limit | Maximum number of records to return. (10 by default) | | skip | Number of records to skip. (0 by default) | | sort | "asc" or "desc". | | enabled | Returns all enabled/disabled subaccounts. (Defaults to all if omitted) | - #### get [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/subaccounts/get-v5-accounts-subaccounts-subaccount_id) `mg.subaccounts.get(subaccount_id)` Example: ```JS mg.subaccounts.get('123') .then(subaccount => console.log(subaccount)) // logs subaccount object .catch(err => console.error(err)); // logs any error ``` Promise returns: Subaccount instance ```JS { id: "123", name: "test.subaccount1", status: "open" } ``` - #### create [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/subaccounts/post-v5-accounts-subaccounts) `mg.subaccounts.create(name)` Example: ```js mg.subaccounts.create('foobar') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: Subaccount instance ```JS { id: "123", name: "foobar", status: "open" } ``` Create method accepts data object with next properties: | Parameter | Description | |-------------|-----------------------------------------------------------| | name | Name of the subaccount being created (ex. 'mysubaccount') | - #### enable [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/subaccounts/post-v5-accounts-subaccounts-subaccount_id-enable) `mg.subaccounts.enable(subaccount_id)` Example: ```js mg.subaccounts.enable('123') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: Subaccount instance ```JS { id: "123", name: "foobar", status: "open" } ``` - #### disable [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/subaccounts/post-v5-accounts-subaccounts-subaccount_id-disable) `mg.subaccounts.disable(subaccount_id)` Example: ```js mg.subaccounts.disable('123') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: Subaccount instance ```JS { id: "123", name: "foobar", status: "disabled" } ``` - #### destroy [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/subaccounts/delete-v5-accounts-subaccounts-subaccount_id) `mg.subaccounts.destroy(subaccount_id)` Example: ```js mg.subaccounts.destroy('123') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: Result message ```JS { message: 'Subaccount successfully deleted' } ``` - #### setMonthlySendingLimit [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/subaccounts/put-v5-accounts-subaccounts-subaccount_id-limit-custom-monthly) `mg.subaccounts.setMonthlySendingLimit(subaccount_id, limit)` Example: ```js mg.subaccounts.setMonthlySendingLimit('123', 5000) .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: Status message ```JS { success: true } ``` - #### getMonthlySendingLimit [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/subaccounts/get-v5-accounts-subaccounts-subaccount_id-limit-custom-monthly) `mg.subaccounts.getMonthlySendingLimit(subaccount_id)` Example: ```js mg.subaccounts.getMonthlySendingLimit('123') .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: Details of custom sending limit on the account ```JS { current: 0, limit: 5000, period: '1m' } ``` - #### updateSubaccountFeature [API Reference](https://documentation.mailgun.com/docs/mailgun/api-reference/send/mailgun/subaccounts/put-v5-accounts-subaccounts-subaccount_id-features) `mg.subaccounts.updateSubaccountFeature(subaccount_id, featuresValues)` Example: ```js mg.subaccounts.updateSubaccountFeature('123', { email_preview: false, inbox_placement: false, sending: false, validations: false, validations_bulk: false }) .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error ``` Promise returns: Successfully updated subaccount features ```JS { features: { email_preview: { enabled: false }, inbox_placement: { enabled: false }, sending: { enabled: true }, validations: { enabled: false }, validations_bulk: { enabled: false } } } ``` ### Inbox Placements A client to allows you to see the likely deliverability of your email campaigns. - #### SeedsLists - #### list [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-seedlists) `mg.inboxPlacements.seedsLists.list()` Example: ```JS mg.inboxPlacements.seedsLists.list() .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: available SeedsLists ```JS { status: 200, items: [ { kid: 'kid', ID: 'ID', AccountID: 'AccountID', created_at: new Date('2024-08-09T14:32:57.183Z'), updated_at: new Date('2024-08-09T14:33:57.183Z'), last_result_at: new Date('2024-08-09T14:32:57.183Z'), Seeds: [ { AccountID: 'acount id', id: 'seed id', token: 'token', email: 'email', provider: 'provider', sync_state: 'sync_state', local_state: 'local_state', created_at: new Date('2024-08-09T14:32:57.183Z'), updated_at: new Date('2024-08-09T14:32:57.183Z'), message_count: 0, max_email_count_hit_at: new Date('2024-08-09T14:32:57.183Z'), total_msgs: 0, matched_msgs: 0, spam_message: 0, expected_msgs: 0, last_sent_to_at: new Date('2024-08-09T14:32:57.183Z'), last_delivered_at: new Date('2024-08-09T14:32:57.183Z'), account_quality: 0, quality_label: 'quality_label', password: 'password', phone_number: 'phone_number', attributes: {}, totp: { secret: 'secret', } }, ... ], target_email: 'test_email@test.com', sending_domains: ['test_domain.com'], has_results: true, name: 'test name', seed_filter: 'test filter', mailing_list: 'test mailing_list', CreatedTS: 1723214101728, tags: { sfmc_remote_id: 'test sfmc_remote_id', }, delivery_stats: { all: { delivered: 0, missing: 0, pending: 0, spam: 0, inbox: 0, total: 0, provider: 'test provider', categories: { primary: 0, promotions: 0, updates: 0, } } }, SeedQuality: 1, is_auto_generated: true, }, ... ], paging: { first: 'first_page_link', last: 'last_page_link', next: 'next_page_link', previous: 'previous_page_link', } } ``` - #### get [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-seedlists--address-) `mg.inboxPlacements.seedsLists.get(seedsListId)` Example: ```JS mg.inboxPlacements.seedsLists.get(seedsListId); .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: SeedsLists item by id ```JS { status: 200, kid: 'kid', ID: 'ID', AccountID: 'AccountID', created_at: new Date('2024-08-09T14:32:57.183Z'), updated_at: new Date('2024-08-09T14:33:57.183Z'), last_result_at: new Date('2024-08-09T14:32:57.183Z'), Seeds: [ { AccountID: 'acount id', id: 'seed id', token: 'token', email: 'email', provider: 'provider', sync_state: 'sync_state', local_state: 'local_state', created_at: new Date('2024-08-09T14:32:57.183Z'), updated_at: new Date('2024-08-09T14:32:57.183Z'), message_count: 0, max_email_count_hit_at: new Date('2024-08-09T14:32:57.183Z'), total_msgs: 0, matched_msgs: 0, spam_message: 0, expected_msgs: 0, last_sent_to_at: new Date('2024-08-09T14:32:57.183Z'), last_delivered_at: new Date('2024-08-09T14:32:57.183Z'), account_quality: 0, quality_label: 'quality_label', password: 'password', phone_number: 'phone_number', attributes: {}, totp: { secret: 'secret', } }, ... ], target_email: 'test_email@test.com', sending_domains: ['test_domain.com'], has_results: true, name: 'test name', seed_filter: 'test filter', mailing_list: 'test mailing_list', CreatedTS: 1723214101728, tags: { sfmc_remote_id: 'test sfmc_remote_id', }, delivery_stats: { all: { delivered: 0, missing: 0, pending: 0, spam: 0, inbox: 0, total: 0, provider: 'test provider', categories: { primary: 0, promotions: 0, updates: 0, } } }, SeedQuality: 1, is_auto_generated: true, } ``` - #### create [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/post-v4-inbox-seedlists) ```js mg.inboxPlacements.seedsLists.create({ name: 'seedLists name', sending_domains: 'your_sending_domain', seed_filter: 'seed filter', remote_id: 'remote_id' }) ``` Example: ```JS mg.inboxPlacements.seedsLists.create({ sending_domains: 'your_sending_domain', name: 'seedLists name'; seed_filter: 'seed filter'; remote_id: 'remote_id'; }); .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: created SeedsLists item ```JS { kid: 'kid', created_at: new Date('2024-08-09T14:32:57.183Z'), updated_at: new Date('2024-08-09T14:32:57.183Z'), last_result_at: new Date('2024-08-09T14:32:57.183Z'), target_email: 'test_email@test.com', sending_domains: [ 'your_sending_domain' ], has_results: false, name: 'seedLists name', seed_filter: 'seed filter', provider_filter: [], mailing_list: 'test_email@test.com', previous_mailing_list: '', tags: { sfmc_remote_id: 'remote_id' }, delivery_stats: { all: { delivered: 0, missing: 0, pending: 0, spam: 0, inbox: 0, total: 0, provider: 'all', categories: {} } }, is_auto_generated: false, version: 2, Seeds: null, status: 200 } ``` - #### update [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/put-v4-inbox-seedlists--address-) ```JS mg.inboxPlacements.seedsLists.update(seedsListId,{ name: 'new seedLists name', // optional provider_filter: 'provider_filter', // optional shuffle: true, // optional sending_domains: 'your_sending_domain' // optional }) ``` Example: ```JS mg.inboxPlacements.seedsLists.update(seedsListId,{ name: 'new seedLists name', provider_filter: 'gmail.com', sending_domains: 'your_sending_domain' }) .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: updated SeedsLists item ```JS { kid: '674dcab31169b0619005a9f8', created_at: new Date('2024-08-09T14:32:57.183Z'), updated_at: 2024-12-02T14:59:42.231Z, last_result_at: new Date('2024-08-09T14:32:57.183Z'), target_email: 'test_email@test.com', sending_domains: [ 'your_sending_domain' ], has_results: false, name: 'seedLists name', seed_filter: '.*', provider_filter: ['gmail.com'], mailing_list: 'test_email@test.com', previous_mailing_list: '', tags: { sfmc_remote_id: 'remote_id' }, delivery_stats: { all: { delivered: 0, missing: 0, pending: 0, spam: 0, inbox: 0, total: 0, provider: 'all', categories: {} } }, is_auto_generated: false, version: 2, Seeds: null, status: 200 } ``` - #### destroy [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/delete-v4-inbox-seedlists--address-) ```js mg.inboxPlacements.seedsLists.destroy(seedsListId) ``` Example: ```JS mg.inboxPlacements.seedsLists.destroy(seedsListId) .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: status object ```JS { status: 200, body: null } ``` - #### Attributes - #### list [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-seedlists-a) `mg.inboxPlacements.seedsLists.attributes.list()` Example: ```JS mg.inboxPlacements.seedsLists.attributes.list() .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: SeedsLists attributes ```JS { status: 200, items:[{ attribute: 'available attribute', values: ['attribute_value', ...] }, ...] } ``` - #### get [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-seedlists-a--attribute-) `mg.inboxPlacements.seedsLists.attributes.get('attribute_name');` Example: ```JS mg.inboxPlacements.seedsLists.attributes.get('attribute_name') .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: SeedsLists attribute ```JS { status: 200, items: { attribute: 'attribute_name', values: ['attribute_value', ...] } } ``` - #### Filters - #### list [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-seedlists--filters) `mg.inboxPlacements.seedsLists.filters.list()` Example: ```JS mg.inboxPlacements.seedsLists.filters.list() .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: SeedsLists filters ```JS { status: 200, supported_filters:{ filters: [ { parameter: 'parameter_name', description: 'parameter_description' }, .... ] } } ``` - #### Providers - #### list [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-providers) List all available email providers. `mg.inboxPlacements.providers.list()` Example: ```JS mg.inboxPlacements.providers.list() .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: providers list ```JS { items: [ { domain: 'something.com', region: 'provider region', display_name: 'provider name', created_at: new Date('2024-08-09T14:32:57.183Z'), updated_at: new Date('2024-08-09T14:32:59.183Z') }, ... ] } ``` - #### Results - #### list [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-results) Get the details for all placement test results. ```js mg.inboxPlacements.results.list({ 'sender': 'sender value', // optional 'subject': 'subject value', // optional 'provider': 'provider value', // optional 'target_email': 'target_email value', // optional 'time_after': new Date('2024-08-09T14:32:57.183Z'), // optional 'time_before': new Date('2024-08-11T14:32:57.183Z'), // optional 'cursor': '', // optional 'sort': '', // optional 'offset': 1, // optional 'ascending': true, // optional 'limit': 5, // optional }) ``` Example: ```JS mg.inboxPlacements.results.list({ 'sender': 'sender value', // optional 'subject': 'subject value', // optional }) .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: results list ```JS { status: 200, items: [ { rid: 'rid_value', result_id: 'result_id_value', AccountID: 'AccountID_value', KeyBoxID: 'KeyBoxID_value', keybox_email: 'keybox_email_value', subject: 'subject_value', sender: 'sender_value', seedlist_name: 'seedlist_name_value', created_at: new Date('2024-08-09T14:32:57.183Z'), updated_at: new Date('2024-08-11T14:32:57.183Z'), status: 'status_value', CreatedTS: 1723214101728, attributes: { attribute_value: 'attribute_value_value' }, campaign_id: 'campaign_id_value', sharing_enabled: true, sharing_id: 'sharing_id_value', sharing_expires_at: new Date('2024-08-14T14:32:57.183Z'), Box: { Id: 'box_Id_value', kid: 'box_kid_value', AccountID: 'box_AccountID_value', created_at: new Date('2024-08-11T14:32:57.183Z'), updated_at: new Date('2024-08-12T14:32:57.183Z'), last_result_at: new Date('2024-08-13T14:32:57.183Z'), Seeds: null, target_email: 'box_target_email_value', sending_domains: null, has_results: true, name: 'box_name_value', seed_filter: 'box_seed_filter_value', mailing_list: 'box_mailing_list_value', CreatedTS: 1723214101728, tags: ['tag_value'], SeedQuality: 100, is_auto_generated: true, }, seed_results: [{ email: 'seed_result_email_value', provider: 'seed_result_provider_value', destination: 'seed_result_destination_value', state: 'seed_result_state_value', originating_ip: 'seed_result_originating_ip_value', tags: ['seed_result_tag_value'], dkim: 'seed_result_dkim_value', spf: 'seed_result_spf_value', dmarc: 'seed_result_dmarc_value', headers: [{ key: 'seed_result_header_key_value', value: 'seed_result_header_value_value', }], extensions: { category: 'seed_result_extensions_category_value', } }], spamassassin: { is_spam: false, score: 1, required: 1, rules: [{ name: 'rule_name_value', points: 100, short_description: 'short_description_value', long_description: 'long_description_value', }], }, delivery_stats: { test_delivery_stat: { delivered: 1, missing: 0, pending: 0, spam: 0, inbox: 0, total: 1, provider: 'provider_value', categories: { primary: 1, updates: 0, } } } } ], pages: { first: '?page=first', last: '?page=last', next: '?page=next', previous: '?page=previous', }, } ``` - #### get Get the details for a single result. [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-results--result-) `mg.inboxPlacements.results.get(IBPResultId)` Example: ```JS mg.inboxPlacements.results.get(IBPResultId); .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: Inbox Placement result item ```JS { status: 200, inboxPlacementResult: { rid: 'rid_value', result_id: 'result_id_value', AccountID: 'AccountID_value', KeyBoxID: 'KeyBoxID_value', keybox_email: 'keybox_email_value', subject: 'subject_value', sender: 'sender_value', seedlist_name: 'seedlist_name_value', created_at: new Date('2024-08-09T14:32:57.183Z'), updated_at: new Date('2024-08-11T14:32:57.183Z'), status: 'status_value', CreatedTS: 1723214101728, attributes: { attribute_value: 'attribute_value_value' }, campaign_id: 'campaign_id_value', sharing_enabled: true, sharing_id: 'sharing_id_value', sharing_expires_at: new Date('2024-08-14T14:32:57.183Z'), Box: { Id: 'box_Id_value', kid: 'box_kid_value', AccountID: 'box_AccountID_value', created_at: new Date('2024-08-11T14:32:57.183Z'), updated_at: new Date('2024-08-12T14:32:57.183Z'), last_result_at: new Date('2024-08-13T14:32:57.183Z'), Seeds: null, target_email: 'box_target_email_value', sending_domains: null, has_results: true, name: 'box_name_value', seed_filter: 'box_seed_filter_value', mailing_list: 'box_mailing_list_value', CreatedTS: 1723214101728, tags: ['tag_value'], SeedQuality: 100, is_auto_generated: true, }, seed_results: [{ email: 'seed_result_email_value', provider: 'seed_result_provider_value', destination: 'seed_result_destination_value', state: 'seed_result_state_value', originating_ip: 'seed_result_originating_ip_value', tags: ['seed_result_tag_value'], dkim: 'seed_result_dkim_value', spf: 'seed_result_spf_value', dmarc: 'seed_result_dmarc_value', headers: [{ key: 'seed_result_header_key_value', value: 'seed_result_header_value_value', }], extensions: { category: 'seed_result_extensions_category_value', } }], spamassassin: { is_spam: false, score: 1, required: 1, rules: [{ name: 'rule_name_value', points: 100, short_description: 'short_description_value', long_description: 'long_description_value', }], }, delivery_stats: { test_delivery_stat: { delivered: 1, missing: 0, pending: 0, spam: 0, inbox: 0, total: 1, provider: 'provider_value', categories: { primary: 1, updates: 0, } } } } } ``` - #### destroy [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/delete-v4-inbox-results--result-) Delete the result and all associated information. `mg.inboxPlacements.results.destroy(IBPResultId)` Example: ```JS mg.inboxPlacements.results.destroy(IBPResultId) .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: status object ```JS { status: 200, message: 'deleted' } ``` - #### getResultByShareId Get a result by the share ID. [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-sharing-public--shareid-) ```js mg.inboxPlacements.results.getResultByShareId('result_sharing_id') ``` Example: ```JS mg.inboxPlacements.results.getResultByShareId('result_sharing_id') .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: Inbox Placement result item ```JS { status: 200, inboxPlacementResult: { rid: 'rid_value', result_id: 'result_id_value', AccountID: 'AccountID_value', KeyBoxID: 'KeyBoxID_value', keybox_email: 'keybox_email_value', subject: 'subject_value', sender: 'sender_value', seedlist_name: 'seedlist_name_value', created_at: new Date('2024-08-09T14:32:57.183Z'), updated_at: new Date('2024-08-11T14:32:57.183Z'), status: 'status_value', CreatedTS: 1723214101728, attributes: { attribute_value: 'attribute_value_value' }, campaign_id: 'campaign_id_value', sharing_enabled: true, sharing_id: 'sharing_id_value', sharing_expires_at: new Date('2024-08-14T14:32:57.183Z'), Box: { Id: 'box_Id_value', kid: 'box_kid_value', AccountID: 'box_AccountID_value', created_at: new Date('2024-08-11T14:32:57.183Z'), updated_at: new Date('2024-08-12T14:32:57.183Z'), last_result_at: new Date('2024-08-13T14:32:57.183Z'), Seeds: null, target_email: 'box_target_email_value', sending_domains: null, has_results: true, name: 'box_name_value', seed_filter: 'box_seed_filter_value', mailing_list: 'box_mailing_list_value', CreatedTS: 1723214101728, tags: ['tag_value'], SeedQuality: 100, is_auto_generated: true, }, seed_results: [{ email: 'seed_result_email_value', provider: 'seed_result_provider_value', destination: 'seed_result_destination_value', state: 'seed_result_state_value', originating_ip: 'seed_result_originating_ip_value', tags: ['seed_result_tag_value'], dkim: 'seed_result_dkim_value', spf: 'seed_result_spf_value', dmarc: 'seed_result_dmarc_value', headers: [{ key: 'seed_result_header_key_value', value: 'seed_result_header_value_value', }], extensions: { category: 'seed_result_extensions_category_value', } }], spamassassin: { is_spam: false, score: 1, required: 1, rules: [{ name: 'rule_name_value', points: 100, short_description: 'short_description_value', long_description: 'long_description_value', }], }, delivery_stats: { test_delivery_stat: { delivered: 1, missing: 0, pending: 0, spam: 0, inbox: 0, total: 1, provider: 'provider_value', categories: { primary: 1, updates: 0, } } } } } ``` - #### Attributes - #### list [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-results-a) `mg.inboxPlacements.results.attributes.list()` Example: ```JS mg.inboxPlacements.results.attributes.list() .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: results attributes ```JS { status: 200, items:[{ attribute: 'available attribute', values: ['attribute_value', ...] }, ...] } ``` - #### get [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-results-a--attribute-) `mg.inboxPlacements.attributes.get('attribute_name');` Example: ```JS mg.inboxPlacements.results.attributes.get('attribute_name') .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: results attribute ```JS { status: 200, items: { attribute: 'attribute_name', values: ['attribute_value', ...] } } ``` - #### Filters - #### list [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-results--filters) `mg.inboxPlacements.results.filters.list()` Example: ```JS mg.inboxPlacements.results.filters.list() .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: SeedsLists filters ```JS { status: 200, supported_filters:{ filters: [ { parameter: 'parameter_name', description: 'parameter_description' }, .... ] } } ``` - #### Sharing - #### get The sharing status of a result. [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/get-v4-inbox-sharing--result-) `mg.inboxPlacements.results.sharing.get('result_id');` Example: ```JS mg.inboxPlacements.results.sharing.get('result_id'); .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: IPRSharingResult ```JS { status: 200, result_id: 'result_id', expires_at: new Date('2024-08-12T14:32:57.183Z'), enabled: true, url_id: 'result_sharing_id', url: 'url-to-shared-result-page', api_url: 'url-shared-result-page-in-json' } ``` - #### update Change the sharing status of a result or create a new share URL [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/put-v4-inbox-sharing--result-) `mg.inboxPlacements.results.sharing.update('result_id', IPRSharingUpdateData);` Example: ```JS mg.inboxPlacements.results.sharing.update('result_id', { enabled: false }); .then(data => console.log(data)) // logs response data .catch(err => console.error(err)); //logs any error ``` Promise returns: IPRSharingResult ```JS { status: 200, result_id: 'result_id', expires_at: new Date('2024-08-12T14:32:57.183Z'), enabled: false, url_id: 'result_sharing_id', url: '', api_url: '' } ``` - #### Run test Create and run a new inbox placement test. Either 'html' or 'template_name' field should be provided. 'variables' are Template variables, which could be used in html or template. You can use next recipient variables inside Template variables, which will be filled for every seed automatically: %recipient.first_name%, %recipient.last_name%. [API Reference](https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready/inbox-placement/post-v4-inbox-tests) `mg.inboxPlacements.runTest(InboxPlacementsData);` Example: ```JS mg.inboxPlacements.runTest({ from: 'Excited User