List transactional emails

Author: danrowden

README.md

@@ -98,6 +98,7 @@ You can use custom contact properties in API calls. Please make sure to [add cus
 - [getMailingLists()](#getmailinglists)
 - [sendEvent()](#sendevent)
 - [sendTransactionalEmail()](#sendtransactionalemail)
+- [getTransactionalEmails()](#gettransactionalemails)
 
 ---
 
@@ -666,8 +667,71 @@ HTTP 400 Bad Request
 
 ---
 
+### getTransactionalEmails()
+
+Get a list of published transactional emails.
+
+[API Reference](https://loops.so/docs/api-reference/list-transactional-emails)
+
+#### Parameters
+
+| Name      | Type    | Required | Notes                                                                                                                         |
+| --------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `perPage` | integer | No       | How many results to return per page. Must be between 10 and 50. Defaults to 20 if omitted.                                    |
+| `cursor`  | string  | No       | A cursor, to return a specific page of results. Cursors can be found from the `pagination.nextCursor` value in each response. |
+
+#### Example
+
+```javascript
+const resp = await loops.getTransactionalEmails();
+
+const resp = await loops.getTransactionalEmails({ perPage: 15 });
+```
+
+#### Response
+
+```json
+{
+  "pagination": {
+    "totalResults": 23,
+    "returnedResults": 20,
+    "perPage": 20,
+    "totalPages": 2,
+    "nextCursor": "clyo0q4wo01p59fsecyxqsh38",
+    "nextPage": "https://app.loops.so/api/v1/transactional?cursor=clyo0q4wo01p59fsecyxqsh38&perPage=20"
+  },
+  "data": [
+    {
+      "id": "clfn0k1yg001imo0fdeqg30i8",
+      "lastUpdated": "2023-11-06T17:48:07.249Z",
+      "dataVariables": []
+    },
+    {
+      "id": "cll42l54f20i1la0lfooe3z12",
+      "lastUpdated": "2025-02-02T02:56:28.845Z",
+      "dataVariables": [
+        "confirmationUrl"
+      ]
+    },
+    {
+      "id": "clw6rbuwp01rmeiyndm80155l",
+      "lastUpdated": "2024-05-14T19:02:52.000Z",
+      "dataVariables": [
+        "firstName",
+        "lastName",
+        "inviteLink"
+      ]
+    },
+    ...
+  ]
+}
+```
+
+---
+
 ## Version history
 
+- `v4.1.0` (Feb 27, 2025) - Support for new [List transactional emails](#gettransactionalemails) endpoint.
 - `v4.0.0` (Jan 16, 2025)
   - Added `APIError` to more easily understand API errors. [See usage example](#usage).
   - Added support for two new contact property endpoints: [List contact properties](#listcontactproperties) and [Create contact property](#createcontactproperty).

src/index.ts

@@ -147,6 +147,56 @@ interface MailingList {
   isPublic: boolean;
 }
 
+interface PaginationData {
+  /**
+   * Total results found.
+   */
+  totalResults: number;
+  /**
+   * The number of results returned in this response.
+   */
+  returnedResults: number;
+  /**
+   * The maximum number of results requested.
+   */
+  perPage: number;
+  /**
+   * Total number of pages.
+   */
+  totalPages: number;
+  /**
+   * The next cursor (for retrieving the next page of results using the `cursor` parameter), or `null` if there are no further pages.
+   */
+  nextCursor: string | null;
+  /**
+   * The URL of the next page of results, or `null` if there are no further pages.
+   */
+  nextPage: string | null;
+}
+
+interface TransactionalEmail {
+  /** The ID of the transactional email. */
+  id: string;
+  /**
+   * The name of the transactional email.
+   */
+  name: string;
+  /**
+   * The date the email was last updated in ECMA-262 date-time format.
+   * @see https://tc39.es/ecma262/multipage/numbers-and-dates.html#sec-date-time-string-format
+   */
+  lastUpdate: string;
+  /**
+   * Data variables in the transactional email.
+   */
+  dataVariables: string[];
+}
+
+interface ListTransactionalsResponse {
+  pagination: PaginationData;
+  data: TransactionalEmail[];
+}
+
 class RateLimitExceededError extends Error {
   limit: number;
   remaining: number;
@@ -508,6 +558,34 @@ class LoopsClient {
       payload,
     });
   }
+
+  /**
+   * List published transactional emails.
+   *
+   * @param {Object} params
+   * @param {number} [params.perPage] How many results to return in each request. Must be between 10 and 50. Defaults to 20.
+   * @param {string} [params.cursor] A cursor, to return a specific page of results. Cursors can be found from the `pagination.nextCursor` value in each response.
+   *
+   * @see https://loops.so/docs/api-reference/list-transactional-emails
+   *
+   * @returns {Object} List of transactional emails (JSON)
+   */
+  async getTransactionalEmails({
+    perPage,
+    cursor,
+  }: {
+    perPage?: number;
+    cursor?: string;
+  } = {}): Promise<ListTransactionalsResponse> {
+    let params: { perPage: string; cursor?: string } = {
+      perPage: (perPage || 20).toString(),
+    };
+    if (cursor) params["cursor"] = cursor;
+    return this._makeQuery({
+      path: "v1/transactional",
+      params,
+    });
+  }
 }
 
 export { LoopsClient, RateLimitExceededError, APIError };