Contacts api

README.md

@@ -58,6 +58,8 @@ Refer to the [`examples`](examples) folder for the source code of this and other
  - [List User & Invite account accesses](examples/general/account-accesses.ts)
  - [Remove account access](examples/general/accounts.ts)
  - [Permissions](examples/general/permissions.ts)
+ - [Contacts](examples/contacts/everything.ts.ts)
+ - [Contact Lists](examples/contacts/contact-lists.ts)
 
 ### Sending API
 

examples/contacts/contact-lists.ts

@@ -0,0 +1,19 @@
+import { MailtrapClient } from "mailtrap";
+
+const TOKEN = "<YOUR-TOKEN-HERE>";
+const ACCOUNT_ID = "<YOUR-ACCOUNT-ID-HERE>"
+
+const client = new MailtrapClient({ 
+  token: TOKEN,
+  accountId: ACCOUNT_ID 
+});
+
+// List all contact lists
+client.contactLists
+  .list()
+  .then(response => {
+    console.log("Contact lists:", response.data);
+  })
+  .catch(error => {
+    console.error("Error fetching contact lists:", error);
+  });

examples/contacts/everything.ts

@@ -0,0 +1,44 @@
+import { MailtrapClient } from "mailtrap";
+
+const TOKEN = "<YOUR-TOKEN-HERE>";
+const ACCOUNT_ID = "<YOUR-ACCOUNT-ID-HERE>"
+
+const client = new MailtrapClient({
+  token: TOKEN,
+  accountId: ACCOUNT_ID
+});
+
+const contactData = {
+  email: "[email protected]",
+  fields: {
+    first_name: "John",
+    last_name: "Smith"
+  },
+  list_ids: [1, 2, 3]
+};
+
+// Create contact
+client.contacts
+  .create(contactData)
+  .then(async (response) => {
+    console.log("Contact created:", response.data);
+    const contactId = response.data.id;
+
+    // Update contact
+    const updateResponse = await client.contacts
+      .update(contactId, {
+        fields: {
+          first_name: "Johnny",
+          last_name: "Smith",
+          company: "New Corp"
+        }
+      })
+    console.log("Contact updated:", updateResponse.data);
+    // Delete contact
+    await client.general.contacts
+      .delete(contactId)
+    console.log("Contact deleted");
+  })
+  .catch(error => {
+    console.error("Error in contact lifecycle:", error);
+  }); 

src/__tests__/lib/mailtrap-client.test.ts

@@ -11,7 +11,8 @@ import TestingAPI from "../../lib/api/Testing";
 import GeneralAPI from "../../lib/api/General";
 
 const { ERRORS, CLIENT_SETTINGS } = CONFIG;
-const { TESTING_ENDPOINT, BULK_ENDPOINT, SENDING_ENDPOINT } = CLIENT_SETTINGS;
+const { TESTING_ENDPOINT, BULK_ENDPOINT, SENDING_ENDPOINT, GENERAL_ENDPOINT } =
+  CLIENT_SETTINGS;
 const { TEST_INBOX_ID_MISSING, ACCOUNT_ID_MISSING, BULK_SANDBOX_INCOMPATIBLE } =
   ERRORS;
 
@@ -729,4 +730,143 @@ describe("lib/mailtrap-client: ", () => {
       });
     });
   });
+
+  describe("contacts API:", () => {
+    it("successfully creates a contact", async () => {
+      const client = new MailtrapClient({
+        token: "MY_API_TOKEN",
+        accountId: 123,
+      });
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/123/contacts`;
+      const expectedResponseData = {
+        id: 1,
+        email: "[email protected]",
+        fields: { first_name: "John", last_name: "Smith" },
+      };
+      mock.onPost(endpoint).reply(200, expectedResponseData);
+
+      const contactData = {
+        email: "[email protected]",
+        fields: { first_name: "John", last_name: "Smith" },
+      };
+
+      const result = await client.contacts.create(contactData);
+
+      expect(mock.history.post[0].url).toEqual(endpoint);
+      expect(mock.history.post[0].data).toEqual(
+        JSON.stringify({ contact: contactData })
+      );
+      expect(result).toEqual(expectedResponseData);
+    });
+
+    it("successfully updates a contact", async () => {
+      const client = new MailtrapClient({
+        token: "MY_API_TOKEN",
+        accountId: 123,
+      });
+      const contactId = 1;
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/123/contacts/${contactId}`;
+      const expectedResponseData = {
+        id: contactId,
+        email: "[email protected]",
+        fields: { first_name: "Johnny", last_name: "Smith" },
+      };
+      mock.onPatch(endpoint).reply(200, expectedResponseData);
+
+      const updateData = {
+        email: "[email protected]",
+        fields: { first_name: "Johnny", last_name: "Smith" },
+      };
+
+      const result = await client.contacts.update(contactId, updateData);
+
+      expect(mock.history.patch[0].url).toEqual(endpoint);
+      expect(mock.history.patch[0].data).toEqual(
+        JSON.stringify({ contact: updateData })
+      );
+      expect(result).toEqual(expectedResponseData);
+    });
+
+    it("successfully deletes a contact", async () => {
+      const client = new MailtrapClient({
+        token: "MY_API_TOKEN",
+        accountId: 123,
+      });
+      const contactId = 1;
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/123/contacts/${contactId}`;
+      const expectedResponseData = { success: true };
+      mock.onDelete(endpoint).reply(200, expectedResponseData);
+
+      const result = await client.contacts.delete(contactId);
+
+      expect(mock.history.delete[0].url).toEqual(endpoint);
+      expect(result).toEqual(expectedResponseData);
+    });
+
+    it("handles API errors for contacts", async () => {
+      const client = new MailtrapClient({
+        token: "MY_API_TOKEN",
+        accountId: 123,
+      });
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/123/contacts`;
+      const responseData = {
+        success: false,
+        errors: ["email is required"],
+      };
+      mock.onPost(endpoint).reply(400, responseData);
+
+      try {
+        await client.contacts.create({} as any);
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual("email is required");
+        }
+      }
+    });
+  });
+
+  describe("contact lists API:", () => {
+    it("successfully lists contact lists", async () => {
+      const client = new MailtrapClient({
+        token: "MY_API_TOKEN",
+        accountId: 123,
+      });
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/123/contacts/lists`;
+      const expectedResponseData = {
+        lists: [
+          { id: 1, name: "Marketing" },
+          { id: 2, name: "Sales" },
+        ],
+      };
+      mock.onGet(endpoint).reply(200, expectedResponseData);
+
+      const result = await client.contactLists.list();
+
+      expect(mock.history.get[0].url).toEqual(endpoint);
+      expect(result).toEqual(expectedResponseData);
+    });
+
+    it("handles API errors for contact lists", async () => {
+      const client = new MailtrapClient({
+        token: "MY_API_TOKEN",
+        accountId: 123,
+      });
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/123/contacts/lists`;
+      const responseData = {
+        success: false,
+        errors: ["account not found"],
+      };
+      mock.onGet(endpoint).reply(404, responseData);
+
+      try {
+        await client.contactLists.list();
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual("account not found");
+        }
+      }
+    });
+  });
 });

