mailisk 2.0.0 → 2.1.1

package/.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: Build and Test
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    name: Test
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Use Node.js 18.x
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18.x
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test

package/README.md

@@ -35,7 +35,7 @@ const { MailiskClient } = require("mailisk");
 const mailisk = new MailiskClient({ apiKey: "YOUR_API_KEY" });
 
 // send email (using virtual SMTP)
-await client.sendVirtualEmail(namespace, {
+await mailisk.sendVirtualEmail(namespace, {
   from: "test@example.com",
   to: `john@${namespace}.mailisk.net`,
   subject: "Testing",
@@ -43,7 +43,7 @@ await client.sendVirtualEmail(namespace, {
 });
 
 // receive email
-const result = await client.searchInbox(namespace);
+const result = await mailisk.searchInbox(namespace);
 
 console.log(result);
 ```
@@ -54,35 +54,42 @@ This library wraps the REST API endpoints. Find out more in the [API Reference](
 
 ## Client functions
 
-### searchInbox(namespace, params?)
+### `searchInbox(namespace, params?)`
+
+Use `searchInbox` to fetch messages that arrived in a given namespace, optionally waiting until the first new mail shows up.
+
+For the full parameter options see the [endpoint reference](https://docs.mailisk.com/api-reference/search-inbox.html#request-1).
+
+Default behaviour:
 
-The `searchInbox` function takes a namespace and call parameters.
+- Waits until at least one new email arrives (override with `wait: false`).
+- Times out after 5 minutes if nothing shows up (adjust via `requestOptions.timeout`).
+- Ignores messages older than 15 minutes to avoid picking up leftovers from previous tests (change via `from_timestamp`).
 
-- By default it uses the `wait` flag. This means the call won't return until at least one email is received. Disabling this flag via `wait: false` can cause it to return an empty response immediately.
-- The request timeout is adjustable by passing `timeout` in the request options. By default it uses a timeout of 5 minutes.
-- By default `from_timestamp` is set to **current timestamp - 5 seconds**. This ensures that only new emails are returned. Without this, older emails would also be returned, potentially disrupting you if you were waiting for a specific email. This can be overriden by passing the `from_timestamp` parameter (`from_timestmap: 0` will disable filtering by email age).
+#### Quick examples
 
 ```js
-// timeout of 5 minutes
-await mailisk.searchInbox(namespace);
-// timeout of 1 minute
+// wait up to the default 5 min for *any* new mail
+const { data: emails } = await mailisk.searchInbox(namespace);
+
+// custom 60-second timeout
 await mailisk.searchInbox(namespace, {}, { timeout: 1000 * 60 });
-// returns immediately, even if the result would be empty
+
+// polling pattern — return immediately, even if inbox is empty
 await mailisk.searchInbox(namespace, { wait: false });
 ```
 
 #### Filter by destination address
 
-A common use case is filtering the returned emails by the destination address, this is done using the `to_addr_prefix` parameter.
+A common pattern is to wait for the email your UI just triggered (e.g. password-reset).
+Pass `to_addr_prefix` so you don’t pick up stale messages:
 
 ```js
 const { data: emails } = await mailisk.searchInbox(namespace, {
-  to_addr_prefix: "john@mynamespace.mailisk.net",
+  to_addr_prefix: `john@${namespace}.mailisk.net`,
 });
 ```
 
-For more parameter options see the [endpoint reference](https://docs.mailisk.com/api-reference/search-inbox.html#request-1).
-
 ### sendVirtualEmail(namespace, params)
 
 Send an email using [Virtual SMTP](https://docs.mailisk.com/smtp.html). This will fetch the SMTP settings for the selected namespace and send an email. These emails can only be sent to an address that ends in `@{namespace}.mailisk.net`.
@@ -100,7 +107,7 @@ await mailisk.sendVirtualEmail(namespace, {
 
 This does not call an API endpoint but rather uses nodemailer to send an email using SMTP.
 
-### listNamespaces()
+### `listNamespaces()`
 
 List all namespaces associated with the current API Key.
 
@@ -110,3 +117,44 @@ const namespacesResponse = await mailisk.listNamespaces();
 // will be ['namespace1', 'namespace2']
 const namespaces = namespacesResponse.map((nr) => nr.namespace);
 ```
+
+### `getAttachment(attachmentId)`
+
+Get information about an attachment.
+
+```ts
+const attachment = await mailisk.getAttachment(attachmentId);
+```
+
+### `downloadAttachment(attachmentId)`
+
+Retrieve the raw bytes of a file attached to an email message.  
+Typically you call this after `searchInbox` → iterate over `email.attachments[]` → pass the desired `attachment.id`.
+
+#### Quick examples
+
+```js
+import fs from "node:fs";
+import path from "node:path";
+
+// assume 'email' was fetched via searchInbox()
+const { id, filename } = email.attachments[0];
+
+// download the attachment
+const buffer = await mailisk.downloadAttachment(id);
+
+// save to disk (preserve original filename)
+fs.writeFileSync(filename, buffer);
+```
+
+Streaming large files
+
+downloadAttachment returns the entire file as a single Buffer.
+If you expect very large attachments and want to avoid holding them fully in memory, use getAttachment(attachmentId).download_url and stream with fetch / axios instead:
+
+```js
+const meta = await mailisk.getAttachment(id);
+const res = await fetch(meta.download_url);
+const fileStream = fs.createWriteStream(filename);
+await new Promise((ok, err) => res.body.pipe(fileStream).on("finish", ok).on("error", err));
+```

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { AxiosRequestConfig } from 'axios';
+import { AxiosBasicCredentials, AxiosRequestConfig } from 'axios';
+import { Attachment } from 'nodemailer/lib/mailer';
 
 interface EmailAddress {
     /** Email address */
@@ -6,6 +7,16 @@ interface EmailAddress {
     /** Display name, if one is specified */
     name?: string;
 }
+interface EmailAttachment {
+    /** Unique identifier for the attachment */
+    id: string;
+    /** Filename of the attachment */
+    filename: string;
+    /** Content type of the attachment */
+    content_type: string;
+    /** Size in bytes of the attachment */
+    size: number;
+}
 interface Email {
     /** Namespace scoped ID */
     id: string;
@@ -31,6 +42,10 @@ interface Email {
     expires_timestamp: number;
     /** The spam score as reported by SpamAssassin */
     spam_score?: number;
+    /** The headers of the email */
+    headers?: Record<string, string>;
+    /** The attachments of the email */
+    attachments?: EmailAttachment[];
 }
 interface SearchInboxParams {
     /**
@@ -52,9 +67,21 @@ interface SearchInboxParams {
     /**
      * Filter emails by 'to' address. Address must start with this.
      *
-     * 'foo' would return 'foobar@namespace.mailisk.net' but not 'barfoo@namespace.mailisk.net'
+     * 'foo' would return for 'foobar@namespace.mailisk.net' but not 'barfoo@namespace.mailisk.net'
      */
     to_addr_prefix?: string;
+    /**
+     * Filter emails by 'from' address. Address must include this.
+     *
+     * '@foo' would return for 'a@foo.com', 'b@foo.net'
+     */
+    from_addr_includes?: string;
+    /**
+     * Filter emails by subject. This is case insensitive. Subject must include this.
+     *
+     * 'password' would return for 'Password reset', 'Reset password notification' but not 'Reset'
+     */
+    subject_includes?: string;
     /**
      * Will keep the request going till at least one email would be returned.
      *
@@ -84,6 +111,16 @@ interface SmtpSettings {
         password: string;
     };
 }
+interface GetAttachmentResponse {
+    data: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        expires_at: string | null;
+        download_url: string;
+    };
+}
 interface ListNamespacesResponse {
     data: [
         {
@@ -107,12 +144,17 @@ interface SendVirtualEmailParams {
     text?: string | undefined;
     /** The HTML version of the message */
     html?: string | undefined;
+    /** Custom headers for the email */
+    headers?: Record<string, string>;
+    /** Attachments to the email */
+    attachments?: Attachment[];
 }
 
 declare class MailiskClient {
-    constructor({ apiKey, baseUrl }: {
+    constructor({ apiKey, baseUrl, auth }: {
         apiKey: string;
         baseUrl?: string;
+        auth?: AxiosBasicCredentials;
     });
     private readonly axiosInstance;
     /**
@@ -163,6 +205,21 @@ declare class MailiskClient {
      * Get the SMTP settings for a namespace.
      */
     getSmtpSettings(namespace: string): Promise<SmtpSettings>;
+    getAttachment(attachmentId: string): Promise<GetAttachmentResponse>;
+    /**
+     * Download an attachment from an attachment ID.
+     *
+     * @example
+     * Download an attachment from an email
+     * ```typescript
+     * const attachment = email.attachments[0];
+     * const attachmentBuffer = await client.downloadAttachment(attachment.id);
+     *
+     * // save to file
+     * fs.writeFileSync(attachment.filename, attachmentBuffer);
+     * ```
+     */
+    downloadAttachment(attachmentId: string): Promise<Buffer>;
 }
 
 export { MailiskClient };

package/dist/index.js

@@ -35,12 +35,13 @@ module.exports = __toCommonJS(src_exports);
 var import_axios = __toESM(require("axios"));
 var import_nodemailer = __toESM(require("nodemailer"));
 var MailiskClient = class {
-  constructor({ apiKey, baseUrl }) {
+  constructor({ apiKey, baseUrl, auth }) {
     this.axiosInstance = import_axios.default.create({
       headers: {
         "X-Api-Key": apiKey
       },
-      baseURL: baseUrl || "https://api.mailisk.com/"
+      baseURL: baseUrl || "https://api.mailisk.com/",
+      auth
     });
   }
   axiosInstance;
@@ -58,30 +59,35 @@ var MailiskClient = class {
         pass: smtpSettings.data.password
       }
     });
-    const { from, to, subject, text, html } = params;
+    const { from, to, subject, text, html, headers, attachments } = params;
     await transport.sendMail({
       from,
       to,
       subject,
       text,
-      html
+      html,
+      headers,
+      attachments
     });
     transport.close();
   }
   async searchInbox(namespace, params, config) {
     let _params = { ...params };
     if (params?.from_timestamp === void 0 || params?.from_timestamp === null) {
-      _params.from_timestamp = Math.floor(new Date().getTime() / 1e3) - 5;
+      _params.from_timestamp = Math.floor(new Date().getTime() / 1e3) - 15 * 60;
     }
     if (params?.wait !== false) {
       _params.wait = true;
     }
     let _config = { ...config };
+    if (!config?.maxRedirects) {
+      _config.maxRedirects = 99999;
+    }
     if (_params.wait && !config?.timeout) {
       _config.timeout = 1e3 * 60 * 5;
     }
     return (await this.axiosInstance.get(`api/emails/${namespace}/inbox`, {
-      ...config,
+      ..._config,
       params: _params
     })).data;
   }
@@ -89,6 +95,15 @@ var MailiskClient = class {
     const result = await this.axiosInstance.get(`api/smtp/${namespace}`);
     return result.data;
   }
+  async getAttachment(attachmentId) {
+    const result = await this.axiosInstance.get(`api/attachments/${attachmentId}`);
+    return result.data;
+  }
+  async downloadAttachment(attachmentId) {
+    const result = await this.getAttachment(attachmentId);
+    const response = await import_axios.default.get(result.data.download_url, { responseType: "arraybuffer" });
+    return Buffer.from(response.data);
+  }
 };
 __name(MailiskClient, "MailiskClient");
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/mailisk.ts"],"sourcesContent":["export * from \"./mailisk\";\n","import axios, { AxiosRequestConfig } from \"axios\";\nimport {\n  ListNamespacesResponse,\n  SearchInboxParams,\n  SearchInboxResponse,\n  SendVirtualEmailParams,\n  SmtpSettings,\n} from \"./mailisk.interfaces\";\nimport nodemailer from \"nodemailer\";\n\nexport class MailiskClient {\n  constructor({ apiKey, baseUrl }: { apiKey: string; baseUrl?: string }) {\n    this.axiosInstance = axios.create({\n      headers: {\n        \"X-Api-Key\": apiKey,\n      },\n      baseURL: baseUrl || \"https://api.mailisk.com/\",\n    });\n  }\n\n  private readonly axiosInstance;\n\n  /**\n   * List all namespaces that belong to the current account (API key).\n   */\n  async listNamespaces(): Promise<ListNamespacesResponse> {\n    return (await this.axiosInstance.get(\"api/namespaces\")).data;\n  }\n\n  /**\n   * Send an email using the Virtual SMTP.\n   *\n   * These emails can only be sent to valid Mailisk namespaces, i.e. emails that end in @mynamespace.mailisk.net\n   *\n   * @example\n   * For example, sending a test email:\n   * ```typescript\n   * client.sendVirtualEmail(namespace, {\n   *   from: \"test@example.com\",\n   *   to: `john@${namespace}.mailisk.net`,\n   *   subject: \"This is a test\",\n   *   text: \"Testing\",\n   * });\n   * ```\n   */\n  async sendVirtualEmail(namespace: string, params: SendVirtualEmailParams): Promise<void> {\n    const smtpSettings = await this.getSmtpSettings(namespace);\n\n    // TODO: to should match namespace\n\n    const transport = nodemailer.createTransport({\n      host: smtpSettings.data.host,\n      port: smtpSettings.data.port,\n      secure: false,\n      auth: {\n        user: smtpSettings.data.username,\n        pass: smtpSettings.data.password,\n      },\n    });\n\n    const { from, to, subject, text, html } = params;\n\n    await transport.sendMail({\n      from,\n      to,\n      subject,\n      text,\n      html,\n    });\n\n    transport.close();\n  }\n\n  /**\n   * Search inbox of a namespace.\n   *\n   * By default, this calls the api using the `wait` flag. This means the call won't timeout until at least one email is received or 5 minutes pass.\n   * It also uses a default `from_timestamp` of **current timestamp - 5 seconds**. This means that older emails will be ignored.\n   *\n   * Both of these settings can be overriden by passing them in the `params` object.\n   *\n   * @example\n   * Get the latest emails in the namespace\n   * ```typescript\n   * const { data: emails } = await client.searchInbox(namespace);\n   * ```\n   *\n   * @example\n   * Get the latest emails for a specific email address\n   * ```typescript\n   * const { data: emails } = await client.searchInbox(namespace, {\n   *  to_addr_prefix: 'john@mynamespace.mailisk.net'\n   * });\n   * ```\n   */\n  async searchInbox(\n    namespace: string,\n    params?: SearchInboxParams,\n    config?: AxiosRequestConfig\n  ): Promise<SearchInboxResponse> {\n    let _params = { ...params };\n\n    // default from timestamp, 5 seconds before starting this request\n    if (params?.from_timestamp === undefined || params?.from_timestamp === null) {\n      _params.from_timestamp = Math.floor(new Date().getTime() / 1000) - 5;\n    }\n\n    // by default wait for email\n    if (params?.wait !== false) {\n      _params.wait = true;\n    }\n\n    let _config = { ...config };\n\n    // by default, wait 5 minutes for emails before timing out\n    if (_params.wait && !config?.timeout) {\n      _config.timeout = 1000 * 60 * 5;\n    }\n\n    return (\n      await this.axiosInstance.get(`api/emails/${namespace}/inbox`, {\n        ...config,\n        params: _params,\n      })\n    ).data;\n  }\n\n  /**\n   * Get the SMTP settings for a namespace.\n   */\n  async getSmtpSettings(namespace: string): Promise<SmtpSettings> {\n    const result = await this.axiosInstance.get(`api/smtp/${namespace}`);\n    return result.data;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAA0C;AAQ1C,wBAAuB;AAEhB,IAAM,gBAAN,MAAoB;AAAA,EACzB,YAAY,EAAE,QAAQ,QAAQ,GAAyC;AACrE,SAAK,gBAAgB,aAAAA,QAAM,OAAO;AAAA,MAChC,SAAS;AAAA,QACP,aAAa;AAAA,MACf;AAAA,MACA,SAAS,WAAW;AAAA,IACtB,CAAC;AAAA,EACH;AAAA,EAEiB;AAAA,EAKjB,MAAM,iBAAkD;AACtD,YAAQ,MAAM,KAAK,cAAc,IAAI,gBAAgB,GAAG;AAAA,EAC1D;AAAA,EAkBA,MAAM,iBAAiB,WAAmB,QAA+C;AACvF,UAAM,eAAe,MAAM,KAAK,gBAAgB,SAAS;AAIzD,UAAM,YAAY,kBAAAC,QAAW,gBAAgB;AAAA,MAC3C,MAAM,aAAa,KAAK;AAAA,MACxB,MAAM,aAAa,KAAK;AAAA,MACxB,QAAQ;AAAA,MACR,MAAM;AAAA,QACJ,MAAM,aAAa,KAAK;AAAA,QACxB,MAAM,aAAa,KAAK;AAAA,MAC1B;AAAA,IACF,CAAC;AAED,UAAM,EAAE,MAAM,IAAI,SAAS,MAAM,KAAK,IAAI;AAE1C,UAAM,UAAU,SAAS;AAAA,MACvB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAED,cAAU,MAAM;AAAA,EAClB;AAAA,EAwBA,MAAM,YACJ,WACA,QACA,QAC8B;AAC9B,QAAI,UAAU,EAAE,GAAG,OAAO;AAG1B,QAAI,QAAQ,mBAAmB,UAAa,QAAQ,mBAAmB,MAAM;AAC3E,cAAQ,iBAAiB,KAAK,MAAM,IAAI,KAAK,EAAE,QAAQ,IAAI,GAAI,IAAI;AAAA,IACrE;AAGA,QAAI,QAAQ,SAAS,OAAO;AAC1B,cAAQ,OAAO;AAAA,IACjB;AAEA,QAAI,UAAU,EAAE,GAAG,OAAO;AAG1B,QAAI,QAAQ,QAAQ,CAAC,QAAQ,SAAS;AACpC,cAAQ,UAAU,MAAO,KAAK;AAAA,IAChC;AAEA,YACE,MAAM,KAAK,cAAc,IAAI,cAAc,mBAAmB;AAAA,MAC5D,GAAG;AAAA,MACH,QAAQ;AAAA,IACV,CAAC,GACD;AAAA,EACJ;AAAA,EAKA,MAAM,gBAAgB,WAA0C;AAC9D,UAAM,SAAS,MAAM,KAAK,cAAc,IAAI,YAAY,WAAW;AACnE,WAAO,OAAO;AAAA,EAChB;AACF;AA5Ha;","names":["axios","nodemailer"]}
+{"version":3,"sources":["../src/index.ts","../src/mailisk.ts"],"sourcesContent":["export * from \"./mailisk\";\n","import axios, { AxiosBasicCredentials, AxiosRequestConfig } from \"axios\";\nimport {\n  GetAttachmentResponse,\n  ListNamespacesResponse,\n  SearchInboxParams,\n  SearchInboxResponse,\n  SendVirtualEmailParams,\n  SmtpSettings,\n} from \"./mailisk.interfaces\";\nimport nodemailer from \"nodemailer\";\n\nexport class MailiskClient {\n  constructor({ apiKey, baseUrl, auth }: { apiKey: string; baseUrl?: string; auth?: AxiosBasicCredentials }) {\n    this.axiosInstance = axios.create({\n      headers: {\n        \"X-Api-Key\": apiKey,\n      },\n      baseURL: baseUrl || \"https://api.mailisk.com/\",\n      auth,\n    });\n  }\n\n  private readonly axiosInstance;\n\n  /**\n   * List all namespaces that belong to the current account (API key).\n   */\n  async listNamespaces(): Promise<ListNamespacesResponse> {\n    return (await this.axiosInstance.get(\"api/namespaces\")).data;\n  }\n\n  /**\n   * Send an email using the Virtual SMTP.\n   *\n   * These emails can only be sent to valid Mailisk namespaces, i.e. emails that end in @mynamespace.mailisk.net\n   *\n   * @example\n   * For example, sending a test email:\n   * ```typescript\n   * client.sendVirtualEmail(namespace, {\n   *   from: \"test@example.com\",\n   *   to: `john@${namespace}.mailisk.net`,\n   *   subject: \"This is a test\",\n   *   text: \"Testing\",\n   * });\n   * ```\n   */\n  async sendVirtualEmail(namespace: string, params: SendVirtualEmailParams): Promise<void> {\n    const smtpSettings = await this.getSmtpSettings(namespace);\n\n    const transport = nodemailer.createTransport({\n      host: smtpSettings.data.host,\n      port: smtpSettings.data.port,\n      secure: false,\n      auth: {\n        user: smtpSettings.data.username,\n        pass: smtpSettings.data.password,\n      },\n    });\n\n    const { from, to, subject, text, html, headers, attachments } = params;\n\n    await transport.sendMail({\n      from,\n      to,\n      subject,\n      text,\n      html,\n      headers,\n      attachments,\n    });\n\n    transport.close();\n  }\n\n  /**\n   * Search inbox of a namespace.\n   *\n   * By default, this calls the api using the `wait` flag. This means the call won't timeout until at least one email is received or 5 minutes pass.\n   * It also uses a default `from_timestamp` of **current timestamp - 5 seconds**. This means that older emails will be ignored.\n   *\n   * Both of these settings can be overriden by passing them in the `params` object.\n   *\n   * @example\n   * Get the latest emails in the namespace\n   * ```typescript\n   * const { data: emails } = await client.searchInbox(namespace);\n   * ```\n   *\n   * @example\n   * Get the latest emails for a specific email address\n   * ```typescript\n   * const { data: emails } = await client.searchInbox(namespace, {\n   *  to_addr_prefix: 'john@mynamespace.mailisk.net'\n   * });\n   * ```\n   */\n  async searchInbox(\n    namespace: string,\n    params?: SearchInboxParams,\n    config?: AxiosRequestConfig\n  ): Promise<SearchInboxResponse> {\n    let _params = { ...params };\n\n    // default from timestamp, 15 minutes before starting this request\n    if (params?.from_timestamp === undefined || params?.from_timestamp === null) {\n      _params.from_timestamp = Math.floor(new Date().getTime() / 1000) - 15 * 60;\n    }\n\n    // by default wait for email\n    if (params?.wait !== false) {\n      _params.wait = true;\n    }\n\n    let _config = { ...config };\n\n    if (!config?.maxRedirects) {\n      _config.maxRedirects = 99999;\n    }\n\n    // by default, wait 5 minutes for emails before timing out\n    if (_params.wait && !config?.timeout) {\n      _config.timeout = 1000 * 60 * 5;\n    }\n\n    return (\n      await this.axiosInstance.get(`api/emails/${namespace}/inbox`, {\n        ..._config,\n        params: _params,\n      })\n    ).data;\n  }\n\n  /**\n   * Get the SMTP settings for a namespace.\n   */\n  async getSmtpSettings(namespace: string): Promise<SmtpSettings> {\n    const result = await this.axiosInstance.get(`api/smtp/${namespace}`);\n    return result.data;\n  }\n\n  async getAttachment(attachmentId: string): Promise<GetAttachmentResponse> {\n    const result = await this.axiosInstance.get(`api/attachments/${attachmentId}`);\n    return result.data;\n  }\n\n  /**\n   * Download an attachment from an attachment ID.\n   *\n   * @example\n   * Download an attachment from an email\n   * ```typescript\n   * const attachment = email.attachments[0];\n   * const attachmentBuffer = await client.downloadAttachment(attachment.id);\n   *\n   * // save to file\n   * fs.writeFileSync(attachment.filename, attachmentBuffer);\n   * ```\n   */\n  async downloadAttachment(attachmentId: string): Promise<Buffer> {\n    const result = await this.getAttachment(attachmentId);\n\n    const response = await axios.get(result.data.download_url, { responseType: \"arraybuffer\" });\n    return Buffer.from(response.data);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAAiE;AASjE,wBAAuB;AAEhB,IAAM,gBAAN,MAAoB;AAAA,EACzB,YAAY,EAAE,QAAQ,SAAS,KAAK,GAAuE;AACzG,SAAK,gBAAgB,aAAAA,QAAM,OAAO;AAAA,MAChC,SAAS;AAAA,QACP,aAAa;AAAA,MACf;AAAA,MACA,SAAS,WAAW;AAAA,MACpB;AAAA,IACF,CAAC;AAAA,EACH;AAAA,EAEiB;AAAA,EAKjB,MAAM,iBAAkD;AACtD,YAAQ,MAAM,KAAK,cAAc,IAAI,gBAAgB,GAAG;AAAA,EAC1D;AAAA,EAkBA,MAAM,iBAAiB,WAAmB,QAA+C;AACvF,UAAM,eAAe,MAAM,KAAK,gBAAgB,SAAS;AAEzD,UAAM,YAAY,kBAAAC,QAAW,gBAAgB;AAAA,MAC3C,MAAM,aAAa,KAAK;AAAA,MACxB,MAAM,aAAa,KAAK;AAAA,MACxB,QAAQ;AAAA,MACR,MAAM;AAAA,QACJ,MAAM,aAAa,KAAK;AAAA,QACxB,MAAM,aAAa,KAAK;AAAA,MAC1B;AAAA,IACF,CAAC;AAED,UAAM,EAAE,MAAM,IAAI,SAAS,MAAM,MAAM,SAAS,YAAY,IAAI;AAEhE,UAAM,UAAU,SAAS;AAAA,MACvB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAED,cAAU,MAAM;AAAA,EAClB;AAAA,EAwBA,MAAM,YACJ,WACA,QACA,QAC8B;AAC9B,QAAI,UAAU,EAAE,GAAG,OAAO;AAG1B,QAAI,QAAQ,mBAAmB,UAAa,QAAQ,mBAAmB,MAAM;AAC3E,cAAQ,iBAAiB,KAAK,MAAM,IAAI,KAAK,EAAE,QAAQ,IAAI,GAAI,IAAI,KAAK;AAAA,IAC1E;AAGA,QAAI,QAAQ,SAAS,OAAO;AAC1B,cAAQ,OAAO;AAAA,IACjB;AAEA,QAAI,UAAU,EAAE,GAAG,OAAO;AAE1B,QAAI,CAAC,QAAQ,cAAc;AACzB,cAAQ,eAAe;AAAA,IACzB;AAGA,QAAI,QAAQ,QAAQ,CAAC,QAAQ,SAAS;AACpC,cAAQ,UAAU,MAAO,KAAK;AAAA,IAChC;AAEA,YACE,MAAM,KAAK,cAAc,IAAI,cAAc,mBAAmB;AAAA,MAC5D,GAAG;AAAA,MACH,QAAQ;AAAA,IACV,CAAC,GACD;AAAA,EACJ;AAAA,EAKA,MAAM,gBAAgB,WAA0C;AAC9D,UAAM,SAAS,MAAM,KAAK,cAAc,IAAI,YAAY,WAAW;AACnE,WAAO,OAAO;AAAA,EAChB;AAAA,EAEA,MAAM,cAAc,cAAsD;AACxE,UAAM,SAAS,MAAM,KAAK,cAAc,IAAI,mBAAmB,cAAc;AAC7E,WAAO,OAAO;AAAA,EAChB;AAAA,EAeA,MAAM,mBAAmB,cAAuC;AAC9D,UAAM,SAAS,MAAM,KAAK,cAAc,YAAY;AAEpD,UAAM,WAAW,MAAM,aAAAD,QAAM,IAAI,OAAO,KAAK,cAAc,EAAE,cAAc,cAAc,CAAC;AAC1F,WAAO,OAAO,KAAK,SAAS,IAAI;AAAA,EAClC;AACF;AA1Ja;","names":["axios","nodemailer"]}

package/dist/index.mjs

@@ -5,12 +5,13 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 import axios from "axios";
 import nodemailer from "nodemailer";
 var MailiskClient = class {
-  constructor({ apiKey, baseUrl }) {
+  constructor({ apiKey, baseUrl, auth }) {
     this.axiosInstance = axios.create({
       headers: {
         "X-Api-Key": apiKey
       },
-      baseURL: baseUrl || "https://api.mailisk.com/"
+      baseURL: baseUrl || "https://api.mailisk.com/",
+      auth
     });
   }
   axiosInstance;
@@ -28,30 +29,35 @@ var MailiskClient = class {
         pass: smtpSettings.data.password
       }
     });
-    const { from, to, subject, text, html } = params;
+    const { from, to, subject, text, html, headers, attachments } = params;
     await transport.sendMail({
       from,
       to,
       subject,
       text,
-      html
+      html,
+      headers,
+      attachments
     });
     transport.close();
   }
   async searchInbox(namespace, params, config) {
     let _params = { ...params };
     if (params?.from_timestamp === void 0 || params?.from_timestamp === null) {
-      _params.from_timestamp = Math.floor(new Date().getTime() / 1e3) - 5;
+      _params.from_timestamp = Math.floor(new Date().getTime() / 1e3) - 15 * 60;
     }
     if (params?.wait !== false) {
       _params.wait = true;
     }
     let _config = { ...config };
+    if (!config?.maxRedirects) {
+      _config.maxRedirects = 99999;
+    }
     if (_params.wait && !config?.timeout) {
       _config.timeout = 1e3 * 60 * 5;
     }
     return (await this.axiosInstance.get(`api/emails/${namespace}/inbox`, {
-      ...config,
+      ..._config,
       params: _params
     })).data;
   }
@@ -59,6 +65,15 @@ var MailiskClient = class {
     const result = await this.axiosInstance.get(`api/smtp/${namespace}`);
     return result.data;
   }
+  async getAttachment(attachmentId) {
+    const result = await this.axiosInstance.get(`api/attachments/${attachmentId}`);
+    return result.data;
+  }
+  async downloadAttachment(attachmentId) {
+    const result = await this.getAttachment(attachmentId);
+    const response = await axios.get(result.data.download_url, { responseType: "arraybuffer" });
+    return Buffer.from(response.data);
+  }
 };
 __name(MailiskClient, "MailiskClient");
 export {

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/mailisk.ts"],"sourcesContent":["import axios, { AxiosRequestConfig } from \"axios\";\nimport {\n  ListNamespacesResponse,\n  SearchInboxParams,\n  SearchInboxResponse,\n  SendVirtualEmailParams,\n  SmtpSettings,\n} from \"./mailisk.interfaces\";\nimport nodemailer from \"nodemailer\";\n\nexport class MailiskClient {\n  constructor({ apiKey, baseUrl }: { apiKey: string; baseUrl?: string }) {\n    this.axiosInstance = axios.create({\n      headers: {\n        \"X-Api-Key\": apiKey,\n      },\n      baseURL: baseUrl || \"https://api.mailisk.com/\",\n    });\n  }\n\n  private readonly axiosInstance;\n\n  /**\n   * List all namespaces that belong to the current account (API key).\n   */\n  async listNamespaces(): Promise<ListNamespacesResponse> {\n    return (await this.axiosInstance.get(\"api/namespaces\")).data;\n  }\n\n  /**\n   * Send an email using the Virtual SMTP.\n   *\n   * These emails can only be sent to valid Mailisk namespaces, i.e. emails that end in @mynamespace.mailisk.net\n   *\n   * @example\n   * For example, sending a test email:\n   * ```typescript\n   * client.sendVirtualEmail(namespace, {\n   *   from: \"test@example.com\",\n   *   to: `john@${namespace}.mailisk.net`,\n   *   subject: \"This is a test\",\n   *   text: \"Testing\",\n   * });\n   * ```\n   */\n  async sendVirtualEmail(namespace: string, params: SendVirtualEmailParams): Promise<void> {\n    const smtpSettings = await this.getSmtpSettings(namespace);\n\n    // TODO: to should match namespace\n\n    const transport = nodemailer.createTransport({\n      host: smtpSettings.data.host,\n      port: smtpSettings.data.port,\n      secure: false,\n      auth: {\n        user: smtpSettings.data.username,\n        pass: smtpSettings.data.password,\n      },\n    });\n\n    const { from, to, subject, text, html } = params;\n\n    await transport.sendMail({\n      from,\n      to,\n      subject,\n      text,\n      html,\n    });\n\n    transport.close();\n  }\n\n  /**\n   * Search inbox of a namespace.\n   *\n   * By default, this calls the api using the `wait` flag. This means the call won't timeout until at least one email is received or 5 minutes pass.\n   * It also uses a default `from_timestamp` of **current timestamp - 5 seconds**. This means that older emails will be ignored.\n   *\n   * Both of these settings can be overriden by passing them in the `params` object.\n   *\n   * @example\n   * Get the latest emails in the namespace\n   * ```typescript\n   * const { data: emails } = await client.searchInbox(namespace);\n   * ```\n   *\n   * @example\n   * Get the latest emails for a specific email address\n   * ```typescript\n   * const { data: emails } = await client.searchInbox(namespace, {\n   *  to_addr_prefix: 'john@mynamespace.mailisk.net'\n   * });\n   * ```\n   */\n  async searchInbox(\n    namespace: string,\n    params?: SearchInboxParams,\n    config?: AxiosRequestConfig\n  ): Promise<SearchInboxResponse> {\n    let _params = { ...params };\n\n    // default from timestamp, 5 seconds before starting this request\n    if (params?.from_timestamp === undefined || params?.from_timestamp === null) {\n      _params.from_timestamp = Math.floor(new Date().getTime() / 1000) - 5;\n    }\n\n    // by default wait for email\n    if (params?.wait !== false) {\n      _params.wait = true;\n    }\n\n    let _config = { ...config };\n\n    // by default, wait 5 minutes for emails before timing out\n    if (_params.wait && !config?.timeout) {\n      _config.timeout = 1000 * 60 * 5;\n    }\n\n    return (\n      await this.axiosInstance.get(`api/emails/${namespace}/inbox`, {\n        ...config,\n        params: _params,\n      })\n    ).data;\n  }\n\n  /**\n   * Get the SMTP settings for a namespace.\n   */\n  async getSmtpSettings(namespace: string): Promise<SmtpSettings> {\n    const result = await this.axiosInstance.get(`api/smtp/${namespace}`);\n    return result.data;\n  }\n}\n"],"mappings":";;;;AAAA,OAAO,WAAmC;AAQ1C,OAAO,gBAAgB;AAEhB,IAAM,gBAAN,MAAoB;AAAA,EACzB,YAAY,EAAE,QAAQ,QAAQ,GAAyC;AACrE,SAAK,gBAAgB,MAAM,OAAO;AAAA,MAChC,SAAS;AAAA,QACP,aAAa;AAAA,MACf;AAAA,MACA,SAAS,WAAW;AAAA,IACtB,CAAC;AAAA,EACH;AAAA,EAEiB;AAAA,EAKjB,MAAM,iBAAkD;AACtD,YAAQ,MAAM,KAAK,cAAc,IAAI,gBAAgB,GAAG;AAAA,EAC1D;AAAA,EAkBA,MAAM,iBAAiB,WAAmB,QAA+C;AACvF,UAAM,eAAe,MAAM,KAAK,gBAAgB,SAAS;AAIzD,UAAM,YAAY,WAAW,gBAAgB;AAAA,MAC3C,MAAM,aAAa,KAAK;AAAA,MACxB,MAAM,aAAa,KAAK;AAAA,MACxB,QAAQ;AAAA,MACR,MAAM;AAAA,QACJ,MAAM,aAAa,KAAK;AAAA,QACxB,MAAM,aAAa,KAAK;AAAA,MAC1B;AAAA,IACF,CAAC;AAED,UAAM,EAAE,MAAM,IAAI,SAAS,MAAM,KAAK,IAAI;AAE1C,UAAM,UAAU,SAAS;AAAA,MACvB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAED,cAAU,MAAM;AAAA,EAClB;AAAA,EAwBA,MAAM,YACJ,WACA,QACA,QAC8B;AAC9B,QAAI,UAAU,EAAE,GAAG,OAAO;AAG1B,QAAI,QAAQ,mBAAmB,UAAa,QAAQ,mBAAmB,MAAM;AAC3E,cAAQ,iBAAiB,KAAK,MAAM,IAAI,KAAK,EAAE,QAAQ,IAAI,GAAI,IAAI;AAAA,IACrE;AAGA,QAAI,QAAQ,SAAS,OAAO;AAC1B,cAAQ,OAAO;AAAA,IACjB;AAEA,QAAI,UAAU,EAAE,GAAG,OAAO;AAG1B,QAAI,QAAQ,QAAQ,CAAC,QAAQ,SAAS;AACpC,cAAQ,UAAU,MAAO,KAAK;AAAA,IAChC;AAEA,YACE,MAAM,KAAK,cAAc,IAAI,cAAc,mBAAmB;AAAA,MAC5D,GAAG;AAAA,MACH,QAAQ;AAAA,IACV,CAAC,GACD;AAAA,EACJ;AAAA,EAKA,MAAM,gBAAgB,WAA0C;AAC9D,UAAM,SAAS,MAAM,KAAK,cAAc,IAAI,YAAY,WAAW;AACnE,WAAO,OAAO;AAAA,EAChB;AACF;AA5Ha;","names":[]}
+{"version":3,"sources":["../src/mailisk.ts"],"sourcesContent":["import axios, { AxiosBasicCredentials, AxiosRequestConfig } from \"axios\";\nimport {\n  GetAttachmentResponse,\n  ListNamespacesResponse,\n  SearchInboxParams,\n  SearchInboxResponse,\n  SendVirtualEmailParams,\n  SmtpSettings,\n} from \"./mailisk.interfaces\";\nimport nodemailer from \"nodemailer\";\n\nexport class MailiskClient {\n  constructor({ apiKey, baseUrl, auth }: { apiKey: string; baseUrl?: string; auth?: AxiosBasicCredentials }) {\n    this.axiosInstance = axios.create({\n      headers: {\n        \"X-Api-Key\": apiKey,\n      },\n      baseURL: baseUrl || \"https://api.mailisk.com/\",\n      auth,\n    });\n  }\n\n  private readonly axiosInstance;\n\n  /**\n   * List all namespaces that belong to the current account (API key).\n   */\n  async listNamespaces(): Promise<ListNamespacesResponse> {\n    return (await this.axiosInstance.get(\"api/namespaces\")).data;\n  }\n\n  /**\n   * Send an email using the Virtual SMTP.\n   *\n   * These emails can only be sent to valid Mailisk namespaces, i.e. emails that end in @mynamespace.mailisk.net\n   *\n   * @example\n   * For example, sending a test email:\n   * ```typescript\n   * client.sendVirtualEmail(namespace, {\n   *   from: \"test@example.com\",\n   *   to: `john@${namespace}.mailisk.net`,\n   *   subject: \"This is a test\",\n   *   text: \"Testing\",\n   * });\n   * ```\n   */\n  async sendVirtualEmail(namespace: string, params: SendVirtualEmailParams): Promise<void> {\n    const smtpSettings = await this.getSmtpSettings(namespace);\n\n    const transport = nodemailer.createTransport({\n      host: smtpSettings.data.host,\n      port: smtpSettings.data.port,\n      secure: false,\n      auth: {\n        user: smtpSettings.data.username,\n        pass: smtpSettings.data.password,\n      },\n    });\n\n    const { from, to, subject, text, html, headers, attachments } = params;\n\n    await transport.sendMail({\n      from,\n      to,\n      subject,\n      text,\n      html,\n      headers,\n      attachments,\n    });\n\n    transport.close();\n  }\n\n  /**\n   * Search inbox of a namespace.\n   *\n   * By default, this calls the api using the `wait` flag. This means the call won't timeout until at least one email is received or 5 minutes pass.\n   * It also uses a default `from_timestamp` of **current timestamp - 5 seconds**. This means that older emails will be ignored.\n   *\n   * Both of these settings can be overriden by passing them in the `params` object.\n   *\n   * @example\n   * Get the latest emails in the namespace\n   * ```typescript\n   * const { data: emails } = await client.searchInbox(namespace);\n   * ```\n   *\n   * @example\n   * Get the latest emails for a specific email address\n   * ```typescript\n   * const { data: emails } = await client.searchInbox(namespace, {\n   *  to_addr_prefix: 'john@mynamespace.mailisk.net'\n   * });\n   * ```\n   */\n  async searchInbox(\n    namespace: string,\n    params?: SearchInboxParams,\n    config?: AxiosRequestConfig\n  ): Promise<SearchInboxResponse> {\n    let _params = { ...params };\n\n    // default from timestamp, 15 minutes before starting this request\n    if (params?.from_timestamp === undefined || params?.from_timestamp === null) {\n      _params.from_timestamp = Math.floor(new Date().getTime() / 1000) - 15 * 60;\n    }\n\n    // by default wait for email\n    if (params?.wait !== false) {\n      _params.wait = true;\n    }\n\n    let _config = { ...config };\n\n    if (!config?.maxRedirects) {\n      _config.maxRedirects = 99999;\n    }\n\n    // by default, wait 5 minutes for emails before timing out\n    if (_params.wait && !config?.timeout) {\n      _config.timeout = 1000 * 60 * 5;\n    }\n\n    return (\n      await this.axiosInstance.get(`api/emails/${namespace}/inbox`, {\n        ..._config,\n        params: _params,\n      })\n    ).data;\n  }\n\n  /**\n   * Get the SMTP settings for a namespace.\n   */\n  async getSmtpSettings(namespace: string): Promise<SmtpSettings> {\n    const result = await this.axiosInstance.get(`api/smtp/${namespace}`);\n    return result.data;\n  }\n\n  async getAttachment(attachmentId: string): Promise<GetAttachmentResponse> {\n    const result = await this.axiosInstance.get(`api/attachments/${attachmentId}`);\n    return result.data;\n  }\n\n  /**\n   * Download an attachment from an attachment ID.\n   *\n   * @example\n   * Download an attachment from an email\n   * ```typescript\n   * const attachment = email.attachments[0];\n   * const attachmentBuffer = await client.downloadAttachment(attachment.id);\n   *\n   * // save to file\n   * fs.writeFileSync(attachment.filename, attachmentBuffer);\n   * ```\n   */\n  async downloadAttachment(attachmentId: string): Promise<Buffer> {\n    const result = await this.getAttachment(attachmentId);\n\n    const response = await axios.get(result.data.download_url, { responseType: \"arraybuffer\" });\n    return Buffer.from(response.data);\n  }\n}\n"],"mappings":";;;;AAAA,OAAO,WAA0D;AASjE,OAAO,gBAAgB;AAEhB,IAAM,gBAAN,MAAoB;AAAA,EACzB,YAAY,EAAE,QAAQ,SAAS,KAAK,GAAuE;AACzG,SAAK,gBAAgB,MAAM,OAAO;AAAA,MAChC,SAAS;AAAA,QACP,aAAa;AAAA,MACf;AAAA,MACA,SAAS,WAAW;AAAA,MACpB;AAAA,IACF,CAAC;AAAA,EACH;AAAA,EAEiB;AAAA,EAKjB,MAAM,iBAAkD;AACtD,YAAQ,MAAM,KAAK,cAAc,IAAI,gBAAgB,GAAG;AAAA,EAC1D;AAAA,EAkBA,MAAM,iBAAiB,WAAmB,QAA+C;AACvF,UAAM,eAAe,MAAM,KAAK,gBAAgB,SAAS;AAEzD,UAAM,YAAY,WAAW,gBAAgB;AAAA,MAC3C,MAAM,aAAa,KAAK;AAAA,MACxB,MAAM,aAAa,KAAK;AAAA,MACxB,QAAQ;AAAA,MACR,MAAM;AAAA,QACJ,MAAM,aAAa,KAAK;AAAA,QACxB,MAAM,aAAa,KAAK;AAAA,MAC1B;AAAA,IACF,CAAC;AAED,UAAM,EAAE,MAAM,IAAI,SAAS,MAAM,MAAM,SAAS,YAAY,IAAI;AAEhE,UAAM,UAAU,SAAS;AAAA,MACvB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAED,cAAU,MAAM;AAAA,EAClB;AAAA,EAwBA,MAAM,YACJ,WACA,QACA,QAC8B;AAC9B,QAAI,UAAU,EAAE,GAAG,OAAO;AAG1B,QAAI,QAAQ,mBAAmB,UAAa,QAAQ,mBAAmB,MAAM;AAC3E,cAAQ,iBAAiB,KAAK,MAAM,IAAI,KAAK,EAAE,QAAQ,IAAI,GAAI,IAAI,KAAK;AAAA,IAC1E;AAGA,QAAI,QAAQ,SAAS,OAAO;AAC1B,cAAQ,OAAO;AAAA,IACjB;AAEA,QAAI,UAAU,EAAE,GAAG,OAAO;AAE1B,QAAI,CAAC,QAAQ,cAAc;AACzB,cAAQ,eAAe;AAAA,IACzB;AAGA,QAAI,QAAQ,QAAQ,CAAC,QAAQ,SAAS;AACpC,cAAQ,UAAU,MAAO,KAAK;AAAA,IAChC;AAEA,YACE,MAAM,KAAK,cAAc,IAAI,cAAc,mBAAmB;AAAA,MAC5D,GAAG;AAAA,MACH,QAAQ;AAAA,IACV,CAAC,GACD;AAAA,EACJ;AAAA,EAKA,MAAM,gBAAgB,WAA0C;AAC9D,UAAM,SAAS,MAAM,KAAK,cAAc,IAAI,YAAY,WAAW;AACnE,WAAO,OAAO;AAAA,EAChB;AAAA,EAEA,MAAM,cAAc,cAAsD;AACxE,UAAM,SAAS,MAAM,KAAK,cAAc,IAAI,mBAAmB,cAAc;AAC7E,WAAO,OAAO;AAAA,EAChB;AAAA,EAeA,MAAM,mBAAmB,cAAuC;AAC9D,UAAM,SAAS,MAAM,KAAK,cAAc,YAAY;AAEpD,UAAM,WAAW,MAAM,MAAM,IAAI,OAAO,KAAK,cAAc,EAAE,cAAc,cAAc,CAAC;AAC1F,WAAO,OAAO,KAAK,SAAS,IAAI;AAAA,EAClC;AACF;AA1Ja;","names":[]}

package/jest.config.js

@@ -0,0 +1,13 @@
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  roots: ["<rootDir>/tests"],
+  transform: {
+    "^.+\\.tsx?$": "ts-jest",
+  },
+  testRegex: "(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$",
+  moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
+  collectCoverage: true,
+  collectCoverageFrom: ["src/**/*.ts"],
+  setupFilesAfterEnv: ["<rootDir>/tests/setup.ts"],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailisk",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Mailisk library for NodeJS",
   "keywords": [
     "mailisk",
@@ -11,12 +11,20 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsup"
+    "build": "tsup",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
   },
   "author": "",
   "license": "ISC",
   "devDependencies": {
+    "@types/jest": "^29.5.14",
     "@types/nodemailer": "^6.4.6",
+    "dotenv": "^16.4.7",
+    "jest": "^29.7.0",
+    "jest-mock-axios": "^4.8.0",
+    "ts-jest": "^29.2.6",
     "tsup": "^6.2.3",
     "typescript": "^4.8.4"
   },

package/src/mailisk.interfaces.ts

@@ -1,3 +1,5 @@
+import { Attachment } from "nodemailer/lib/mailer";
+
 export interface EmailAddress {
   /** Email address */
   address: string;
@@ -5,6 +7,17 @@ export interface EmailAddress {
   name?: string;
 }
 
+export interface EmailAttachment {
+  /** Unique identifier for the attachment */
+  id: string;
+  /** Filename of the attachment */
+  filename: string;
+  /** Content type of the attachment */
+  content_type: string;
+  /** Size in bytes of the attachment */
+  size: number;
+}
+
 export interface Email {
   /** Namespace scoped ID */
   id: string;
@@ -30,6 +43,10 @@ export interface Email {
   expires_timestamp: number;
   /** The spam score as reported by SpamAssassin */
   spam_score?: number;
+  /** The headers of the email */
+  headers?: Record<string, string>;
+  /** The attachments of the email */
+  attachments?: EmailAttachment[];
 }
 
 export interface SearchInboxParams {
@@ -99,6 +116,17 @@ export interface SmtpSettings {
   };
 }
 
+export interface GetAttachmentResponse {
+  data: {
+    id: string;
+    filename: string;
+    content_type: string;
+    size: number;
+    expires_at: string | null;
+    download_url: string;
+  };
+}
+
 export interface ListNamespacesResponse {
   data: [
     {
@@ -123,4 +151,8 @@ export interface SendVirtualEmailParams {
   text?: string | undefined;
   /** The HTML version of the message */
   html?: string | undefined;
+  /** Custom headers for the email */
+  headers?: Record<string, string>;
+  /** Attachments to the email */
+  attachments?: Attachment[];
 }

package/src/mailisk.ts

@@ -1,5 +1,6 @@
-import axios, { AxiosRequestConfig } from "axios";
+import axios, { AxiosBasicCredentials, AxiosRequestConfig } from "axios";
 import {
+  GetAttachmentResponse,
   ListNamespacesResponse,
   SearchInboxParams,
   SearchInboxResponse,
@@ -9,12 +10,13 @@ import {
 import nodemailer from "nodemailer";
 
 export class MailiskClient {
-  constructor({ apiKey, baseUrl }: { apiKey: string; baseUrl?: string }) {
+  constructor({ apiKey, baseUrl, auth }: { apiKey: string; baseUrl?: string; auth?: AxiosBasicCredentials }) {
     this.axiosInstance = axios.create({
       headers: {
         "X-Api-Key": apiKey,
       },
       baseURL: baseUrl || "https://api.mailisk.com/",
+      auth,
     });
   }
 
@@ -46,8 +48,6 @@ export class MailiskClient {
   async sendVirtualEmail(namespace: string, params: SendVirtualEmailParams): Promise<void> {
     const smtpSettings = await this.getSmtpSettings(namespace);
 
-    // TODO: to should match namespace
-
     const transport = nodemailer.createTransport({
       host: smtpSettings.data.host,
       port: smtpSettings.data.port,
@@ -58,7 +58,7 @@ export class MailiskClient {
       },
     });
 
-    const { from, to, subject, text, html } = params;
+    const { from, to, subject, text, html, headers, attachments } = params;
 
     await transport.sendMail({
       from,
@@ -66,6 +66,8 @@ export class MailiskClient {
       subject,
       text,
       html,
+      headers,
+      attachments,
     });
 
     transport.close();
@@ -112,6 +114,10 @@ export class MailiskClient {
 
     let _config = { ...config };
 
+    if (!config?.maxRedirects) {
+      _config.maxRedirects = 99999;
+    }
+
     // by default, wait 5 minutes for emails before timing out
     if (_params.wait && !config?.timeout) {
       _config.timeout = 1000 * 60 * 5;
@@ -119,7 +125,7 @@ export class MailiskClient {
 
     return (
       await this.axiosInstance.get(`api/emails/${namespace}/inbox`, {
-        ...config,
+        ..._config,
         params: _params,
       })
     ).data;
@@ -132,4 +138,29 @@ export class MailiskClient {
     const result = await this.axiosInstance.get(`api/smtp/${namespace}`);
     return result.data;
   }
+
+  async getAttachment(attachmentId: string): Promise<GetAttachmentResponse> {
+    const result = await this.axiosInstance.get(`api/attachments/${attachmentId}`);
+    return result.data;
+  }
+
+  /**
+   * Download an attachment from an attachment ID.
+   *
+   * @example
+   * Download an attachment from an email
+   * ```typescript
+   * const attachment = email.attachments[0];
+   * const attachmentBuffer = await client.downloadAttachment(attachment.id);
+   *
+   * // save to file
+   * fs.writeFileSync(attachment.filename, attachmentBuffer);
+   * ```
+   */
+  async downloadAttachment(attachmentId: string): Promise<Buffer> {
+    const result = await this.getAttachment(attachmentId);
+
+    const response = await axios.get(result.data.download_url, { responseType: "arraybuffer" });
+    return Buffer.from(response.data);
+  }
 }

package/tests/mocks/axios-mocks.ts

@@ -0,0 +1,49 @@
+// Mock namespace response data
+export const mockNamespacesResponse = {
+  namespaces: [
+    {
+      name: "test-namespace",
+      created_at: new Date().toISOString(),
+      expires_at: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+    },
+  ],
+};
+
+// Mock email response data
+export const mockEmailsResponse = {
+  emails: [
+    {
+      id: "email-123",
+      from: { address: "sender@example.com", name: "Sender" },
+      to: [{ address: "recipient@test-namespace.mailisk.net", name: "Recipient" }],
+      subject: "Test Email",
+      html: "<p>Test content</p>",
+      text: "Test content",
+      received_date: new Date().toISOString(),
+      received_timestamp: Math.floor(Date.now() / 1000),
+      expires_timestamp: Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60,
+    },
+  ],
+  count: 1,
+};
+
+// Mock attachment response data
+export const mockAttachmentResponse = {
+  id: "attachment-123",
+  filename: "test.txt",
+  content_type: "text/plain",
+  size: 100,
+  expires_at: "Fri, 23 Jun 2025 02:29:13 GMT",
+  download_url: "https://example.com/attachment-123.txt",
+};
+
+// Mock SMTP settings response
+export const mockSmtpSettingsResponse = {
+  host: "smtp.mailisk.com",
+  port: 25,
+  secure: false,
+  auth: {
+    user: "test-namespace",
+    pass: "mock-password",
+  },
+};

package/tests/setup.ts

@@ -0,0 +1,21 @@
+import dotenv from "dotenv";
+import path from "path";
+
+dotenv.config({ path: path.resolve(process.cwd(), ".env.test") });
+
+jest.setTimeout(10000);
+
+process.env.TEST_MODE = "true";
+
+export const createTestClient = (mockResponses = {}) => {
+  const { MailiskClient } = require("../src/mailisk");
+
+  return new MailiskClient({
+    apiKey: "test-api-key",
+    baseUrl: "https://test-api.mailisk.com/",
+  });
+};
+
+afterEach(() => {
+  jest.resetAllMocks();
+});

package/tests/unit/mailisk.test.ts

@@ -0,0 +1,344 @@
+jest.mock("axios");
+jest.mock("nodemailer");
+
+import axios from "axios";
+import nodemailer from "nodemailer";
+import { MailiskClient } from "../../src/mailisk";
+import {
+  mockNamespacesResponse,
+  mockEmailsResponse,
+  mockSmtpSettingsResponse,
+  mockAttachmentResponse,
+} from "../mocks/axios-mocks";
+
+const setupMockAxios = () => {
+  jest.clearAllMocks();
+
+  const mockGet = jest.fn();
+  const mockPost = jest.fn();
+  const mockPut = jest.fn();
+  const mockDelete = jest.fn();
+
+  const mockInstance = {
+    get: mockGet,
+    post: mockPost,
+    put: mockPut,
+    delete: mockDelete,
+  };
+
+  (axios.create as jest.Mock).mockReturnValue(mockInstance);
+  (axios.get as jest.Mock).mockImplementation(jest.fn());
+
+  return {
+    mockInstance,
+    mockGet,
+    mockPost,
+    mockPut,
+    mockDelete,
+  };
+};
+
+describe("MailiskClient", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe("constructor", () => {
+    it("should initialize with default baseURL when not provided", () => {
+      setupMockAxios();
+      const client = new MailiskClient({ apiKey: "test-key" });
+      expect(axios.create).toHaveBeenCalledWith({
+        headers: {
+          "X-Api-Key": "test-key",
+        },
+        baseURL: "https://api.mailisk.com/",
+      });
+    });
+
+    it("should initialize with custom baseURL when provided", () => {
+      setupMockAxios();
+      const client = new MailiskClient({
+        apiKey: "test-key",
+        baseUrl: "https://custom-api.mailisk.com/",
+      });
+      expect(axios.create).toHaveBeenCalledWith({
+        headers: {
+          "X-Api-Key": "test-key",
+        },
+        baseURL: "https://custom-api.mailisk.com/",
+      });
+    });
+  });
+
+  describe("listNamespaces", () => {
+    it("should fetch and return namespaces", async () => {
+      const { mockGet } = setupMockAxios();
+      mockGet.mockResolvedValueOnce({ data: mockNamespacesResponse });
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+      const result = await client.listNamespaces();
+
+      expect(mockGet).toHaveBeenCalledWith("api/namespaces");
+      expect(result).toEqual(mockNamespacesResponse);
+    });
+
+    it("should handle errors correctly", async () => {
+      const { mockGet } = setupMockAxios();
+      const error = new Error("API Error");
+      mockGet.mockRejectedValueOnce(error);
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+
+      await expect(client.listNamespaces()).rejects.toThrow("API Error");
+    });
+  });
+
+  describe("getSmtpSettings", () => {
+    it("should fetch and return SMTP settings for a namespace", async () => {
+      const { mockGet } = setupMockAxios();
+      mockGet.mockResolvedValueOnce({ data: mockSmtpSettingsResponse });
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+      const result = await client.getSmtpSettings("test-namespace");
+
+      expect(mockGet).toHaveBeenCalledWith("api/smtp/test-namespace");
+      expect(result).toEqual(mockSmtpSettingsResponse);
+    });
+
+    it("should handle errors correctly", async () => {
+      const { mockGet } = setupMockAxios();
+      const error = new Error("SMTP Settings Error");
+      mockGet.mockRejectedValueOnce(error);
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+
+      await expect(client.getSmtpSettings("test-namespace")).rejects.toThrow("SMTP Settings Error");
+    });
+  });
+
+  describe("getAttachment", () => {
+    it("should fetch and return attachment data", async () => {
+      const { mockGet } = setupMockAxios();
+      mockGet.mockResolvedValueOnce({ data: mockAttachmentResponse });
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+      const result = await client.getAttachment("attachment-123");
+
+      expect(mockGet).toHaveBeenCalledWith("api/attachments/attachment-123");
+      expect(result).toEqual(mockAttachmentResponse);
+    });
+  });
+
+  describe("downloadAttachment", () => {
+    it("should download and return attachment data", async () => {
+      const getAttachmentSpy = jest.spyOn(MailiskClient.prototype, "getAttachment");
+      getAttachmentSpy.mockResolvedValueOnce({ data: mockAttachmentResponse });
+
+      const mockBuffer = Buffer.from("test content");
+      (axios.get as jest.Mock).mockResolvedValueOnce({ data: mockBuffer });
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+      const result = await client.downloadAttachment("attachment-123");
+
+      expect(axios.get).toHaveBeenCalledWith(mockAttachmentResponse.download_url, { responseType: "arraybuffer" });
+      expect(result).toEqual(mockBuffer);
+    });
+  });
+
+  describe("searchInbox", () => {
+    it("should fetch and return emails with default parameters", async () => {
+      const { mockGet } = setupMockAxios();
+      mockGet.mockResolvedValueOnce({ data: mockEmailsResponse });
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+      const result = await client.searchInbox("test-namespace");
+
+      expect(mockGet).toHaveBeenCalledWith("api/emails/test-namespace/inbox", {
+        maxRedirects: 99999,
+        timeout: 1000 * 60 * 5,
+        params: {
+          from_timestamp: expect.any(Number),
+          wait: true,
+        },
+      });
+      expect(result).toEqual(mockEmailsResponse);
+    });
+
+    it("should use custom parameters if provided", async () => {
+      const { mockGet } = setupMockAxios();
+      mockGet.mockResolvedValueOnce({ data: mockEmailsResponse });
+
+      const customParams = {
+        limit: 10,
+        offset: 5,
+        from_timestamp: 1234567890,
+        to_timestamp: 1234567899,
+        to_addr_prefix: "john",
+        from_addr_includes: "@example.com",
+        subject_includes: "test",
+        wait: false,
+      };
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+      const result = await client.searchInbox("test-namespace", customParams);
+
+      expect(mockGet).toHaveBeenCalledWith("api/emails/test-namespace/inbox", {
+        maxRedirects: 99999,
+        params: customParams,
+      });
+      expect(result).toEqual(mockEmailsResponse);
+    });
+
+    it("should use custom axios config if provided", async () => {
+      const { mockGet } = setupMockAxios();
+      mockGet.mockResolvedValueOnce({ data: mockEmailsResponse });
+
+      const customParams = {
+        wait: true,
+      };
+
+      const customConfig = {
+        timeout: 10000,
+        maxRedirects: 5,
+      };
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+      const result = await client.searchInbox("test-namespace", customParams, customConfig);
+
+      expect(mockGet).toHaveBeenCalledWith("api/emails/test-namespace/inbox", {
+        ...customConfig,
+        params: {
+          from_timestamp: expect.any(Number),
+          wait: true,
+        },
+      });
+      expect(result).toEqual(mockEmailsResponse);
+    });
+
+    it("should handle errors correctly", async () => {
+      const { mockGet } = setupMockAxios();
+      const error = new Error("Search Inbox Error");
+      mockGet.mockRejectedValueOnce(error);
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+
+      await expect(client.searchInbox("test-namespace")).rejects.toThrow("Search Inbox Error");
+    });
+  });
+
+  describe("sendVirtualEmail", () => {
+    // Setup for nodemailer mock
+    const mockSendMail = jest.fn();
+    const mockClose = jest.fn();
+    const mockTransport = {
+      sendMail: mockSendMail,
+      close: mockClose,
+    };
+
+    beforeEach(() => {
+      (nodemailer.createTransport as jest.Mock).mockReturnValue(mockTransport);
+      mockSendMail.mockReset().mockResolvedValue({});
+      mockClose.mockReset();
+    });
+
+    it("should send an email using nodemailer", async () => {
+      const { mockGet } = setupMockAxios();
+      mockGet.mockResolvedValueOnce({
+        data: {
+          data: {
+            host: "smtp.mailisk.com",
+            port: 25,
+            username: "test-namespace",
+            password: "mock-password",
+          },
+        },
+      });
+
+      const emailParams = {
+        from: "sender@example.com",
+        to: "recipient@test-namespace.mailisk.net",
+        subject: "Test Subject",
+        text: "Test Content",
+        html: "<p>Test HTML Content</p>",
+        headers: { "X-Custom-Header": "Custom Value" },
+      };
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+      await client.sendVirtualEmail("test-namespace", emailParams);
+
+      expect(mockGet).toHaveBeenCalledWith("api/smtp/test-namespace");
+
+      expect(nodemailer.createTransport).toHaveBeenCalledWith({
+        host: "smtp.mailisk.com",
+        port: 25,
+        secure: false,
+        auth: {
+          user: "test-namespace",
+          pass: "mock-password",
+        },
+      });
+
+      expect(mockSendMail).toHaveBeenCalledWith({
+        from: "sender@example.com",
+        to: "recipient@test-namespace.mailisk.net",
+        subject: "Test Subject",
+        text: "Test Content",
+        html: "<p>Test HTML Content</p>",
+        headers: { "X-Custom-Header": "Custom Value" },
+      });
+
+      expect(mockClose).toHaveBeenCalled();
+    });
+
+    it("should handle errors from SMTP settings fetch", async () => {
+      const { mockGet } = setupMockAxios();
+      const error = new Error("SMTP Settings Error");
+      mockGet.mockRejectedValueOnce(error);
+
+      const emailParams = {
+        from: "sender@example.com",
+        to: "recipient@test-namespace.mailisk.net",
+        subject: "Test Subject",
+        text: "Test Content",
+      };
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+
+      await expect(client.sendVirtualEmail("test-namespace", emailParams)).rejects.toThrow("SMTP Settings Error");
+
+      expect(nodemailer.createTransport).not.toHaveBeenCalled();
+    });
+
+    it("should handle errors from nodemailer sendMail", async () => {
+      const { mockGet } = setupMockAxios();
+      mockGet.mockResolvedValueOnce({
+        data: {
+          data: {
+            host: "smtp.mailisk.com",
+            port: 25,
+            username: "test-namespace",
+            password: "mock-password",
+          },
+        },
+      });
+
+      const sendMailError = new Error("Failed to send email");
+      mockSendMail.mockRejectedValueOnce(sendMailError);
+
+      const emailParams = {
+        from: "sender@example.com",
+        to: "recipient@test-namespace.mailisk.net",
+        subject: "Test Subject",
+        text: "Test Content",
+      };
+
+      const client = new MailiskClient({ apiKey: "test-key" });
+
+      await expect(client.sendVirtualEmail("test-namespace", emailParams)).rejects.toThrow("Failed to send email");
+
+      // In the actual implementation, if sendMail throws an error, close won't be called
+      // We just verify that sendMail was called
+      expect(mockSendMail).toHaveBeenCalled();
+    });
+  });
+});