@sendmailos/sdk 1.3.1 → 1.4.0

package/README.md

@@ -315,6 +315,53 @@ await platform.campaigns.send({
 
 **One verified domain = One workspace.** Simple.
 
+### Master API Keys
+
+Master API keys can access all workspaces in your organization with a single key. Ideal for SaaS platforms that need to manage multiple client workspaces programmatically.
+
+#### Recommended Flow for SaaS Platforms
+
+```typescript
+// Your platform backend - when a new client signs up
+const platform = new SendMailOS('sk_live_master_key');
+
+// 1. Create workspace first (with your client's data)
+const { workspace } = await platform.workspaces.create({
+  name: 'Pizza Palace',           // From your user's profile
+  industry: 'restaurants',        // Optional - can be null
+  website: 'https://pizzapalace.com'
+});
+
+// 2. Add domain TO that workspace
+const { dns_records } = await platform.domains.create({
+  domain: 'pizzapalace.com',
+  workspaceId: workspace.id       // Link to the workspace
+});
+
+// 3. Show DNS records to your user
+// They verify DNS, domain becomes active
+
+// 4. Now send emails using workspace_id or domain
+await platform.emails.send({
+  to: 'customer@example.com',
+  fromEmail: 'hello@pizzapalace.com',
+  subject: 'Welcome!',
+  html: '<h1>Welcome!</h1>',
+  workspaceId: workspace.id
+});
+```
+
+Your end users only see: **"Add domain → Verify DNS → Done"**
+
+Behind the scenes: Workspace created with proper settings → Domain linked → Ready to send.
+
+**Master Key vs Workspace Key:**
+| Feature | Master Key | Workspace Key |
+|---------|-----------|---------------|
+| Access | All workspaces | Single workspace |
+| workspaceId param | Required | Not needed |
+| Use case | Platform/SaaS backend | Per-client integrations |
+
 ## Agency Workspaces (Advanced)
 
 For more control, you can manually manage workspaces:

package/dist/index.d.mts

@@ -391,6 +391,41 @@ interface WorkflowStatusResponse {
         status: WorkflowStatus;
     };
 }
+interface Pixel$1 {
+    id: string;
+    name: string;
+    domain: string;
+    token: string;
+    active: boolean;
+    workspaceId?: string;
+    workspace?: {
+        id: string;
+        name: string;
+    };
+    createdAt: string;
+}
+interface CreatePixelRequest {
+    /** Pixel name (for identification) */
+    name: string;
+    /** Domain where the pixel will be installed */
+    domain: string;
+    /** Workspace ID (for agency accounts) - use this OR domain auto-detection */
+    workspace_id?: string;
+}
+interface CreatePixelResponse {
+    success: boolean;
+    pixel: Pixel$1;
+}
+interface ListPixelsRequest {
+    /** Filter by workspace ID (for agency accounts) */
+    workspace_id?: string;
+    /** Filter by domain (alternative to workspace_id) */
+    domain?: string;
+}
+interface ListPixelsResponse {
+    success: boolean;
+    pixels: Pixel$1[];
+}
 interface ApiError {
     success: false;
     error: string;
@@ -1215,6 +1250,55 @@ declare class WebhooksResource {
     }>;
 }
 
+/**
+ * Pixels resource for managing tracking pixels
+ */
+declare class PixelsResource {
+    private request;
+    constructor(request: <T>(endpoint: string, options?: RequestInit) => Promise<T>);
+    /**
+     * Create a new tracking pixel
+     * Returns a pixel with token for installation
+     *
+     * @example
+     * ```ts
+     * const { pixel } = await client.pixels.create({
+     *   name: 'Main Website',
+     *   domain: 'example.com'
+     * });
+     *
+     * console.log('Pixel token:', pixel.token);
+     * ```
+     */
+    create(params: CreatePixelRequest): Promise<CreatePixelResponse>;
+    /**
+     * List all pixels for the organization
+     *
+     * @example
+     * ```ts
+     * // List all pixels
+     * const { pixels } = await client.pixels.list();
+     *
+     * // List pixels for a specific domain (agency accounts)
+     * const { pixels } = await client.pixels.list({ domain: 'client.com' });
+     * ```
+     */
+    list(params?: ListPixelsRequest): Promise<ListPixelsResponse>;
+    /**
+     * Get a single pixel by ID
+     */
+    get(pixelId: string): Promise<{
+        success: boolean;
+        pixel: Pixel$1;
+    }>;
+    /**
+     * Delete a pixel
+     */
+    delete(pixelId: string): Promise<{
+        success: boolean;
+    }>;
+}
+
 /**
  * SendMailOS SDK Client
  *
@@ -1259,6 +1343,8 @@ declare class SendMailOS {
     readonly workflows: WorkflowsResource;
     /** Webhook management */
     readonly webhooks: WebhooksResource;
+    /** Tracking pixel management */
+    readonly pixels: PixelsResource;
     constructor(apiKey: string, options?: SendMailOSOptions);
     /**
      * Make an authenticated request to the API

package/dist/index.d.ts

@@ -391,6 +391,41 @@ interface WorkflowStatusResponse {
         status: WorkflowStatus;
     };
 }
+interface Pixel$1 {
+    id: string;
+    name: string;
+    domain: string;
+    token: string;
+    active: boolean;
+    workspaceId?: string;
+    workspace?: {
+        id: string;
+        name: string;
+    };
+    createdAt: string;
+}
+interface CreatePixelRequest {
+    /** Pixel name (for identification) */
+    name: string;
+    /** Domain where the pixel will be installed */
+    domain: string;
+    /** Workspace ID (for agency accounts) - use this OR domain auto-detection */
+    workspace_id?: string;
+}
+interface CreatePixelResponse {
+    success: boolean;
+    pixel: Pixel$1;
+}
+interface ListPixelsRequest {
+    /** Filter by workspace ID (for agency accounts) */
+    workspace_id?: string;
+    /** Filter by domain (alternative to workspace_id) */
+    domain?: string;
+}
+interface ListPixelsResponse {
+    success: boolean;
+    pixels: Pixel$1[];
+}
 interface ApiError {
     success: false;
     error: string;
@@ -1215,6 +1250,55 @@ declare class WebhooksResource {
     }>;
 }
 
