Add support for Email Logs API

Author: mklocek

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## [Unreleased]
 
 - Add StatsApi with get, byDomain, byCategory, byEmailServiceProvider, byDate endpoints
+- Add Email Logs API
 
 ## [4.4.0] - 2025-12-08
 

README.md

@@ -227,65 +227,43 @@ See transport usage below:
 Email API:
 
 - Send an email (Transactional stream) – [`sending/minimal.ts`](examples/sending/minimal.ts)
-
 - Send an email (Bulk stream) – [`bulk/send-mail.ts`](examples/bulk/send-mail.ts)
-
 - Send an email with a Template (Transactional) – [`sending/template.ts`](examples/sending/template.ts)
-
 - Send an email with a Template (Bulk) – [`bulk/send-mail.ts`](examples/bulk/send-mail.ts)
-
 - Batch send (Transactional) – [`batch/transactional.ts`](examples/batch/transactional.ts)
-
-- Batch send (Bulk) – [`batch/bulk.ts`](examples/batch/bulk.ts)
-
+- Batch send (Bulk) – [`batch/bulk.ts`](examples/bulk/bulk.ts)
 - Batch send with Template (Transactional) – [`batch/template.ts`](examples/batch/template.ts)
-
 - Batch send with Template (Bulk) – [`batch/template.ts`](examples/batch/template.ts)
-
 - Sending domain management CRUD – [`sending-domains/everything.ts`](examples/sending-domains/everything.ts)
+- Sending stats (aggregated and by domain, category, ESP, date) – [`stats/everything.ts`](examples/stats/everything.ts)
+- Email logs (list with filters, get by message ID) – [`email-logs/everything.ts`](examples/email-logs/everything.ts)
 
 Email Sandbox (Testing):
 
 - Send an email (Sandbox) – [`testing/send-mail.ts`](examples/testing/send-mail.ts)
-
 - Send an email with a Template (Sandbox) – [`testing/template.ts`](examples/testing/template.ts)
-
 - Batch send (Sandbox) – [`batch/sandbox.ts`](examples/batch/sandbox.ts)
-
 - Batch send with Template (Sandbox) – [`batch/sandbox.ts`](examples/batch/sandbox.ts)
-
 - Message management CRUD – [`testing/messages.ts`](examples/testing/messages.ts)
-
 - Inbox management CRUD – [`testing/inboxes.ts`](examples/testing/inboxes.ts)
-
 - Project management CRUD – [`testing/projects.ts`](examples/testing/projects.ts)
-
 - Attachments operations – [`testing/attachments.ts`](examples/testing/attachments.ts)
 
 Contact management:
 
 - Contacts CRUD & listing – [`contacts/everything.ts`](examples/contacts/everything.ts)
-
 - Contact lists CRUD – [`contact-lists/everything.ts`](examples/contact-lists/everything.ts)
-
 - Custom fields CRUD – [`contact-fields/everything.ts`](examples/contact-fields/everything.ts)
-
 - Import/Export – [`contact-imports/everything.ts`](examples/contact-imports/everything.ts), [`contact-exports/everything.ts`](examples/contact-exports/everything.ts)
-
 - Events – [`contact-events/everything.ts`](examples/contact-events/everything.ts)
 
 General API:
 
 - Templates CRUD – [`templates/everything.ts`](examples/templates/everything.ts)
-
 - Suppressions (find & delete) – [`sending/suppressions.ts`](examples/sending/suppressions.ts)
-
 - Billing info – [`general/billing.ts`](examples/general/billing.ts)
-
 - Accounts info – [`general/accounts.ts`](examples/general/accounts.ts)
-
 - Permissions listing – [`general/permissions.ts`](examples/general/permissions.ts)
-
 - Users listing – [`general/account-accesses.ts`](examples/general/account-accesses.ts)
 
 ## Contributing

examples/email-logs/everything.ts

@@ -0,0 +1,53 @@
+import { MailtrapClient } from "mailtrap";
+
+const TOKEN = "<YOUR-TOKEN-HERE>";
+const ACCOUNT_ID = "<YOUR-ACCOUNT-ID-HERE>";
+
+const client = new MailtrapClient({
+  token: TOKEN,
+  accountId: Number(ACCOUNT_ID),
+});
+
+async function emailLogsFlow() {
+  try {
+    // List email logs (paginated)
+    const list = await client.emailLogs.getList();
+    console.log("Email logs:", list.messages.length, "messages, total:", list.total_count);
+    if (list.messages.length > 0) {
+      console.log("First message:", list.messages[0].message_id, list.messages[0].subject);
+    }
+
+    // List with filters (date range, category, status). Filter values can be single or array.
+    const now = new Date();
+    const twoDaysAgo = new Date(now.getTime() - 2 * 24 * 60 * 60 * 1000);
+    const filtered = await client.emailLogs.getList({
+      filters: {
+        sent_after: twoDaysAgo.toISOString(),
+        sent_before: now.toISOString(),
+        subject: { operator: "not_empty" },
+        to: { operator: "ci_equal", value: "recipient@example.com" },
+        category: { operator: "equal", value: ["Welcome Email", "Forget Password"] },
+      },
+    });
+    console.log("Filtered logs:", filtered.messages.length);
+
+    // Next page (use search_after from previous response next_page_cursor)
+    if (list.next_page_cursor) {
+      const nextPage = await client.emailLogs.getList({
+        search_after: list.next_page_cursor,
+      });
+      console.log("Next page:", nextPage.messages.length, "messages");
+    }
+
+    // Get a single message by ID
+    if (list.messages.length > 0) {
+      const messageId = list.messages[0].message_id;
+      const message = await client.emailLogs.get(messageId);
+      console.log("Single message:", message.subject, "events:", message.events?.length ?? 0);
+    }
+  } catch (error) {
+    console.error("Error in emailLogsFlow:", error instanceof Error ? error.message : String(error));
+  }
+}
+
+emailLogsFlow();

package.json

@@ -4,17 +4,18 @@
   "version": "4.4.0",
   "author": "Railsware Products Studio LLC",
   "dependencies": {
-    "axios": ">=0.27"
+    "axios": ">=0.27",
+    "qs": "^6.15.0"
   },
   "devDependencies": {
-    "rimraf": "^5.0.5",
     "@babel/core": "^7.20.5",
     "@babel/preset-env": "^7.20.2",
     "@babel/preset-typescript": "^7.18.6",
     "@jest/globals": "^29.3.1",
     "@types/jest": "^29.5.3",
     "@types/node": "^18.15.11",
     "@types/nodemailer": "^6.4.9",
+    "@types/qs": "^6.15.0",
     "@typescript-eslint/eslint-plugin": "^5.57.1",
     "@typescript-eslint/parser": "^5.57.1",
     "axios-mock-adapter": "^1.21.2",
@@ -28,6 +29,7 @@
     "jest": "^29.3.1",
     "nodemailer": "^7.0.7",
     "prettier": "^2.6.2",
+    "rimraf": "^5.0.5",
     "ts-node": "^10.2.1",
     "typescript": "^5.0.3"
   },