mailgun.js 8.2.2 → 9.0.1

package/Interfaces/Domains/DomainTemplates.d.ts

@@ -0,0 +1,23 @@
+import { CreateDomainTemplateVersionResult, DomainTemplateData, DomainTemplatesQuery, DomainTemplateUpdateData, DomainTemplateUpdateVersionData, DomainTemplateVersionData, ListDomainTemplatesResult, ListDomainTemplateVersionsResult, MutateDomainTemplateVersionResult, NotificationResult, ShortTemplateVersion, TemplateQuery, TemplateVersion, UpdateOrDeleteDomainTemplateResult } from '../../Types/Domains';
+export interface IDomainTemplate {
+    name: string;
+    description: string;
+    createdAt: string | Date;
+    createdBy: string;
+    id: string;
+    version?: TemplateVersion;
+    versions?: ShortTemplateVersion[];
+}
+export interface IDomainTemplatesClient {
+    list(domain: string, query?: DomainTemplatesQuery): Promise<ListDomainTemplatesResult>;
+    get(domain: string, templateName: string, query?: TemplateQuery): Promise<IDomainTemplate>;
+    create(domain: string, data: DomainTemplateData): Promise<IDomainTemplate>;
+    update(domain: string, templateName: string, data: DomainTemplateUpdateData): Promise<UpdateOrDeleteDomainTemplateResult>;
+    destroy(domain: string, templateName: string): Promise<UpdateOrDeleteDomainTemplateResult>;
+    destroyAll(domain: string): Promise<NotificationResult>;
+    createVersion(domain: string, templateName: string, data: DomainTemplateVersionData): Promise<CreateDomainTemplateVersionResult>;
+    getVersion(domain: string, templateName: string, tag: string): Promise<IDomainTemplate>;
+    updateVersion(domain: string, templateName: string, tag: string, data: DomainTemplateUpdateVersionData): Promise<MutateDomainTemplateVersionResult>;
+    destroyVersion(domain: string, templateName: string, tag: string): Promise<MutateDomainTemplateVersionResult>;
+    listVersions(domain: string, templateName: string, query?: DomainTemplatesQuery): Promise<ListDomainTemplateVersionsResult>;
+}

package/Interfaces/Domains/DomainsClient.d.ts

@@ -0,0 +1,27 @@
+import { APIResponse } from '../../Types/Common';
+import { ClickTrackingInfo, ConnectionSettings, DKIMAuthorityInfo, DKIMSelectorInfo, DomainInfo, DomainsQuery, DomainTrackingData, MessageResponse, OpenTrackingInfo, ReplacementForPool, TDomain, UnsubscribeTrackingInfo, UpdatedConnectionSettings, UpdatedDKIMAuthority, UpdatedDKIMSelectorResponse, UpdatedOpenTracking, UpdatedWebPrefixResponse, WebPrefixInfo } from '../../Types/Domains';
+import { IDomainCredentials } from './DomainCredentials';
+import { IDomainTagsClient } from './DomainTags';
+import { IDomainTemplatesClient } from './DomainTemplates';
+export interface IDomainsClient {
+    domainCredentials: IDomainCredentials;
+    domainTemplates: IDomainTemplatesClient;
+    domainTags: IDomainTagsClient;
+    list(query?: DomainsQuery): Promise<TDomain[]>;
+    get(domain: string): Promise<TDomain>;
+    create(data: DomainInfo): Promise<TDomain>;
+    verify(domain: string): Promise<TDomain>;
+    destroy(domain: string): Promise<MessageResponse>;
+    getConnection(domain: string): Promise<ConnectionSettings>;
+    updateConnection(domain: string, data: ConnectionSettings): Promise<UpdatedConnectionSettings>;
+    getTracking(domain: string): Promise<DomainTrackingData>;
+    updateTracking(domain: string, type: string, data: OpenTrackingInfo | ClickTrackingInfo | UnsubscribeTrackingInfo): Promise<UpdatedOpenTracking>;
+    getIps(domain: string): Promise<string[]>;
+    assignIp(domain: string, ip: string): Promise<APIResponse>;
+    deleteIp(domain: string, ip: string): Promise<APIResponse>;
+    linkIpPool(domain: string, pool_id: string): Promise<APIResponse>;
+    unlinkIpPoll(domain: string, replacement: ReplacementForPool): Promise<APIResponse>;
+    updateDKIMAuthority(domain: string, data: DKIMAuthorityInfo): Promise<UpdatedDKIMAuthority>;
+    updateDKIMSelector(domain: string, data: DKIMSelectorInfo): Promise<UpdatedDKIMSelectorResponse>;
+    updateWebPrefix(domain: string, data: WebPrefixInfo): Promise<UpdatedWebPrefixResponse>;
+}

