@sendmailos/sdk 1.2.1 → 1.3.0

package/README.md

@@ -33,11 +33,13 @@ await client.emails.send({
 
 - **Type-safe**: Full TypeScript support with exported types
 - **Lightweight**: Zero dependencies for core SDK
+- **Attachments**: Send files via Base64 or URL (auto-fetched)
+- **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
@@ -72,6 +74,66 @@ await client.emails.sendTemplate({
 });
 ```
 
+### Attachments
+
+Send emails with file attachments (max 5 files, 7MB total).
+
+```typescript
+// With Base64 content
+await client.emails.send({
+  to: 'user@example.com',
+  subject: 'Invoice Attached',
+  html: '<p>Please find your invoice attached.</p>',
+  fromEmail: 'billing@company.com',
+  fromName: 'Billing',
+  attachments: [
+    {
+      filename: 'invoice.pdf',
+      content: 'JVBERi0xLjQK...', // Base64 encoded
+      contentType: 'application/pdf'
+    }
+  ]
+});
+
+// With URL (fetched automatically)
+await client.emails.send({
+  to: 'user@example.com',
+  subject: 'Your Report',
+  html: '<p>Here is your report.</p>',
+  fromEmail: 'reports@company.com',
+  attachments: [
+    {
+      filename: 'report.pdf',
+      url: 'https://cdn.example.com/reports/123.pdf',
+      contentType: 'application/pdf'
+    }
+  ]
+});
+
+// Inline images (using cid)
+await client.emails.send({
+  to: 'user@example.com',
+  subject: 'Check out our logo',
+  html: '<p>Our logo: <img src="cid:logo-image"></p>',
+  fromEmail: 'hello@company.com',
+  attachments: [
+    {
+      filename: 'logo.png',
+      url: 'https://cdn.example.com/logo.png',
+      contentType: 'image/png',
+      cid: 'logo-image'  // Reference in HTML with cid:logo-image
+    }
+  ]
+});
+```
+
+**Attachment Limits:**
+| Limit | Value |
+|-------|-------|
+| Max attachments | 5 |
+| Single file max | 5 MB |
+| Total size | 7 MB |
+
 ### Subscribers
 
 ```typescript
@@ -451,6 +513,63 @@ await platform.workflows.trigger(data.workflow.id, {
 });
 ```
 
+## 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.

package/dist/index.d.mts

@@ -9,6 +9,22 @@ interface SendMailOSOptions {
     /** Custom fetch implementation (for testing/Node.js polyfill) */
     fetch?: typeof fetch;
 }
+/**
+ * Email attachment configuration
+ * Provide either `content` (Base64) or `url` (fetched automatically)
+ */
+interface EmailAttachment {
+    /** Filename shown to recipient */
+    filename: string;
+    /** Base64-encoded file content (required if no url) */
+    content?: string;
+    /** URL to fetch attachment from (required if no content) */
+    url?: string;
+    /** MIME type (e.g., 'application/pdf', 'image/png') */
+    contentType: string;
+    /** Content-ID for inline images - reference in HTML with cid:your-id */
+    cid?: string;
+}
 interface SendEmailRequest {
     /** Recipient email address */
     to: string;
@@ -37,6 +53,11 @@ interface SendEmailRequest {
      * @note Agency accounts MUST specify either workspaceId or domain
      */
     domain?: string;
+    /**
+     * File attachments (max 5 files, 7MB total)
+     * Provide either Base64 content or URL for each attachment
+     */
+    attachments?: EmailAttachment[];
 }
 interface SendEmailResponse {
     success: boolean;
@@ -1418,4 +1439,4 @@ declare function constructWebhookEvent<T = unknown>(payload: string, headers: {
     timestamp: string;
 }, secret: string): T;
 
-export { type ApiError, AuthenticationError, type CreateDomainRequest, type CreateDomainResponse, type CreateSubscriberRequest, type CreateSubscriberResponse, type CreateWebhookRequest, type CreateWorkflowRequest, type CreateWorkflowResponse, type CreateWorkspaceRequest, type DnsRecord, type Domain, type GetWorkflowResponse, INDUSTRIES, type IdentifyTraits, type Industry, type ListDomainsResponse, type ListSubscribersRequest, type ListSubscribersResponse, type ListWorkflowsRequest, type ListWorkflowsResponse, NotFoundError, type OnboardClientRequest, type OnboardClientResponse, type Organization, type OrganizationType, Pixel, type PixelConfig, type PixelOptions, type ProvisionWorkspaceRequest, type ProvisionWorkspaceResponse, RateLimitError, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, SendMailOS, SendMailOSError, type SendMailOSOptions, SendmailPixel, type Subscriber, type TrackEventProperties, type TrackProps, type TriggerWorkflowRequest, type TriggerWorkflowResponse, type UpdateOrganizationRequest, type UpdateWorkflowRequest, type UpdateWorkflowResponse, type UpdateWorkspaceRequest, ValidationError, type VerifyWebhookParams, type Webhook, type WebhookEvent, type WebhookEventType, type Workflow, type WorkflowEdge, type WorkflowNode, type WorkflowStats, type WorkflowStatus, type WorkflowStatusResponse, type WorkflowTrigger, type WorkflowTriggerType, type Workspace, type WorkspaceStats, constructWebhookEvent, createGlobalPixel, SendMailOS as default, verifyWebhookSignature, verifyWebhookSignatureAsync };
+export { type ApiError, AuthenticationError, type CreateDomainRequest, type CreateDomainResponse, type CreateSubscriberRequest, type CreateSubscriberResponse, type CreateWebhookRequest, type CreateWorkflowRequest, type CreateWorkflowResponse, type CreateWorkspaceRequest, type DnsRecord, type Domain, type EmailAttachment, type GetWorkflowResponse, INDUSTRIES, type IdentifyTraits, type Industry, type ListDomainsResponse, type ListSubscribersRequest, type ListSubscribersResponse, type ListWorkflowsRequest, type ListWorkflowsResponse, NotFoundError, type OnboardClientRequest, type OnboardClientResponse, type Organization, type OrganizationType, Pixel, type PixelConfig, type PixelOptions, type ProvisionWorkspaceRequest, type ProvisionWorkspaceResponse, RateLimitError, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, SendMailOS, SendMailOSError, type SendMailOSOptions, SendmailPixel, type Subscriber, type TrackEventProperties, type TrackProps, type TriggerWorkflowRequest, type TriggerWorkflowResponse, type UpdateOrganizationRequest, type UpdateWorkflowRequest, type UpdateWorkflowResponse, type UpdateWorkspaceRequest, ValidationError, type VerifyWebhookParams, type Webhook, type WebhookEvent, type WebhookEventType, type Workflow, type WorkflowEdge, type WorkflowNode, type WorkflowStats, type WorkflowStatus, type WorkflowStatusResponse, type WorkflowTrigger, type WorkflowTriggerType, type Workspace, type WorkspaceStats, constructWebhookEvent, createGlobalPixel, SendMailOS as default, verifyWebhookSignature, verifyWebhookSignatureAsync };

package/dist/index.d.ts

@@ -9,6 +9,22 @@ interface SendMailOSOptions {
     /** Custom fetch implementation (for testing/Node.js polyfill) */
     fetch?: typeof fetch;
 }
+/**
+ * Email attachment configuration
+ * Provide either `content` (Base64) or `url` (fetched automatically)
+ */
+interface EmailAttachment {
+    /** Filename shown to recipient */
+    filename: string;
+    /** Base64-encoded file content (required if no url) */
+    content?: string;
+    /** URL to fetch attachment from (required if no content) */
+    url?: string;
+    /** MIME type (e.g., 'application/pdf', 'image/png') */
+    contentType: string;
+    /** Content-ID for inline images - reference in HTML with cid:your-id */
+    cid?: string;
+}
 interface SendEmailRequest {
     /** Recipient email address */
     to: string;
@@ -37,6 +53,11 @@ interface SendEmailRequest {
      * @note Agency accounts MUST specify either workspaceId or domain
      */
     domain?: string;
+    /**
+     * File attachments (max 5 files, 7MB total)
+     * Provide either Base64 content or URL for each attachment
+     */
+    attachments?: EmailAttachment[];
 }
 interface SendEmailResponse {
     success: boolean;
@@ -1418,4 +1439,4 @@ declare function constructWebhookEvent<T = unknown>(payload: string, headers: {
     timestamp: string;
 }, secret: string): T;
 
-export { type ApiError, AuthenticationError, type CreateDomainRequest, type CreateDomainResponse, type CreateSubscriberRequest, type CreateSubscriberResponse, type CreateWebhookRequest, type CreateWorkflowRequest, type CreateWorkflowResponse, type CreateWorkspaceRequest, type DnsRecord, type Domain, type GetWorkflowResponse, INDUSTRIES, type IdentifyTraits, type Industry, type ListDomainsResponse, type ListSubscribersRequest, type ListSubscribersResponse, type ListWorkflowsRequest, type ListWorkflowsResponse, NotFoundError, type OnboardClientRequest, type OnboardClientResponse, type Organization, type OrganizationType, Pixel, type PixelConfig, type PixelOptions, type ProvisionWorkspaceRequest, type ProvisionWorkspaceResponse, RateLimitError, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, SendMailOS, SendMailOSError, type SendMailOSOptions, SendmailPixel, type Subscriber, type TrackEventProperties, type TrackProps, type TriggerWorkflowRequest, type TriggerWorkflowResponse, type UpdateOrganizationRequest, type UpdateWorkflowRequest, type UpdateWorkflowResponse, type UpdateWorkspaceRequest, ValidationError, type VerifyWebhookParams, type Webhook, type WebhookEvent, type WebhookEventType, type Workflow, type WorkflowEdge, type WorkflowNode, type WorkflowStats, type WorkflowStatus, type WorkflowStatusResponse, type WorkflowTrigger, type WorkflowTriggerType, type Workspace, type WorkspaceStats, constructWebhookEvent, createGlobalPixel, SendMailOS as default, verifyWebhookSignature, verifyWebhookSignatureAsync };
+export { type ApiError, AuthenticationError, type CreateDomainRequest, type CreateDomainResponse, type CreateSubscriberRequest, type CreateSubscriberResponse, type CreateWebhookRequest, type CreateWorkflowRequest, type CreateWorkflowResponse, type CreateWorkspaceRequest, type DnsRecord, type Domain, type EmailAttachment, type GetWorkflowResponse, INDUSTRIES, type IdentifyTraits, type Industry, type ListDomainsResponse, type ListSubscribersRequest, type ListSubscribersResponse, type ListWorkflowsRequest, type ListWorkflowsResponse, NotFoundError, type OnboardClientRequest, type OnboardClientResponse, type Organization, type OrganizationType, Pixel, type PixelConfig, type PixelOptions, type ProvisionWorkspaceRequest, type ProvisionWorkspaceResponse, RateLimitError, type SendCampaignRequest, type SendCampaignResponse, type SendEmailRequest, type SendEmailResponse, SendMailOS, SendMailOSError, type SendMailOSOptions, SendmailPixel, type Subscriber, type TrackEventProperties, type TrackProps, type TriggerWorkflowRequest, type TriggerWorkflowResponse, type UpdateOrganizationRequest, type UpdateWorkflowRequest, type UpdateWorkflowResponse, type UpdateWorkspaceRequest, ValidationError, type VerifyWebhookParams, type Webhook, type WebhookEvent, type WebhookEventType, type Workflow, type WorkflowEdge, type WorkflowNode, type WorkflowStats, type WorkflowStatus, type WorkflowStatusResponse, type WorkflowTrigger, type WorkflowTriggerType, type Workspace, type WorkspaceStats, constructWebhookEvent, createGlobalPixel, SendMailOS as default, verifyWebhookSignature, verifyWebhookSignatureAsync };

package/dist/index.js

@@ -94,7 +94,8 @@ var EmailsResource = class {
         variables: params.variables,
         type: params.type || "transactional",
         workspace_id: params.workspaceId,
-        domain: params.domain
+        domain: params.domain,
+        attachments: params.attachments
       })
     });
   }