src/lib/MailtrapClient.ts

@@ -8,6 +8,7 @@ import handleSendingError from "./axios-logger";
 
 import GeneralAPI from "./api/General";
 import TestingAPI from "./api/Testing";
+import ContactsApi from "./api/resources/contacts/Contacts";
 
 import CONFIG from "../config";
 
@@ -19,6 +20,7 @@ import {
   BatchSendRequest,
 } from "../types/mailtrap";
 import MailtrapError from "./MailtrapError";
+import ContactListsApi from "./api/resources/contacts/ContactLists";
 
 const { CLIENT_SETTINGS, ERRORS } = CONFIG;
 const {
@@ -102,6 +104,20 @@ export default class MailtrapClient {
     return new GeneralAPI(this.axios, this.accountId);
   }
 
+  /**
+   * Getter for Contacts API.
+   */
+  get contacts() {
+    return new ContactsApi(this.axios, this.accountId);
+  }
+
+  /**
+   * Getter for Contact Lists API.
+   */
+  get contactLists() {
+    return new ContactListsApi(this.axios, this.accountId);
+  }
+
   /**
    * Returns configured host. Checks if `bulk` and `sandbox` modes are activated simultaneously,
    *   then reject with Mailtrap Error.

src/lib/api/Contacts.ts

@@ -0,0 +1,21 @@
+import { AxiosInstance } from "axios";
+
+import ContactsApi from "./resources/contacts/Contacts";
+import ContactListsApi from "./resources/contacts/ContactLists";
+
+export default class ContactsAPI {
+  private client: AxiosInstance;
+
+  private accountId?: number;
+
+  public contacts: ContactsApi;
+
+  public contactLists: ContactListsApi;
+
+  constructor(client: AxiosInstance, accountId?: number) {
+    this.client = client;
+    this.accountId = accountId;
+    this.contacts = new ContactsApi(this.client, this.accountId);
+    this.contactLists = new ContactListsApi(this.client);
+  }
+}

src/lib/api/resources/contacts/ContactLists.ts

@@ -0,0 +1,24 @@
+import { AxiosInstance } from "axios";
+
+import CONFIG from "../../../../config";
+
+const { CLIENT_SETTINGS } = CONFIG;
+const { GENERAL_ENDPOINT } = CLIENT_SETTINGS;
+
+export default class ContactListsApi {
+  private client: AxiosInstance;
+
+  private contactListsURL: string;
+
+  constructor(client: AxiosInstance, accountId?: number) {
+    this.client = client;
+    this.contactListsURL = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/contacts/lists`;
+  }
+
+  /**
+   * Lists all contact lists for the account.
+   */
+  public async list() {
+    return this.client.get(this.contactListsURL);
+  }
+}

src/lib/api/resources/contacts/Contacts.ts

@@ -0,0 +1,40 @@
+import { AxiosInstance } from "axios";
+import { ContactData } from "../../../../types/mailtrap";
+import CONFIG from "../../../../config";
+
+const { CLIENT_SETTINGS } = CONFIG;
+const { GENERAL_ENDPOINT } = CLIENT_SETTINGS;
+
+export default class ContactsApi {
+  private client: AxiosInstance;
+
+  private contactsURL: string;
+
+  constructor(client: AxiosInstance, accountId?: number) {
+    this.client = client;
+    this.contactsURL = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/contacts`;
+  }
+
+  /**
+   * Creates a new contact.
+   */
+  public async create(data: ContactData) {
+    return this.client.post(this.contactsURL, { contact: data });
+  }
+
+  /**
+   * Updates an existing contact.
+   */
+  public async update(id: number, data: ContactData) {
+    const url = `${this.contactsURL}/${id}`;
+    return this.client.patch(url, { contact: data });
+  }
+
+  /**
+   * Deletes a contact.
+   */
+  public async delete(id: number) {
+    const url = `${this.contactsURL}/${id}`;
+    return this.client.delete(url);
+  }
+}

src/types/mailtrap.ts

@@ -111,3 +111,15 @@ export interface BatchSendRequest {
     custom_variables?: Record<string, string>;
   }[];
 }
+
+export interface ContactFields {
+  first_name?: string;
+  last_name?: string;
+  [key: string]: string | undefined;
+}
+
+export interface ContactData {
+  email: string;
+  fields?: ContactFields;
+  list_ids?: number[];
+}