Suppressions api

README.md

@@ -76,6 +76,7 @@ Refer to the [`examples`](examples) folder for the source code of this and other
  - [Advanced](examples/sending/everything.ts)
  - [Minimal](examples/sending/minimal.ts)
  - [Send email using template](examples/sending/template.ts)
+ - [Suppressions](examples/sending/suppressions.ts)
  - [Nodemailer transport](examples/sending/transport.ts)
 
 ### Batch Sending API

examples/sending/suppressions.ts

@@ -0,0 +1,30 @@
+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
+});
+
+async function suppressionsFlow() {
+  // Get suppressions (up to 1000 per request)
+  const suppressions = await client.suppressions.getList();
+  console.log("Suppressions (up to 1000):", suppressions);
+
+  // Get suppressions filtered by email
+  const filteredSuppressions = await client.suppressions.getList({email: "test@example.com"});
+  console.log("Filtered suppressions:", filteredSuppressions);
+
+  // Delete a suppression by ID (if any exist)
+  if (suppressions.length > 0) {
+    const suppressionToDelete = suppressions[0];
+    await client.suppressions.delete(suppressionToDelete.id);
+    console.log(`Suppression ${suppressionToDelete.id} deleted successfully`);
+  } else {
+    console.log("No suppressions found to delete");
+  }
+}
+
+suppressionsFlow().catch(console.error);

src/__tests__/lib/api/ContactLists.test.ts

