@sendmailos/sdk 1.2.0 → 1.2.2

package/README.md

@@ -33,11 +33,12 @@ await client.emails.send({
 
 - **Type-safe**: Full TypeScript support with exported types
 - **Lightweight**: Zero dependencies for core SDK
+- **Email Automation**: Build workflows with triggers, delays, conditions, and actions
 - **Industry Templates**: 50+ pre-built templates for different industries
 - **Agency Workspaces**: Manage multiple clients from one account
 - **Pixel Tracking**: Track website visitors and link to email campaigns
+- **Webhooks**: Real-time event notifications with signature verification
 - **React Components**: Pre-built components and hooks
-- **Webhook Verification**: Secure signature verification utilities
 - **Error Handling**: Custom error classes for different scenarios
 
 ## API Reference
@@ -45,7 +46,7 @@ await client.emails.send({
 ### Emails
 
 ```typescript
-// Send transactional email
+// Send transactional email (Single Brand)
 await client.emails.send({
   to: 'user@example.com',
   subject: 'Hello!',
@@ -54,6 +55,16 @@ await client.emails.send({
   fromEmail: 'hello@acme.com',
 });
 
+// Send email (Multi-Brand / SaaS Platform)
+// Workspace auto-detected from fromEmail domain - no extra params needed!
+await platform.emails.send({
+  to: 'customer@example.com',
+  subject: 'Your order is ready!',
+  html: '<h1>Order Ready!</h1>',
+  fromName: 'Pizza Palace',
+  fromEmail: 'orders@pizzapalace.com',  // ← Workspace auto-detected
+});
+
 // Send with template
 await client.emails.sendTemplate({
   to: 'user@example.com',
@@ -65,24 +76,38 @@ await client.emails.sendTemplate({
 ### Subscribers
 
 ```typescript
-// Create subscriber
+// Create subscriber (Single Brand)
 const { subscriber } = await client.subscribers.create({
   email: 'user@example.com',
   firstName: 'John',
   tags: ['newsletter', 'premium']
 });
 
+// Create subscriber (Multi-Brand / SaaS Platform)
+const { subscriber } = await platform.subscribers.create({
+  email: 'customer@example.com',
+  firstName: 'Jane',
+  domain: 'pizzapalace.com',  // Required for multi-brand
+  tags: ['loyalty-member']
+});
+
 // List subscribers
 const { subscribers, total } = await client.subscribers.list({
   limit: 50,
   offset: 0
 });
+
+// List subscribers for a specific client (Multi-Brand)
+const { subscribers } = await platform.subscribers.list({
+  domain: 'pizzapalace.com',
+  limit: 50
+});
 ```
 
 ### Campaigns
 
 ```typescript
-// Send campaign
+// Send campaign (Single Brand)
 await client.campaigns.send({
   name: 'Weekly Newsletter',
   subject: 'What\'s new this week',
@@ -91,17 +116,39 @@ await client.campaigns.send({
   html: '<h1>Hello {{first_name}}!</h1>',
   tags: ['newsletter'] // Filter by subscriber tags
 });
+
+// Send campaign (Multi-Brand / SaaS Platform)
+// Workspace auto-detected from fromEmail domain
+await platform.campaigns.send({
+  name: 'Pizza Promo',
+  subject: 'New menu items!',
+  fromName: 'Pizza Palace',
+  fromEmail: 'promo@pizzapalace.com',  // ← Workspace auto-detected
+  html: '<h1>Check out our new items!</h1>',
+  sourceDomains: ['pizzapalace.com']   // Only send to subscribers from this domain
+});
 ```
 
 ### Domains
 
 ```typescript
-// Add sending domain
+// Add sending domain (Single Brand)
 const { domain } = await client.domains.create({
   domain: 'yourcompany.com'
 });
 
 console.log('DNS Records to add:', domain.dnsRecords);
+
+// Add client domain (Multi-Brand / SaaS Platform)
+// Show these DNS records to your client in your UI
+const { dns_records, domain_id } = await platform.domains.create({
+  domain: 'pizzapalace.com'
+});
+
+// After client verifies DNS:
+// ✓ Domain status becomes "verified"
+// ✓ Workspace is AUTO-CREATED for this domain
+// ✓ You can now send emails from @pizzapalace.com
 ```
 
 ## Organization & Industries
@@ -131,27 +178,97 @@ console.log(INDUSTRIES);
 
 Hotels, Restaurants, Gyms, Travel Agencies, Real Estate, Schools, E-commerce, Dentists, Car Dealerships, Events, Beauty Salons, Law Firms, Non-Profits, SaaS, Recruitment, Insurance, Online Courses, Municipalities, Personal Trainers, Influencers, Doctors/Clinics, Nightclubs, Coworking, Wedding Planners, Art Galleries, Car Rentals, Podcasters, Consultants, Bakeries, Veterinarians, Airbnb Hosts, Accountants, Developers, Musicians, Spas, Bookstores, Cleaning Services, Churches, Graphic Designers, Coffee Shops, Florists, Political Campaigns, Libraries, Taxis/Limos, Home Inspectors, Photographers, Universities, Fashion, Nutritionists, Startups
 
-## Agency Workspaces
+## Account Types
+
+### Single Brand (Business)
+
+For companies sending emails from their own domain. Simple setup, no workspaces needed.
+
+```typescript
+const client = new SendMailOS('sk_live_your_api_key');
+
+await client.emails.send({
+  to: 'customer@example.com',
+  fromEmail: 'hello@yourcompany.com',
+  subject: 'Welcome!',
+  html: '<h1>Hello!</h1>'
+});
+```
+
+### Multi-Brand / SaaS Platform
 
-Agencies can manage multiple clients from one account, each with isolated data.
+For agencies or SaaS platforms managing multiple clients. Each client gets their own workspace with isolated data.
+
+```typescript
+// Your platform's master API key
+const platform = new SendMailOS('sk_live_platform_key');
+
+// 1. Client signs up → Register their domain
+const { dns_records } = await platform.domains.create({
+  domain: 'pizzapalace.com'
+});
+// Show dns_records to client in your UI
+
+// 2. Domain verified → Workspace auto-created!
+//    (No manual workspace creation needed)
+
+// 3. Send emails → Workspace auto-detected from fromEmail
+await platform.emails.send({
+  to: 'customer@example.com',
+  fromEmail: 'orders@pizzapalace.com',  // ← Workspace detected automatically!
+  fromName: 'Pizza Palace',
+  subject: 'Your order is ready!',
+  html: '<h1>Order Ready!</h1>'
+});
+
+// 4. Add subscribers → Use domain param
+await platform.subscribers.create({
+  email: 'customer@example.com',
+  domain: 'pizzapalace.com'  // Required for multi-brand
+});
+
+// 5. List subscribers for a specific client
+const { subscribers } = await platform.subscribers.list({
+  domain: 'pizzapalace.com'
+});
+
+// 6. Send campaign → Workspace auto-detected
+await platform.campaigns.send({
+  subject: 'New Menu Items!',
+  fromName: 'Pizza Palace',
+  fromEmail: 'promo@pizzapalace.com',  // ← Auto-detected
+  html: '<h1>Check out our new menu!</h1>'
+});
+```
+
+### How Workspace Detection Works
+
+| Action | How workspace is identified |
+|--------|----------------------------|
+| Register domain | Creates domain record (pending) |
+| Domain verified | **Workspace auto-created** |
+| Send email | Auto-detect from `fromEmail` domain |
+| Send campaign | Auto-detect from `fromEmail` domain |
+| Add subscriber | From `domain` parameter |
+| List subscribers | From `domain` parameter |
+
+**One verified domain = One workspace.** Simple.
+
+## Agency Workspaces (Advanced)
+
+For more control, you can manually manage workspaces:
 
 ```typescript
 // Convert to agency account first
 await client.organization.convertToAgency();
 
-// Create client workspaces
+// Create client workspaces manually
 const pizzaPlace = await client.workspaces.create({
   name: 'Pizza Palace',
   industry: 'restaurants',
   import_templates: true  // Auto-import restaurant templates
 });
 
-const gym = await client.workspaces.create({
-  name: 'FitLife Gym',
-  industry: 'gyms',
-  import_templates: true
-});
-
 // List all clients
 const { workspaces } = await client.workspaces.list();
 for (const ws of workspaces) {
@@ -167,6 +284,231 @@ console.log(details.stats);
 await client.workspaces.inviteClient(pizzaPlace.id, 'owner@pizzapalace.com');
 ```
 
+## Workflows
+
+Automate email sequences with workflows. Create them via API, build the steps in your UI, then trigger them programmatically.
+
+### Workflow Lifecycle
+
+```
+1. Create workflow (draft)
+2. Add nodes & edges (build the flow)
+3. Activate workflow (start accepting triggers)
+4. Trigger for subscribers (via API or events)
+```
+
+### Create & Manage Workflows
+
+```typescript
+// Create a workflow for a client (Multi-Brand)
+const { data } = await platform.workflows.create({
+  name: 'Welcome Sequence',
+  domain: 'pizzapalace.com',  // Auto-detect workspace
+  trigger: { type: 'api' }    // Triggered via API
+});
+
+const workflowId = data.workflow.id;
+
+// List workflows
+const { data: list } = await platform.workflows.list({ domain: 'pizzapalace.com' });
+
+// Get workflow with nodes/edges
+const { data: workflow } = await platform.workflows.get(workflowId);
+
+// Delete workflow
+await platform.workflows.delete(workflowId);
+```
+
+### Build Workflow Steps
+
+Update a workflow with nodes (steps) and edges (connections):
+
+```typescript
+await platform.workflows.update(workflowId, {
+  nodes: [
+    {
+      id: 'trigger-1',
+      type: 'trigger',
+      data: { triggerType: 'api' }
+    },
+    {
+      id: 'email-1',
+      type: 'email',
+      data: {
+        subject: 'Welcome to {{restaurantName}}!',
+        templateId: 'tmpl_welcome'
+      }
+    },
+    {
+      id: 'delay-1',
+      type: 'delay',
+      data: { duration: 3, unit: 'days' }
+    },
+    {
+      id: 'email-2',
+      type: 'email',
+      data: {
+        subject: 'Your first order discount',
+        templateId: 'tmpl_promo'
+      }
+    }
+  ],
+  edges: [
+    { id: 'e1', source: 'trigger-1', target: 'email-1' },
+    { id: 'e2', source: 'email-1', target: 'delay-1' },
+    { id: 'e3', source: 'delay-1', target: 'email-2' }
+  ]
+});
+```
+
+### Node Types
+
+| Type | Description | Data Fields |
+|------|-------------|-------------|
+| `trigger` | Entry point | `triggerType` |
+| `email` | Send email | `subject`, `templateId`, `fromName`, `fromEmail` |
+| `delay` | Wait period | `duration`, `unit` (minutes/hours/days) |
+| `condition` | Branch logic | `field`, `operator`, `value` |
+| `tag` | Add/remove tags | `action` (add/remove), `tags` |
+| `http` | Call webhook | `url`, `method`, `headers`, `body` |
+| `wait_for_event` | Wait for event | `eventName`, `timeout` |
+| `unsubscribe` | Unsubscribe user | - |
+| `exit` | End workflow | - |
+
+### Activate & Pause
+
+```typescript
+// Activate workflow (start accepting triggers)
+await platform.workflows.activate(workflowId);
+
+// Pause workflow (stop new triggers, existing runs continue)
+await platform.workflows.pause(workflowId);
+```
+
+### Trigger Workflows
+
+```typescript
+// When a customer signs up at the restaurant
+await platform.workflows.trigger(workflowId, {
+  email: 'customer@example.com',
+  data: {
+    firstName: 'John',
+    restaurantName: 'Pizza Palace',
+    signupSource: 'website'
+  }
+});
+```
+
+### Wait for Events
+
+Workflows can pause and wait for specific events:
+
+```typescript
+// Workflow has a "wait_for_event: purchase_completed" node
+// When customer makes a purchase, send the event:
+await platform.workflows.sendEvent({
+  event: 'purchase_completed',
+  email: 'customer@example.com',
+  data: { orderTotal: 45.99 }
+});
+// The workflow resumes from where it was waiting
+```
+
+### Example: Restaurant Welcome Flow
+
+```typescript
+// 1. Create workflow
+const { data } = await platform.workflows.create({
+  name: 'New Customer Welcome',
+  domain: 'pizzapalace.com'
+});
+
+// 2. Build the flow
+await platform.workflows.update(data.workflow.id, {
+  nodes: [
+    { id: '1', type: 'trigger', data: { triggerType: 'api' } },
+    { id: '2', type: 'email', data: { subject: 'Welcome!', templateId: 'tmpl_welcome' } },
+    { id: '3', type: 'delay', data: { duration: 2, unit: 'days' } },
+    { id: '4', type: 'condition', data: { field: 'has_ordered', operator: 'eq', value: true } },
+    { id: '5', type: 'email', data: { subject: 'Thanks for ordering!', templateId: 'tmpl_thanks' } },
+    { id: '6', type: 'email', data: { subject: '10% off your first order', templateId: 'tmpl_promo' } }
+  ],
+  edges: [
+    { id: 'e1', source: '1', target: '2' },
+    { id: 'e2', source: '2', target: '3' },
+    { id: 'e3', source: '3', target: '4' },
+    { id: 'e4', source: '4', target: '5', sourceHandle: 'yes' },
+    { id: 'e5', source: '4', target: '6', sourceHandle: 'no' }
+  ]
+});
+
+// 3. Activate
+await platform.workflows.activate(data.workflow.id);
+
+// 4. Trigger when new customer signs up
+await platform.workflows.trigger(data.workflow.id, {
+  email: 'newcustomer@gmail.com',
+  data: { firstName: 'Jane', restaurantName: 'Pizza Palace' }
+});
+```
+
+## Webhooks
+
+Receive real-time notifications when events occur (emails sent, opened, clicked, bounced, etc.).
+
+### Create & Manage Webhooks
+
+```typescript
+// Create a webhook endpoint
+const { webhook } = await client.webhooks.create({
+  url: 'https://yourserver.com/webhooks',
+  events: ['email.sent', 'email.delivered', 'email.opened', 'email.clicked', 'email.bounced'],
+});
+
+console.log('Webhook secret:', webhook.secret); // Use this to verify signatures
+
+// List all webhooks
+const { webhooks } = await client.webhooks.list();
+
+// Get webhook with delivery history
+const { webhook, recentDeliveries, stats } = await client.webhooks.get('webhook-id');
+
+// Update webhook
+await client.webhooks.update('webhook-id', {
+  events: ['email.sent', 'email.bounced', 'email.complained']
+});
+
+// Test webhook endpoint
+const result = await client.webhooks.test('webhook-id');
+if (result.test.sent) {
+  console.log(`Test delivered in ${result.test.responseTimeMs}ms`);
+}
+
+// Disable/Enable webhook
+await client.webhooks.disable('webhook-id');
+await client.webhooks.enable('webhook-id');
+
+// Delete webhook
+await client.webhooks.delete('webhook-id');
+```
+
+### Event Types
+
+| Event | Description |
+|-------|-------------|
+| `email.sent` | Email was sent to the recipient |
+| `email.delivered` | Email was delivered to recipient's server |
+| `email.opened` | Recipient opened the email |
+| `email.clicked` | Recipient clicked a link in the email |
+| `email.bounced` | Email bounced (hard or soft) |
+| `email.complained` | Recipient marked email as spam |
+| `subscriber.created` | New subscriber was added |
+| `subscriber.updated` | Subscriber was updated |
+| `subscriber.unsubscribed` | Subscriber unsubscribed |
+| `campaign.sent` | Campaign finished sending |
+| `workflow.started` | Workflow execution started |
+| `workflow.completed` | Workflow execution completed |
+
 ## Pixel Tracking
 
 Track website visitors and connect their behavior to email campaigns.