package/Interfaces/Domains/index.d.ts

@@ -0,0 +1,4 @@
+export * from './DomainCredentials';
+export * from './DomainTags';
+export * from './DomainTemplates';
+export * from './DomainsClient';

package/Interfaces/EventClient/IEventClient.d.ts

@@ -0,0 +1,4 @@
+import { EventsList, EventsQuery } from '../../Types/Events';
+export interface IEventClient {
+    get(domain: string, query?: EventsQuery): Promise<EventsList>;
+}

package/Interfaces/EventClient/index.d.ts

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

package/Interfaces/IPPools/IIPPoolsClient.d.ts

@@ -0,0 +1,7 @@
+import { IpPoolCreateData, IpPoolCreateResult, IpPoolDeleteData, IpPoolListResult, IpPoolMessageResult, IpPoolUpdateData } from '../../Types/IPPools';
+export interface IIPPoolsClient {
+    list(): Promise<IpPoolListResult>;
+    create(data: IpPoolCreateData): Promise<IpPoolCreateResult>;
+    update(poolId: string, data: IpPoolUpdateData): Promise<IpPoolMessageResult>;
+    delete(poolId: string, data: IpPoolDeleteData): Promise<IpPoolMessageResult>;
+}

package/Interfaces/IPPools/index.d.ts

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

package/Interfaces/IPs/IIPsClient.d.ts

@@ -0,0 +1,5 @@
+import { IpData, IPsListQuery, IpsListResponseBody } from '../../Types/IPs';
+export interface IIPsClient {
+    list(query: IPsListQuery): Promise<IpsListResponseBody>;
+    get(ip: string): Promise<IpData>;
+}

package/Interfaces/IPs/index.d.ts

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

package/Interfaces/MailgunClient/IMailgunClient.d.ts

@@ -0,0 +1,24 @@
+import { IWebHooksClient } from '../Webhooks';
+import { IDomainsClient } from '../Domains';
+import { IEventClient } from '../EventClient';
+import { IStatsClient } from '../Stats';
+import { IMessagesClient } from '../Messages';
+import { ISuppressionClient } from '../Suppressions';
+import { IRoutesClient } from '../Routes';
+import { IValidationClient } from '../Validations';
+import { IIPsClient } from '../IPs';
+import { IIPPoolsClient } from '../IPPools';
+import { IMailingListsClient } from '../MailingLists';
+export interface IMailgunClient {
+    domains: IDomainsClient;
+    webhooks: IWebHooksClient;
+    events: IEventClient;
+    stats: IStatsClient;
+    suppressions: ISuppressionClient;
+    messages: IMessagesClient;
+    routes: IRoutesClient;
+    validate: IValidationClient;
+    ips: IIPsClient;
+    ip_pools: IIPPoolsClient;
+    lists: IMailingListsClient;
+}

package/Interfaces/MailgunClient/index.d.ts

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

package/Interfaces/MailingLists/MailingListMembers.d.ts

@@ -0,0 +1,9 @@
+import { MailListMembersQuery, MailListMembersResult, MailListMember, CreateUpdateMailListMembers, MultipleMembersData, NewMultipleMembersResponse, DeletedMember } from '../../Types/MailingLists';
+export interface IMailListsMembers {
+    listMembers(mailListAddress: string, query?: MailListMembersQuery): Promise<MailListMembersResult>;
+    getMember(address: string, memberAddress: string): Promise<MailListMember>;
+    createMember(mailListAddress: string, data: CreateUpdateMailListMembers): Promise<MailListMember>;
+    createMembers(mailListAddress: string, data: MultipleMembersData): Promise<NewMultipleMembersResponse>;
+    updateMember(address: string, memberAddress: string, data: CreateUpdateMailListMembers): Promise<MailListMember>;
+    destroyMember(address: string, memberAddress: string): Promise<DeletedMember>;
+}

