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 all suppressions
+  const allSuppressions = await client.suppressions.getList();
+  console.log("All suppressions:", allSuppressions);
+
+  // Get suppressions filtered by email
+  const filteredSuppressions = await client.suppressions.getList("test@example.com");
+  console.log("Filtered suppressions:", filteredSuppressions);
+
+  // Delete a suppression by ID (if any exist)
+  if (allSuppressions.length > 0) {
+    const suppressionToDelete = allSuppressions[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/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("initalizes with all necessary params.", () => {
+        expect(suppressionsAPI).toHaveProperty("getList");
+        expect(suppressionsAPI).toHaveProperty("delete");
+      });
+    });
+  });
+});

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

@@ -0,0 +1,170 @@
+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 all suppressions.", 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 error.", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/suppressions`;
+      const expectedErrorMessage = "Request failed with status code 400";
+
+      expect.assertions(2);
+
+      mock.onGet(endpoint).reply(400, { error: 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 error.", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/suppressions/${suppressionId}`;
+      const expectedErrorMessage = "Request failed with status code 404";
+
+      expect.assertions(2);
+
+      mock.onDelete(endpoint).reply(404, { error: expectedErrorMessage });
+
+      try {
+        await suppressionsAPI.delete(suppressionId);
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual(expectedErrorMessage);
+        }
+      }
+    });
+  });
+});

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

@@ -12,6 +12,7 @@ import TestingAPI from "../../lib/api/Testing";
 import ContactLists from "../../lib/api/ContactLists";
 import Contacts from "../../lib/api/Contacts";
 import TemplatesBaseAPI from "../../lib/api/Templates";
+import SuppressionsBaseAPI from "../../lib/api/Suppressions";
 
 const { ERRORS, CLIENT_SETTINGS } = CONFIG;
 const { TESTING_ENDPOINT, BULK_ENDPOINT, SENDING_ENDPOINT } = CLIENT_SETTINGS;
@@ -809,5 +810,31 @@ describe("lib/mailtrap-client: ", () => {
         expect(templatesClient).toBeInstanceOf(TemplatesBaseAPI);
       });
     });
+
+    describe("get suppressions(): ", () => {
+      it("rejects with Mailtrap error, when `accountId` is missing.", () => {
+        const client = new MailtrapClient({
+          token: "MY_API_TOKEN",
+        });
+        expect.assertions(1);
+
+        try {
+          client.suppressions;
+        } catch (error) {
+          expect(error).toEqual(new MailtrapError(ACCOUNT_ID_MISSING));
+        }
+      });
+
+      it("returns suppressions API object when accountId is provided.", () => {
+        const client = new MailtrapClient({
+          token: "MY_API_TOKEN",
+          accountId: 10,
+        });
+        expect.assertions(1);
+
+        const suppressionsClient = client.suppressions;
+        expect(suppressionsClient).toBeInstanceOf(SuppressionsBaseAPI);
+      });
+    });
   });
 });

src/lib/MailtrapClient.ts

@@ -22,6 +22,7 @@ import {
   BatchSendResponse,
   BatchSendRequest,
 } from "../types/mailtrap";
+import SuppressionsBaseAPI from "./api/Suppressions";
 
 const { CLIENT_SETTINGS, ERRORS } = CONFIG;
 const {
@@ -132,12 +133,26 @@ export default class MailtrapClient {
     return new ContactListsBaseAPI(this.axios, this.accountId);
   }
 
+  /**
+   * Getter for Templates API.
+   */
   get templates() {
     this.validateAccountIdPresence();
 
     return new TemplatesBaseAPI(this.axios, this.accountId);
   }
 
+  /**
+   * Getter for Suppressions API.
+   */
+  get suppressions() {
+    if (!this.accountId) {
+      throw new MailtrapError(ACCOUNT_ID_MISSING);
+    }
+
+    return new SuppressionsBaseAPI(this.axios, this.accountId);
+  }
+
   /**
    * Returns configured host. Checks if `bulk` and `sandbox` modes are activated simultaneously,
    *   then reject with Mailtrap Error.

src/lib/api/Suppressions.ts

@@ -0,0 +1,21 @@
+import { AxiosInstance } from "axios";
+
+import SuppressionsApi from "./resources/Suppressions";
+
+export default class SuppressionsBaseAPI {
+  private client: AxiosInstance;
+
+  private accountId?: number;
+
+  public getList: SuppressionsApi["getList"];
+
+  public delete: SuppressionsApi["delete"];
+
+  constructor(client: AxiosInstance, accountId?: number) {
+    this.client = client;
+    this.accountId = accountId;
+    const suppressions = new SuppressionsApi(this.client, this.accountId);
+    this.getList = suppressions.getList.bind(suppressions);
+    this.delete = suppressions.delete.bind(suppressions);
+  }
+}

src/lib/api/resources/Suppressions.ts

@@ -0,0 +1,44 @@
+import { AxiosInstance } from "axios";
+
+import CONFIG from "../../../config";
+import { ListOptions, Suppression } from "../../../types/api/suppressions";
+
+const { CLIENT_SETTINGS } = CONFIG;
+const { GENERAL_ENDPOINT } = CLIENT_SETTINGS;
+
+export default class SuppressionsApi {
+  private client: AxiosInstance;
+
+  private accountId?: number;
+
+  private suppressionsURL: string;
+
+  constructor(client: AxiosInstance, accountId?: number) {
+    this.client = client;
+    this.accountId = accountId;
+    this.suppressionsURL = `${GENERAL_ENDPOINT}/api/accounts/${this.accountId}/suppressions`;
+  }
+
+  /**
+   * List and search suppressions by email. The endpoint returns up to 1000 suppressions per request.
+   */
+  public async getList(options?: ListOptions) {
+    const params = {
+      ...(options?.email && { email: options.email }),
+    };
+
+    return this.client.get<Suppression[], Suppression[]>(this.suppressionsURL, {
+      params,
+    });
+  }
+
+  /**
+   * Delete a suppression by ID.
+   * Mailtrap will no longer prevent sending to this email unless it's recorded in suppressions again.
+   */
+  public async delete(id: string) {
+    return this.client.delete<Suppression, Suppression>(
+      `${this.suppressionsURL}/${id}`
+    );
+  }
+}

src/types/api/suppressions.ts

@@ -0,0 +1,20 @@
+export type Suppression = {
+  id: string;
+  type: "hard bounce" | "spam complaint" | "unsubscription" | "manual import";
+  created_at: string;
+  email: string;
+  sending_stream: "transactional" | "bulk";
+  domain_name: string | null;
+  message_bounce_category: string | null;
+  message_category: string | null;
+  message_client_ip: string | null;
+  message_created_at: string | null;
+  message_outgoing_ip: string | null;
+  message_recipient_mx_name: string | null;
+  message_sender_email: string | null;
+  message_subject: string | null;
+};
+
+export type ListOptions = {
+  email?: string;
+};