@@ -8,7 +8,7 @@ describe("lib/api/ContactLists: ", () => {
 
   describe("class ContactLists(): ", () => {
     describe("init: ", () => {
-      it("initalizes with all necessary params.", () => {
+      it("initializes with all necessary params.", () => {
         expect(contactListsAPI).toHaveProperty("create");
         expect(contactListsAPI).toHaveProperty("getList");
         expect(contactListsAPI).toHaveProperty("get");

src/__tests__/lib/api/Contacts.test.ts

@@ -8,7 +8,7 @@ describe("lib/api/Contacts: ", () => {
 
   describe("class Contacts(): ", () => {
     describe("init: ", () => {
-      it("initalizes with all necessary params.", () => {
+      it("initializes with all necessary params.", () => {
         expect(contactsAPI).toHaveProperty("create");
         expect(contactsAPI).toHaveProperty("get");
         expect(contactsAPI).toHaveProperty("update");

src/__tests__/lib/api/General.test.ts

@@ -8,7 +8,7 @@ describe("lib/api/General: ", () => {
 
   describe("class General(): ", () => {
     describe("init: ", () => {
-      it("initalizes with all necessary params.", () => {
+      it("initializes with all necessary params.", () => {
         expect(generalAPI).toHaveProperty("accountAccesses");
         expect(generalAPI).toHaveProperty("accounts");
         expect(generalAPI).toHaveProperty("permissions");

src/__tests__/lib/api/Suppressions.test.ts

@@ -0,0 +1,17 @@
+import axios from "axios";
+
+import SuppressionsBaseAPI from "../../../lib/api/Suppressions";
+
+describe("lib/api/Suppressions: ", () => {
+  const accountId = 100;
+  const suppressionsAPI = new SuppressionsBaseAPI(axios, accountId);
+
+  describe("class SuppressionsBaseAPI(): ", () => {
+    describe("init: ", () => {
+      it("initializes with all necessary params.", () => {
+        expect(suppressionsAPI).toHaveProperty("getList");
+        expect(suppressionsAPI).toHaveProperty("delete");
+      });
+    });
+  });
+});

src/__tests__/lib/api/Templates.test.ts

@@ -8,7 +8,7 @@ describe("lib/api/Templates: ", () => {
 
   describe("class TemplatesBaseAPI(): ", () => {
     describe("init: ", () => {
-      it("initalizes with all necessary params.", () => {
+      it("initializes with all necessary params.", () => {
         expect(templatesAPI).toHaveProperty("create");
         expect(templatesAPI).toHaveProperty("getList");
         expect(templatesAPI).toHaveProperty("get");

src/__tests__/lib/api/Testing.test.ts

@@ -8,7 +8,7 @@ describe("lib/api/Testing: ", () => {
 
   describe("class Testing(): ", () => {
     describe("init: ", () => {
-      it("initalizes with all necessary params.", () => {
+      it("initializes with all necessary params.", () => {
         expect(testingAPI).toHaveProperty("projects");
         expect(testingAPI).toHaveProperty("inboxes");
         expect(testingAPI).toHaveProperty("messages");

src/__tests__/lib/api/resources/AccountAccesses.test.ts

@@ -42,7 +42,7 @@ describe("lib/api/resources/AccountAccesses: ", () => {
 
   describe("class AccountAccesses(): ", () => {
     describe("init: ", () => {
-      it("initalizes with all necessary params.", () => {
+      it("initializes with all necessary params.", () => {
         expect(accountAccessesAPI).toHaveProperty("listAccountAccesses");
         expect(accountAccessesAPI).toHaveProperty("removeAccountAccess");
       });

src/__tests__/lib/api/resources/Accounts.test.ts

@@ -22,7 +22,7 @@ describe("lib/api/resources/Accounts: ", () => {
 
   describe("class Accounts(): ", () => {
     describe("init: ", () => {
-      it("initalizes with all necessary params.", () => {
+      it("initializes with all necessary params.", () => {
         expect(accountsAPI).toHaveProperty("getAllAccounts");
       });
     });

src/__tests__/lib/api/resources/Attachments.test.ts

@@ -34,7 +34,7 @@ describe("lib/api/resources/Attachments: ", () => {
 
   describe("class Attachments(): ", () => {
     describe("init: ", () => {
-      it("initalizes with all necessary params.", () => {
+      it("initializes with all necessary params.", () => {
         expect(attachmentsAPI).toHaveProperty("get");
         expect(attachmentsAPI).toHaveProperty("getList");
       });

src/__tests__/lib/api/resources/Inboxes.test.ts

@@ -42,7 +42,7 @@ describe("lib/api/resources/Inboxes: ", () => {
 
   describe("class Inboxes(): ", () => {
     describe("init: ", () => {
-      it("initalizes with all necessary params.", () => {
+      it("initializes with all necessary params.", () => {
         expect(inboxesAPI).toHaveProperty("cleanInbox");
         expect(inboxesAPI).toHaveProperty("create");
         expect(inboxesAPI).toHaveProperty("delete");

src/__tests__/lib/api/resources/Messages.test.ts

@@ -45,7 +45,7 @@ describe("lib/api/resources/Messages: ", () => {
 
   describe("class Messages(): ", () => {
     describe("init: ", () => {
-      it("initalizes with all necessary params.", () => {
+      it("initializes with all necessary params.", () => {
         expect(messagesAPI).toHaveProperty("deleteMessage");
         expect(messagesAPI).toHaveProperty("forward");
         expect(messagesAPI).toHaveProperty("get");

src/__tests__/lib/api/resources/Permissions.test.ts

@@ -28,7 +28,7 @@ describe("lib/api/resources/Permissions: ", () => {
 
   describe("class Permissions(): ", () => {
     describe("init: ", () => {
-      it("initalizes with all necessary params.", () => {
+      it("initializes with all necessary params.", () => {
         expect(permissionsAPI).toHaveProperty("getResources");
         expect(permissionsAPI).toHaveProperty("bulkPermissionsUpdate");
       });

src/__tests__/lib/api/resources/Projects.test.ts

@@ -24,7 +24,7 @@ describe("lib/api/resources/Projects: ", () => {
 
   describe("class Projects(): ", () => {
     describe("init: ", () => {
-      it("initalizes with all necessary params.", () => {
+      it("initializes with all necessary params.", () => {
         expect(projectsAPI).toHaveProperty("create");
         expect(projectsAPI).toHaveProperty("delete");
         expect(projectsAPI).toHaveProperty("getById");

src/__tests__/lib/api/resources/Suppressions.test.ts

@@ -0,0 +1,206 @@
+import axios from "axios";
+import AxiosMockAdapter from "axios-mock-adapter";
+
+import SuppressionsApi from "../../../../lib/api/resources/Suppressions";
+import handleSendingError from "../../../../lib/axios-logger";
+import MailtrapError from "../../../../lib/MailtrapError";
+import { Suppression } from "../../../../types/api/suppressions";
+
+import CONFIG from "../../../../config";
+
+const { CLIENT_SETTINGS } = CONFIG;
+const { GENERAL_ENDPOINT } = CLIENT_SETTINGS;
+
+describe("lib/api/resources/Suppressions: ", () => {
+  let mock: AxiosMockAdapter;
+  const accountId = 100;
+  const suppressionsAPI = new SuppressionsApi(axios, accountId);
+
+  const mockSuppression: Suppression = {
+    id: "1",
+    email: "test@example.com",
+    type: "hard bounce",
+    created_at: "2023-01-01T00:00:00Z",
+    sending_stream: "transactional",
+    domain_name: "example.com",
+    message_bounce_category: "bad_mailbox",
+    message_category: "test",
+    message_client_ip: "192.168.1.1",
+    message_created_at: "2023-01-01T00:00:00Z",
+    message_outgoing_ip: "10.0.0.1",
+    message_recipient_mx_name: "mx.example.com",
+    message_sender_email: "sender@example.com",
+    message_subject: "Test Email",
+  };
+
+  const mockSuppressions: Suppression[] = [
+    {
+      id: "1",
+      email: "test1@example.com",
+      type: "hard bounce",
+      created_at: "2023-01-01T00:00:00Z",
+      sending_stream: "transactional",
+      domain_name: "example.com",
+      message_bounce_category: "bad_mailbox",
+      message_category: "test",
+      message_client_ip: "192.168.1.1",
+      message_created_at: "2023-01-01T00:00:00Z",
+      message_outgoing_ip: "10.0.0.1",
+      message_recipient_mx_name: "mx.example.com",
+      message_sender_email: "sender@example.com",
+      message_subject: "Test Email 1",
+    },
+    {
+      id: "2",
+      email: "test2@example.com",
+      type: "spam complaint",
+      created_at: "2023-01-02T00:00:00Z",
+      sending_stream: "bulk",
+      domain_name: "example.com",
+      message_bounce_category: null,
+      message_category: "promotional",
+      message_client_ip: "192.168.1.2",
+      message_created_at: "2023-01-02T00:00:00Z",
+      message_outgoing_ip: "10.0.0.2",
+      message_recipient_mx_name: "mx.example.com",
+      message_sender_email: "sender@example.com",
+      message_subject: "Test Email 2",
+    },
+  ];
+
+  describe("class SuppressionsApi(): ", () => {
+    describe("init: ", () => {
+      it("initializes with all necessary params.", () => {
+        expect(suppressionsAPI).toHaveProperty("getList");
+        expect(suppressionsAPI).toHaveProperty("delete");
+      });
+    });
+  });
+
+  beforeAll(() => {
+    axios.interceptors.response.use(
+      (response) => response.data,
+      handleSendingError
+    );
+    mock = new AxiosMockAdapter(axios);
+  });
+
+  afterEach(() => {
+    mock.reset();
+  });
+
+  describe("getList(): ", () => {
+    it("successfully gets suppressions (up to 1000 per request).", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/suppressions`;
+
+      expect.assertions(2);
+
+      mock.onGet(endpoint).reply(200, mockSuppressions);
+      const result = await suppressionsAPI.getList();
+
+      expect(mock.history.get[0].url).toEqual(endpoint);
+      expect(result).toEqual(mockSuppressions);
+    });
+
+    it("successfully gets suppressions filtered by email.", async () => {
+      const email = "test@example.com";
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/suppressions`;
+
+      expect.assertions(3);
+
+      mock.onGet(endpoint, { params: { email } }).reply(200, [mockSuppression]);
+      const result = await suppressionsAPI.getList({ email });
+
+      expect(mock.history.get[0].url).toEqual(endpoint);
+      expect(mock.history.get[0].params).toEqual({ email });
+      expect(result).toEqual([mockSuppression]);
+    });
+
+    it("fails with unauthorized error (401).", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/suppressions`;
+      const expectedErrorMessage = "Incorrect API token";
+
+      expect.assertions(2);
+
+      mock.onGet(endpoint).reply(401, { error: expectedErrorMessage });
+
+      try {
+        await suppressionsAPI.getList();
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual(expectedErrorMessage);
+        }
+      }
+    });
+
+    it("fails with forbidden error (403).", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/suppressions`;
+      const expectedErrorMessage = "Access forbidden";
+
+      expect.assertions(2);
+
+      mock.onGet(endpoint).reply(403, { errors: expectedErrorMessage });
+
+      try {
+        await suppressionsAPI.getList();
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual(expectedErrorMessage);
+        }
+      }
+    });
+  });
+
+  describe("delete(): ", () => {
+    const suppressionId = "1";
+
+    it("successfully deletes a suppression.", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/suppressions/${suppressionId}`;
+
+      expect.assertions(1);
+
+      mock.onDelete(endpoint).reply(204);
+      await suppressionsAPI.delete(suppressionId);
+
+      expect(mock.history.delete[0].url).toEqual(endpoint);
+    });
+
+    it("fails with unauthorized error (401).", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/suppressions/${suppressionId}`;
+      const expectedErrorMessage = "Incorrect API token";
+
+      expect.assertions(2);
+
+      mock.onDelete(endpoint).reply(401, { error: expectedErrorMessage });
+
+      try {
+        await suppressionsAPI.delete(suppressionId);
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual(expectedErrorMessage);
+        }
+      }
+    });
+
+    it("fails with forbidden error (403).", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/suppressions/${suppressionId}`;
+      const expectedErrorMessage = "Access forbidden";
+
+      expect.assertions(2);
+
+      mock.onDelete(endpoint).reply(403, { errors: expectedErrorMessage });
+
+      try {
+        await suppressionsAPI.delete(suppressionId);
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual(expectedErrorMessage);
+        }
+      }
+    });
+  });
+});