package/Interfaces/MailingLists/MailingListsClient.d.ts

@@ -0,0 +1,13 @@
+import { CreateUpdateList, DestroyedList, ListsQuery, MailingList, MailingListCancelValidationResult, MailingListResult, MailingListValidationResult, StartValidationResult } from '../../Types/MailingLists';
+import { IMailListsMembers } from './MailingListMembers';
+export interface IMailingListsClient {
+    members: IMailListsMembers;
+    list(query?: ListsQuery): Promise<MailingListResult>;
+    get(mailListAddress: string): Promise<MailingList>;
+    create(data: CreateUpdateList): Promise<MailingList>;
+    update(mailListAddress: string, data: CreateUpdateList): Promise<MailingList>;
+    destroy(mailListAddress: string): Promise<DestroyedList>;
+    validate(mailListAddress: string): Promise<StartValidationResult>;
+    validationResult(mailListAddress: string): Promise<MailingListValidationResult>;
+    cancelValidation(mailListAddress: string): Promise<MailingListCancelValidationResult>;
+}

package/Interfaces/MailingLists/index.d.ts

@@ -0,0 +1,2 @@
+export * from './MailingListMembers';
+export * from './MailingListsClient';

package/Interfaces/Messages/IMessagesClient.d.ts

@@ -0,0 +1,4 @@
+import { MailgunMessageData, MessagesSendResult } from '../../Types/Messages';
+export interface IMessagesClient {
+    create(domain: string, data: MailgunMessageData): Promise<MessagesSendResult>;
+}

package/Interfaces/Messages/index.d.ts

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

package/Interfaces/Routes/IRoutesClient.d.ts

@@ -0,0 +1,8 @@
+import { CreateUpdateRouteData, DestroyRouteResponse, Route, RoutesListQuery, UpdateRouteResponse } from '../../Types/Routes';
+export interface IRoutesClient {
+    list(query: RoutesListQuery): Promise<Route[]>;
+    get(id: string): Promise<Route>;
+    create(data: CreateUpdateRouteData): Promise<Route>;
+    update(id: string, data: CreateUpdateRouteData): Promise<UpdateRouteResponse>;
+    destroy(id: string): Promise<DestroyRouteResponse>;
+}

package/Interfaces/Routes/index.d.ts

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

package/Interfaces/Stats/StatsClient.d.ts

@@ -0,0 +1,6 @@
+import { StatsQuery } from '../../Types/Stats';
+import { IStatsContainer } from './StatsContainer';
+export interface IStatsClient {
+    getDomain(domain: string, query?: StatsQuery): Promise<IStatsContainer>;
+    getAccount(query?: StatsQuery): Promise<IStatsContainer>;
+}

package/Interfaces/Stats/StatsContainer.d.ts

@@ -0,0 +1,7 @@
+import { Stat } from '../../Types/Stats';
+export interface IStatsContainer {
+    start: Date;
+    end: Date;
+    resolution: string;
+    stats: Stat[];
+}

package/Interfaces/Stats/index.d.ts

@@ -0,0 +1,2 @@
+export * from './StatsClient';
+export * from './StatsContainer';

package/{interfaces → Interfaces}/Suppressions/Bounce.d.ts

