@tratto/email 1.1.1 → 1.2.0

package/README.md

@@ -252,9 +252,24 @@ await tratto.campaigns.send(id, { scheduledAt: new Date('2025-07-01T09:00:00Z')
 const stats = await tratto.campaigns.getStats(id);
 console.log(stats.rates.openRate);
 
+// Cancel a scheduled send: back to draft, scheduledAt cleared
+await tratto.campaigns.unschedule(id);
+
+// 409 if it cannot: the send already started, the campaign is in another
+// status, or it already sent a test wave to part of the list and is waiting
+// for the bounce rate. Those emails cannot be recalled, so pause it instead.
+
 // Pause
 await tratto.campaigns.pause(id);
 
+// Why a campaign is paused: 'quota_exceeded', 'schedule_missed',
+// 'bounce_rate' (it stopped itself on too many permanent bounces),
+// or null when it was paused by hand.
+const campaign = await tratto.campaigns.get(id);
+if (campaign.pausedReason === 'bounce_rate') {
+  console.log('Stopped: too many bounces. Clean the list before resuming.');
+}
+
 // Test send
 const { emailId } = await tratto.campaigns.testSend(id, 'me@example.com');
 ```
@@ -442,6 +457,7 @@ import type {
   Contact,
   Audience,
   Campaign,
+  CampaignPausedReason,
   CampaignStatsDetail,
   Template,
   Webhook,
@@ -462,14 +478,23 @@ See the [`examples/`](examples/) folder:
 
 | File | Description |
 |---|---|
-| [`send-email.ts`](examples/send-email.ts) | Send transactional emails (HTML, template, with idempotency) |
+| [`send-email.ts`](examples/send-email.ts) | Send transactional emails (HTML, template, with idempotency), read the timeline |
 | [`contacts.ts`](examples/contacts.ts) | Contact management and CSV bulk import |
-| [`campaign.ts`](examples/campaign.ts) | Create, configure, and send a marketing campaign |
+| [`audiences.ts`](examples/audiences.ts) | Rule-based audiences, adding contacts to one |
+| [`campaign.ts`](examples/campaign.ts) | Create, configure, send, unschedule and pause a marketing campaign |
+| [`templates.ts`](examples/templates.ts) | Template life cycle: create, edit, versions, test send, delete |
 | [`analytics.ts`](examples/analytics.ts) | Fetch delivery metrics and daily timeseries |
 | [`webhook.ts`](examples/webhook.ts) | Register a webhook and inspect delivery history |
+| [`domains.ts`](examples/domains.ts) | Add a sending domain, print its DNS records, verify it |
+| [`flows.ts`](examples/flows.ts) | Automation flows (needs an API key with the `*` permission) |
+| [`workspace.ts`](examples/workspace.ts) | Workspace settings, per-send-type senders, members |
 | [`nextjs.ts`](examples/nextjs.ts) | Next.js App Router route handler sending a welcome email |
 | [`express.ts`](examples/express.ts) | Express route sending a password-reset email |
 | [`fastify.ts`](examples/fastify.ts) | Fastify route sending an order-confirmation email via template |
+| [`smoke.ts`](examples/smoke.ts) | Runnable round-trip against a real API in test mode ([how to run](CONTRIBUTING.md#manual-smoke-test)) |
+
+Every example is type-checked and linted with the rest of the repo, so a
+renamed method breaks the build instead of a user's integration.
 
 Run any example with [tsx](https://github.com/privatenumber/tsx):
 
@@ -477,6 +502,9 @@ Run any example with [tsx](https://github.com/privatenumber/tsx):
 TRATTO_API_KEY=tratto_live_... npx tsx examples/send-email.ts
 ```
 
+The examples are written the way you would use the SDK, against real
+resources: read them before you run them.
+
 ---
 
 ## Contributing

package/dist/index.d.mts

@@ -154,6 +154,15 @@ interface AddContactsToAudienceResult {
     notFound: number;
 }
 type CampaignStatus = 'draft' | 'sending' | 'scheduled' | 'paused' | 'completed';
+/**
+ * Why a paused campaign is paused. `null` for a manual pause, or for a
+ * campaign that was never paused.
+ *
+ * - `quota_exceeded` — the dispatcher hit the monthly plan cap mid-send.
+ * - `schedule_missed` — the scheduled send window passed without dispatch.
+ * - `bounce_rate` — too many permanent bounces, the campaign stopped itself.
+ */
+type CampaignPausedReason = 'quota_exceeded' | 'schedule_missed' | 'bounce_rate';
 interface CampaignStats {
     total: number;
     sent: number;
@@ -166,6 +175,8 @@ interface Campaign {
     id: string;
     name: string;
     status: CampaignStatus;
+    /** Set whenever `status` is `paused`, `null` otherwise. */
+    pausedReason: CampaignPausedReason | null;
     templateId: string;
     audienceId: string;
     fromName: string;
@@ -373,6 +384,29 @@ interface ListFlowsParams {
 type WorkspacePlan = 'free' | 'starter' | 'growth';
 type WorkspaceMemberRole = 'owner' | 'admin' | 'member';
 type WorkspaceLocale = 'it' | 'en';
+type SendType = 'marketing' | 'automation' | 'transactional';
+/**
+ * Sender for one send type. `fromEmail` must be on a domain already verified
+ * for the workspace; `replyTo` is a response header, not the envelope sender,
+ * so it needs no verified domain.
+ */
+interface Sender {
+    fromEmail: string;
+    fromName: string;
+    replyTo?: string | null;
+}
+/**
+ * Default sender per send type (API >= 0.5.7).
+ *
+ * `null` on a type means it is not configured and **inherits** the
+ * workspace-wide `defaultFromEmail`/`defaultFromName` — it is never a reason
+ * for a send to be refused.
+ *
+ * Which type applies where: `marketing` for campaigns and template test sends,
+ * `automation` for the emails a flow sends (resolved when the flow is
+ * activated), `transactional` for API sends that carry no `from` of their own.
+ */
+type Senders = Record<SendType, Sender | null>;
 interface Workspace {
     id: string;
     name: string;
@@ -383,6 +417,11 @@ interface Workspace {
     /** Workspace default sender, used when a send does not specify one. */
     defaultFromName: string | null;
     defaultFromEmail: string | null;
+    /**
+     * Per-send-type senders. Optional: an API older than 0.5.7 does not send
+     * the field at all, so read it defensively rather than assuming three keys.
+     */
+    senders?: Partial<Senders>;
     /**
      * Tenant-hosted unsubscribe/preference page. When set, {{unsubscribe_url}}
      * resolves here instead of the Tratto-hosted page.
@@ -418,6 +457,13 @@ interface UpdateWorkspaceParams {
     locale?: WorkspaceLocale;
     defaultFromName?: string;
     defaultFromEmail?: string;
+    /**
+     * Partial write: sending only `marketing` leaves the other two untouched,
+     * and `{ marketing: null }` puts that type back to inheriting the
+     * workspace-wide default. Both halves of a sender travel together — a
+     * `fromEmail` without a `fromName` is refused.
+     */
+    senders?: Partial<Record<SendType, Sender | null>>;
     /** Set to null to clear and fall back to the Tratto-hosted page. */
     customUnsubscribeUrl?: string | null;
     /**
@@ -486,6 +532,21 @@ declare class CampaignsResource extends BaseResource {
     send(id: string, params?: SendCampaignParams): Promise<{
         status: string;
     }>;
+    /**
+     * Cancel a scheduled send: the campaign goes back to `draft` and its
+     * `scheduledAt` is cleared.
+     *
+     * Only a campaign still waiting for its date can be unscheduled. Anything
+     * else answers 409: a send already running, a campaign in any other status,
+     * or one that has already sent a test wave to part of its list and is
+     * waiting for the bounce rate before sending the rest. In those cases the
+     * emails already out cannot be recalled, so `pause()` is the way to stop it.
+     */
+    unschedule(id: string): Promise<{
+        id: string;
+        status: 'draft';
+        scheduledAt: null;
+    }>;
     pause(id: string): Promise<{
         status: string;
     }>;
@@ -580,4 +641,4 @@ declare class Tratto {
     constructor(apiKey: string, options?: TrattoOptions);
 }
 
-export { type AddContactsToAudienceResult, type AnalyticsPeriod, type AnalyticsSummary, type Audience, type AudienceRule, type AudienceRuleOperator, type Campaign, type CampaignStats, type CampaignStatsDetail, type CampaignStatus, type Contact, type ContactStatus, type CreateAudienceParams, type CreateCampaignParams, type CreateContactParams, type CreateFlowParams, type CreateTemplateParams, type CreateWebhookParams, type Domain, type DomainRecord, type DomainStatus, type DomainSummary, type EmailDetail, type EmailEvent, type EmailSummary, type Flow, type FlowStatus, type FlowStep, type FlowStepType, type FlowTrigger, type FlowTriggerType, type ImportJobStatus, type InviteMemberParams, type ListAudiencesParams, type ListCampaignsParams, type ListContactsParams, type ListDomainsParams, type ListEmailsParams, type ListFlowsParams, type ListTemplatesParams, type ListWebhookDeliveriesParams, type PaginatedResponse, type Pagination, type SendCampaignParams, type SendEmailParams, type Template, type TemplateStatus, type TemplateSummary, type TemplateVersion, type TemplateVersionSummary, type TimeseriesPoint, Tratto, TrattoError, type TrattoOptions, type UpdateContactParams, type UpdateFlowParams, type UpdateMemberParams, type UpdateTemplateParams, type UpdateWorkspaceParams, type UpdateWorkspacePreferencesParams, type Webhook, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEventType, type WebhookStatus, type Workspace, type WorkspaceLocale, type WorkspaceMember, type WorkspaceMemberRole, type WorkspacePlan, type WorkspacePreferences };
+export { type AddContactsToAudienceResult, type AnalyticsPeriod, type AnalyticsSummary, type Audience, type AudienceRule, type AudienceRuleOperator, type Campaign, type CampaignPausedReason, type CampaignStats, type CampaignStatsDetail, type CampaignStatus, type Contact, type ContactStatus, type CreateAudienceParams, type CreateCampaignParams, type CreateContactParams, type CreateFlowParams, type CreateTemplateParams, type CreateWebhookParams, type Domain, type DomainRecord, type DomainStatus, type DomainSummary, type EmailDetail, type EmailEvent, type EmailSummary, type Flow, type FlowStatus, type FlowStep, type FlowStepType, type FlowTrigger, type FlowTriggerType, type ImportJobStatus, type InviteMemberParams, type ListAudiencesParams, type ListCampaignsParams, type ListContactsParams, type ListDomainsParams, type ListEmailsParams, type ListFlowsParams, type ListTemplatesParams, type ListWebhookDeliveriesParams, type PaginatedResponse, type Pagination, type SendCampaignParams, type SendEmailParams, type SendType, type Sender, type Senders, type Template, type TemplateStatus, type TemplateSummary, type TemplateVersion, type TemplateVersionSummary, type TimeseriesPoint, Tratto, TrattoError, type TrattoOptions, type UpdateContactParams, type UpdateFlowParams, type UpdateMemberParams, type UpdateTemplateParams, type UpdateWorkspaceParams, type UpdateWorkspacePreferencesParams, type Webhook, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEventType, type WebhookStatus, type Workspace, type WorkspaceLocale, type WorkspaceMember, type WorkspaceMemberRole, type WorkspacePlan, type WorkspacePreferences };

package/dist/index.d.ts

@@ -154,6 +154,15 @@ interface AddContactsToAudienceResult {
     notFound: number;
 }
 type CampaignStatus = 'draft' | 'sending' | 'scheduled' | 'paused' | 'completed';
+/**
+ * Why a paused campaign is paused. `null` for a manual pause, or for a
+ * campaign that was never paused.
+ *
+ * - `quota_exceeded` — the dispatcher hit the monthly plan cap mid-send.
+ * - `schedule_missed` — the scheduled send window passed without dispatch.
+ * - `bounce_rate` — too many permanent bounces, the campaign stopped itself.
+ */
+type CampaignPausedReason = 'quota_exceeded' | 'schedule_missed' | 'bounce_rate';
 interface CampaignStats {
     total: number;
     sent: number;
@@ -166,6 +175,8 @@ interface Campaign {
     id: string;
     name: string;
     status: CampaignStatus;
+    /** Set whenever `status` is `paused`, `null` otherwise. */
+    pausedReason: CampaignPausedReason | null;
     templateId: string;
     audienceId: string;
     fromName: string;
@@ -373,6 +384,29 @@ interface ListFlowsParams {
 type WorkspacePlan = 'free' | 'starter' | 'growth';
 type WorkspaceMemberRole = 'owner' | 'admin' | 'member';
 type WorkspaceLocale = 'it' | 'en';
+type SendType = 'marketing' | 'automation' | 'transactional';
+/**
+ * Sender for one send type. `fromEmail` must be on a domain already verified
+ * for the workspace; `replyTo` is a response header, not the envelope sender,
+ * so it needs no verified domain.
+ */
+interface Sender {
+    fromEmail: string;
+    fromName: string;
+    replyTo?: string | null;
+}
+/**
+ * Default sender per send type (API >= 0.5.7).
+ *
+ * `null` on a type means it is not configured and **inherits** the
+ * workspace-wide `defaultFromEmail`/`defaultFromName` — it is never a reason
+ * for a send to be refused.
+ *
+ * Which type applies where: `marketing` for campaigns and template test sends,
+ * `automation` for the emails a flow sends (resolved when the flow is
+ * activated), `transactional` for API sends that carry no `from` of their own.
+ */
+type Senders = Record<SendType, Sender | null>;
 interface Workspace {
     id: string;
     name: string;
@@ -383,6 +417,11 @@ interface Workspace {
     /** Workspace default sender, used when a send does not specify one. */
     defaultFromName: string | null;
     defaultFromEmail: string | null;
+    /**
+     * Per-send-type senders. Optional: an API older than 0.5.7 does not send
+     * the field at all, so read it defensively rather than assuming three keys.
+     */
+    senders?: Partial<Senders>;
     /**
      * Tenant-hosted unsubscribe/preference page. When set, {{unsubscribe_url}}
      * resolves here instead of the Tratto-hosted page.
@@ -418,6 +457,13 @@ interface UpdateWorkspaceParams {
     locale?: WorkspaceLocale;
     defaultFromName?: string;
     defaultFromEmail?: string;
+    /**
+     * Partial write: sending only `marketing` leaves the other two untouched,
+     * and `{ marketing: null }` puts that type back to inheriting the
+     * workspace-wide default. Both halves of a sender travel together — a
+     * `fromEmail` without a `fromName` is refused.
+     */
+    senders?: Partial<Record<SendType, Sender | null>>;
     /** Set to null to clear and fall back to the Tratto-hosted page. */
     customUnsubscribeUrl?: string | null;
     /**
@@ -486,6 +532,21 @@ declare class CampaignsResource extends BaseResource {
     send(id: string, params?: SendCampaignParams): Promise<{
         status: string;
     }>;
+    /**
+     * Cancel a scheduled send: the campaign goes back to `draft` and its
+     * `scheduledAt` is cleared.
+     *
+     * Only a campaign still waiting for its date can be unscheduled. Anything
+     * else answers 409: a send already running, a campaign in any other status,
+     * or one that has already sent a test wave to part of its list and is
+     * waiting for the bounce rate before sending the rest. In those cases the
+     * emails already out cannot be recalled, so `pause()` is the way to stop it.
+     */
+    unschedule(id: string): Promise<{
+        id: string;
+        status: 'draft';
+        scheduledAt: null;
+    }>;
     pause(id: string): Promise<{
         status: string;
     }>;
@@ -580,4 +641,4 @@ declare class Tratto {
     constructor(apiKey: string, options?: TrattoOptions);
 }
 
-export { type AddContactsToAudienceResult, type AnalyticsPeriod, type AnalyticsSummary, type Audience, type AudienceRule, type AudienceRuleOperator, type Campaign, type CampaignStats, type CampaignStatsDetail, type CampaignStatus, type Contact, type ContactStatus, type CreateAudienceParams, type CreateCampaignParams, type CreateContactParams, type CreateFlowParams, type CreateTemplateParams, type CreateWebhookParams, type Domain, type DomainRecord, type DomainStatus, type DomainSummary, type EmailDetail, type EmailEvent, type EmailSummary, type Flow, type FlowStatus, type FlowStep, type FlowStepType, type FlowTrigger, type FlowTriggerType, type ImportJobStatus, type InviteMemberParams, type ListAudiencesParams, type ListCampaignsParams, type ListContactsParams, type ListDomainsParams, type ListEmailsParams, type ListFlowsParams, type ListTemplatesParams, type ListWebhookDeliveriesParams, type PaginatedResponse, type Pagination, type SendCampaignParams, type SendEmailParams, type Template, type TemplateStatus, type TemplateSummary, type TemplateVersion, type TemplateVersionSummary, type TimeseriesPoint, Tratto, TrattoError, type TrattoOptions, type UpdateContactParams, type UpdateFlowParams, type UpdateMemberParams, type UpdateTemplateParams, type UpdateWorkspaceParams, type UpdateWorkspacePreferencesParams, type Webhook, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEventType, type WebhookStatus, type Workspace, type WorkspaceLocale, type WorkspaceMember, type WorkspaceMemberRole, type WorkspacePlan, type WorkspacePreferences };
+export { type AddContactsToAudienceResult, type AnalyticsPeriod, type AnalyticsSummary, type Audience, type AudienceRule, type AudienceRuleOperator, type Campaign, type CampaignPausedReason, type CampaignStats, type CampaignStatsDetail, type CampaignStatus, type Contact, type ContactStatus, type CreateAudienceParams, type CreateCampaignParams, type CreateContactParams, type CreateFlowParams, type CreateTemplateParams, type CreateWebhookParams, type Domain, type DomainRecord, type DomainStatus, type DomainSummary, type EmailDetail, type EmailEvent, type EmailSummary, type Flow, type FlowStatus, type FlowStep, type FlowStepType, type FlowTrigger, type FlowTriggerType, type ImportJobStatus, type InviteMemberParams, type ListAudiencesParams, type ListCampaignsParams, type ListContactsParams, type ListDomainsParams, type ListEmailsParams, type ListFlowsParams, type ListTemplatesParams, type ListWebhookDeliveriesParams, type PaginatedResponse, type Pagination, type SendCampaignParams, type SendEmailParams, type SendType, type Sender, type Senders, type Template, type TemplateStatus, type TemplateSummary, type TemplateVersion, type TemplateVersionSummary, type TimeseriesPoint, Tratto, TrattoError, type TrattoOptions, type UpdateContactParams, type UpdateFlowParams, type UpdateMemberParams, type UpdateTemplateParams, type UpdateWorkspaceParams, type UpdateWorkspacePreferencesParams, type Webhook, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEventType, type WebhookStatus, type Workspace, type WorkspaceLocale, type WorkspaceMember, type WorkspaceMemberRole, type WorkspacePlan, type WorkspacePreferences };

package/dist/index.js

@@ -37,7 +37,7 @@ var TrattoError = class extends Error {
 };
 
 // package.json
-var version = "1.1.1";
+var version = "1.2.0";
 
 // src/resources/base.ts
 var BaseResource = class {
@@ -192,6 +192,23 @@ var CampaignsResource = class extends BaseResource {
     }
     return this.fetchData("POST", `/v1/campaigns/${id}/send`, { body });
   }
+  /**
+   * Cancel a scheduled send: the campaign goes back to `draft` and its
+   * `scheduledAt` is cleared.
+   *
+   * Only a campaign still waiting for its date can be unscheduled. Anything
+   * else answers 409: a send already running, a campaign in any other status,
+   * or one that has already sent a test wave to part of its list and is
+   * waiting for the bounce rate before sending the rest. In those cases the
+   * emails already out cannot be recalled, so `pause()` is the way to stop it.
+   */
+  unschedule(id) {
+    return this.fetchData(
+      "POST",
+      `/v1/campaigns/${id}/unschedule`,
+      { body: {} }
+    );
+  }
   pause(id) {
     return this.fetchData("POST", `/v1/campaigns/${id}/pause`, { body: {} });
   }

package/dist/index.mjs

@@ -10,7 +10,7 @@ var TrattoError = class extends Error {
 };
 
 // package.json
-var version = "1.1.1";
+var version = "1.2.0";
 
 // src/resources/base.ts
 var BaseResource = class {
@@ -165,6 +165,23 @@ var CampaignsResource = class extends BaseResource {
     }
     return this.fetchData("POST", `/v1/campaigns/${id}/send`, { body });
   }
+  /**
+   * Cancel a scheduled send: the campaign goes back to `draft` and its
+   * `scheduledAt` is cleared.
+   *
+   * Only a campaign still waiting for its date can be unscheduled. Anything
+   * else answers 409: a send already running, a campaign in any other status,
+   * or one that has already sent a test wave to part of its list and is
+   * waiting for the bounce rate before sending the rest. In those cases the
+   * emails already out cannot be recalled, so `pause()` is the way to stop it.
+   */
+  unschedule(id) {
+    return this.fetchData(
+      "POST",
+      `/v1/campaigns/${id}/unschedule`,
+      { body: {} }
+    );
+  }
   pause(id) {
     return this.fetchData("POST", `/v1/campaigns/${id}/pause`, { body: {} });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tratto/email",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Tratto Node.js SDK \u2014 send transactional and marketing email",
   "author": "Tratto <hello@tratto.email>",
   "license": "MIT",
@@ -29,7 +29,7 @@
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "lint": "eslint src --ext .ts",
+    "lint": "eslint src examples --ext .ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -49,5 +49,8 @@
   },
   "engines": {
     "node": ">=18"
+  },
+  "volta": {
+    "node": "24.21.0"
   }
 }