+/**
+ * Pixels resource for managing tracking pixels
+ */
+declare class PixelsResource {
+    private request;
+    constructor(request: <T>(endpoint: string, options?: RequestInit) => Promise<T>);
+    /**
+     * Create a new tracking pixel
+     * Returns a pixel with token for installation
+     *
+     * @example
+     * ```ts
+     * const { pixel } = await client.pixels.create({
+     *   name: 'Main Website',
+     *   domain: 'example.com'
+     * });
+     *
+     * console.log('Pixel token:', pixel.token);
+     * ```
+     */
+    create(params: CreatePixelRequest): Promise<CreatePixelResponse>;
+    /**
+     * List all pixels for the organization
+     *
+     * @example
+     * ```ts
+     * // List all pixels
+     * const { pixels } = await client.pixels.list();
+     *
+     * // List pixels for a specific domain (agency accounts)
+     * const { pixels } = await client.pixels.list({ domain: 'client.com' });
+     * ```
+     */
+    list(params?: ListPixelsRequest): Promise<ListPixelsResponse>;
+    /**
+     * Get a single pixel by ID
+     */
+    get(pixelId: string): Promise<{
+        success: boolean;
+        pixel: Pixel$1;
+    }>;
+    /**
+     * Delete a pixel
+     */
+    delete(pixelId: string): Promise<{
+        success: boolean;
+    }>;
+}
+
 /**
  * SendMailOS SDK Client
  *
@@ -1259,6 +1343,8 @@ declare class SendMailOS {
     readonly workflows: WorkflowsResource;
     /** Webhook management */
     readonly webhooks: WebhooksResource;
+    /** Tracking pixel management */
+    readonly pixels: PixelsResource;
     constructor(apiKey: string, options?: SendMailOSOptions);
     /**
      * Make an authenticated request to the API

package/dist/index.js

@@ -1000,10 +1000,75 @@ var WebhooksResource = class {
   }
 };
 
+// src/resources/pixels.ts
+var PixelsResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Create a new tracking pixel
+   * Returns a pixel with token for installation
+   *
+   * @example
+   * ```ts
+   * const { pixel } = await client.pixels.create({
+   *   name: 'Main Website',
+   *   domain: 'example.com'
+   * });
+   *
+   * console.log('Pixel token:', pixel.token);
+   * ```
+   */
+  async create(params) {
+    return this.request("/pixels", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  /**
+   * List all pixels for the organization
+   *
+   * @example
+   * ```ts
+   * // List all pixels
+   * const { pixels } = await client.pixels.list();
+   *
+   * // List pixels for a specific domain (agency accounts)
+   * const { pixels } = await client.pixels.list({ domain: 'client.com' });
+   * ```
+   */
+  async list(params) {
+    const searchParams = new URLSearchParams();
+    if (params?.workspace_id) searchParams.set("workspace_id", params.workspace_id);
+    if (params?.domain) searchParams.set("domain", params.domain);
+    const query = searchParams.toString();
+    const endpoint = query ? `/pixels?${query}` : "/pixels";
+    return this.request(endpoint, {
+      method: "GET"
+    });
+  }
+  /**
+   * Get a single pixel by ID
+   */
+  async get(pixelId) {
+    return this.request(`/pixels/${pixelId}`, {
+      method: "GET"
+    });
+  }
+  /**
+   * Delete a pixel
+   */
+  async delete(pixelId) {
+    return this.request(`/pixels/${pixelId}`, {
+      method: "DELETE"
+    });
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://sendmailos.com/api/v1";
 var DEFAULT_TIMEOUT = 3e4;
-var SDK_VERSION = "1.3.1";
+var SDK_VERSION = "1.4.0";
 var SendMailOS = class {
   constructor(apiKey, options = {}) {
     if (!apiKey) {
@@ -1032,6 +1097,7 @@ var SendMailOS = class {
     this.workspaces = new WorkspacesResource(boundRequest);
     this.workflows = new WorkflowsResource(boundRequest);
     this.webhooks = new WebhooksResource(boundRequest);
+    this.pixels = new PixelsResource(boundRequest);
   }
   /**
    * Make an authenticated request to the API