@@ -1,9 +1,3 @@
-export interface BounceData {
-    address: string;
-    code: number;
-    error: string;
-    created_at: string | Date;
-}
 export interface IBounce {
     address: string;
     code: number;

package/{interfaces → Interfaces}/Suppressions/Complaint.d.ts

@@ -1,7 +1,3 @@
-export interface ComplaintData {
-    address: string;
-    created_at: string | Date;
-}
 export interface IComplaint {
     address: string;
     created_at: Date;

package/Interfaces/Suppressions/ISuppressionsClient.d.ts

@@ -0,0 +1,11 @@
+import { SuppressionList, SuppressionCreationData, SuppressionCreationResult, SuppressionListQuery, SuppressionDestroyResult } from '../../Types/Suppressions';
+import { IBounce } from './Bounce';
+import { IComplaint } from './Complaint';
+import { IUnsubscribe } from './Unsubscribe';
+import { IWhiteList } from './WhiteList';
+export interface ISuppressionClient {
+    list(domain: string, type: string, query?: SuppressionListQuery): Promise<SuppressionList>;
+    get(domain: string, type: string, address: string): Promise<IBounce | IComplaint | IUnsubscribe | IWhiteList>;
+    create(domain: string, type: string, data: SuppressionCreationData | SuppressionCreationData[]): Promise<SuppressionCreationResult>;
+    destroy(domain: string, type: string, address: string): Promise<SuppressionDestroyResult>;
+}

package/{interfaces → Interfaces}/Suppressions/Unsubscribe.d.ts

@@ -1,8 +1,3 @@
-export interface UnsubscribeData {
-    address: string;
-    tags: any;
-    created_at: string | Date;
-}
 export interface IUnsubscribe {
     address: string;
     tags: any;

package/Interfaces/Suppressions/WhiteList.d.ts

@@ -0,0 +1,6 @@
+export interface IWhiteList {
+    type: string;
+    value: string;
+    reason: string;
+    createdAt: Date;
+}

package/Interfaces/Suppressions/index.d.ts

@@ -0,0 +1,5 @@
+export * from './Bounce';
+export * from './Complaint';
+export * from './Unsubscribe';
+export * from './WhiteList';
+export * from './ISuppressionsClient';

package/Interfaces/Validations/MultipleValidation.d.ts

@@ -0,0 +1,7 @@
+import { MultipleValidationJobsListResult, MultipleValidationJobResult, CreatedMultipleValidationJob, CanceledMultipleValidationJob, MultipleValidationCreationData, MultipleValidationJobsListQuery } from '../../Types/Validations';
+export interface IMultipleValidationClient {
+    list(query?: MultipleValidationJobsListQuery): Promise<MultipleValidationJobsListResult>;
+    get(listId: string): Promise<MultipleValidationJobResult>;
+    create(listId: string, data: MultipleValidationCreationData): Promise<CreatedMultipleValidationJob>;
+    destroy(listId: string): Promise<CanceledMultipleValidationJob>;
+}

package/Interfaces/Validations/Validation.d.ts

@@ -0,0 +1,6 @@
+import { ValidationResult } from '../../Types/Validations';
+import { IMultipleValidationClient } from './MultipleValidation';
+export interface IValidationClient {
+    multipleValidation: IMultipleValidationClient;
+    get(address: string): Promise<ValidationResult>;
+}

package/Interfaces/Validations/index.d.ts

@@ -0,0 +1,2 @@
+export * from './MultipleValidation';
+export * from './Validation';

package/Interfaces/Webhooks/IWebHooksClient.d.ts

@@ -0,0 +1,9 @@
+import { WebhooksIds } from '../../Enums';
+import { WebhookList, WebhookResult, WebhooksQuery, WebhookValidationResponse } from '../../Types/Webhooks';
+export interface IWebHooksClient {
+    list(domain: string, query: WebhooksQuery): Promise<WebhookList>;
+    get(domain: string, id: WebhooksIds): Promise<WebhookResult>;
+    create(domain: string, id: string, url: string, test: boolean): Promise<WebhookResult | WebhookValidationResponse>;
+    update(domain: string, id: string, url: string): Promise<WebhookResult>;
+    destroy(domain: string, id: string): Promise<WebhookResult>;
+}

package/Interfaces/Webhooks/index.d.ts

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

package/Interfaces/index.d.ts

@@ -0,0 +1,13 @@
+export * from './Common';
+export * from './Domains';
+export * from './MailgunClient';
+export * from './MailingLists';
+export * from './Stats';
+export * from './Suppressions';
+export * from './Validations';
+export * from './EventClient';
+export * from './Webhooks';
+export * from './Messages';
+export * from './Routes';
+export * from './IPs';
+export * from './IPPools';

package/README.md

@@ -1,4 +1,4 @@
-# Mailgun.js [![Build Status](https://travis-ci.org/mailgun/mailgun-js.svg)](https://travis-ci.org/mailgun/mailgun-js)
+# Mailgun.js
 
 A javascript sdk for Mailgun built with webpack, babel & es6. This can be used in node or in the browser*.
 
@@ -9,6 +9,10 @@ __Table of Contents__
 - [Documentation](#documentation)
   - [Install](#install)
   - [Setup Client](#setup-client)
+    - [Available Imports](#imports)
+    - [Types imports](#types-imports)
+    - [Interfaces and Enums imports](#interfaces-and-enums-imports)
+  - [Generated docs](#generated-docs)
   - [Methods](#methods)
   - [Browser Demo](#browser-demo)
   - [Examples](https://github.com/mailgun/mailgun-js/tree/master/examples)
@@ -19,6 +23,7 @@ __Table of Contents__
   - [Release Process](#release-process)
 
 # Documentation
+[Mailgun API Documentation](https://documentation.mailgun.com/en/latest/api_reference.html):
 
 ## Install
 
@@ -36,19 +41,39 @@ Next, require the module and instantiate a mailgun client by calling `new Mailgu
 
 NOTE: starting from version 3.0 you need to pass FormData (we need this to keep library universal). For node.js you can use `form-data` library.
 
+### Imports
+Once the package is installed, you can import the library using `import` or `require` approach:
+
 ```js
-const formData = require('form-data');
-const Mailgun = require('mailgun.js');
-const mailgun = new Mailgun(formData);
-const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
+  const formData = require('form-data');
+  const Mailgun = require('mailgun.js');
+  const mailgun = new Mailgun(formData);
+  const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
 ```
-
-In the case your mailgun account is eu hosted you would need to define eu's subdomain as `url` in mailgun's Client constructor:
-
 ```js
-const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere', url: 'https://api.eu.mailgun.net'});
+  import * as FormData from 'form-data';
+  import Mailgun from 'mailgun.js';
+  const mailgun = new Mailgun(formData);
+  const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
+```
+### Types imports
+Starting from version **9.0.0.** Types can be includes as named import:
+```TS
+ import Mailgun, { MailgunClientOptions, MessagesSendResult } from 'mailgun.js';
 ```
 
+### Interfaces and Enums imports
+Starting from version **9.0.0.** Interfaces and Enums can be imported in the next way:
+```TS
+  import Mailgun, { Interfaces, Enums } from 'mailgun.js';
+  ...
+  const mailgunClient: Interfaces.IMailgunClient = mailgun.client(clientOptions);
+  const yes = Enums.YesNo.YES;
+  ...
+```
+
+### Generated docs
+The list of all available Types, Interfaces and Enums is auto-generated and located in the docs/ folder.
 
 ## Methods
 
@@ -268,9 +293,7 @@ Method naming conventions:
           messageParams.inline = file;
           return mg.messages.create('sandbox-123.mailgun.org', messageParams);
         })
-        .then(response => {
-            console.log(response);
-        })
+        .then(response => console.log(response))
       ```
 
     - Browser example of send file
@@ -317,7 +340,13 @@ Method naming conventions:
 
   To provide values for a substitution you need to use 'h:X-Mailgun-Variables' property in the message description.
 
-  Make sure that this property is a JSON string like {"title":"A title", "body":"The body"}.
+  Make sure that this property is a JSON string like:
+  ```js
+  JSON.stringify({
+    "title": "A title",
+    "body": "The body"
+  })
+  ```
 
   You can find few examples of how to use templates below.
 - Providing values for **title** and **slug** variables to render in template

package/Types/Common/ApiResponse.d.ts

@@ -0,0 +1,4 @@
+export type APIResponse = {
+    status: number;
+    body: any;
+};

package/Types/Common/Error.d.ts

@@ -0,0 +1,19 @@
+export type APIErrorOptions = {
+    headers?: {
+        [key: string]: unknown;
+    };
+    status: number;
+    message?: string;
+    body: {
+        error?: string;
+        message?: string;
+    };
+    url?: string;
+    statusText?: string;
+};
+export type APIErrorType = {
+    stack: string;
+    status: number;
+    message: string;
+    details: string;
+};

package/Types/Common/FormData.d.ts

@@ -0,0 +1,7 @@
+import * as NodeFormData from 'form-data';
+export type FormDataOptions = {
+    [key: string]: any;
+};
+export type InputFormData = {
+    new (options?: HTMLFormElement | FormDataOptions): NodeFormData | FormData;
+};

package/{interfaces → Types/Common}/NavigationThruPages.d.ts

@@ -1,33 +1,33 @@
-export interface PagesList {
+export type PagesList = {
     previous: string;
     first: string;
     last: string;
     next: string;
-}
-export interface ParsedPage {
+};
+export type ParsedPage = {
     id: string;
     page: string;
     iteratorPosition: string | undefined;
     url: string;
-}
-export interface ParsedPagesList {
+};
+export type ParsedPagesList = {
     previous: ParsedPage;
     first: ParsedPage;
     last: ParsedPage;
     next: ParsedPage;
-}
-export interface PagesListAccumulator {
+};
+export type PagesListAccumulator = {
     [index: string]: ParsedPage;
-}
-export interface ResponseWithPaging {
+};
+export type ResponseWithPaging = {
     body: {
         paging: PagesList;
     };
-}
-export interface QueryWithPage {
+};
+export type QueryWithPage = {
     page?: string;
-}
-export interface UpdatedUrlAndQuery {
+};
+export type UpdatedUrlAndQuery = {
     url: string;
     updatedQuery: Record<string, unknown>;
-}
+};

package/{interfaces → Types/Common}/RequestOptions.d.ts

@@ -1,15 +1,15 @@
 import { AxiosRequestHeaders, RawAxiosRequestHeaders } from 'axios';
-import Options from './Options';
-export interface OnCallEmptyHeaders {
+import { MailgunClientOptions } from '../MailgunClient';
+export type OnCallEmptyHeaders = {
     [key: string]: undefined;
-}
-export interface RequestOptions extends Options {
+};
+export type RequestOptions = MailgunClientOptions & {
     headers: AxiosRequestHeaders | RawAxiosRequestHeaders;
     timeout: number;
-}
-export interface OnCallRequestOptions {
+};
+export type OnCallRequestOptions = {
     timeout?: number;
     headers?: AxiosRequestHeaders | RawAxiosRequestHeaders;
     query?: any;
     [key: string]: unknown | undefined;
-}
+};

package/Types/Common/index.d.ts

@@ -0,0 +1,5 @@
+export * from './Error';
+export * from './ApiResponse';
+export * from './FormData';
+export * from './NavigationThruPages';
+export * from './RequestOptions';

package/Types/Domains/DomainCredentials.d.ts

@@ -0,0 +1,46 @@
+export type DomainCredentialsQuery = {
+    limit: number;
+    skip: number;
+};
+export type DomainCredentials = {
+    login: string;
+    password: string;
+};
+export type DomainCredentialsItem = {
+    created_at: string;
+    login: string;
+    mailbox: string;
+    size_bytes: number | null;
+};
+export type DomainCredentialsResponseData = {
+    status: number;
+    body: {
+        items: DomainCredentialsItem[];
+        total_count: number;
+    };
+};
+export type DomainCredentialsList = {
+    items: DomainCredentialsItem[];
+    totalCount: number;
+};
+export type DomainCredentialsResult = {
+    status: number;
+    message: string;
+    spec?: string;
+};
+export type CreatedUpdatedDomainCredentialsResponse = {
+    status: number;
+    body: {
+        message: string;
+    };
+};
+export type DeletedDomainCredentialsResponse = {
+    status: number;
+    body: {
+        message: string;
+        spec: string;
+    };
+};
+export type UpdateDomainCredentialsData = {
+    password: string;
+};