@tratto/email 1.0.0 → 1.1.1

package/README.md

@@ -34,6 +34,22 @@ const { id } = await tratto.emails.send({
 console.log('Sent email:', id);
 ```
 
+Or write the email in [emailmd](https://www.emailmd.dev/) markdown — the API
+renders it into responsive, email-safe HTML (plus a text part) server-side:
+
+```ts
+await tratto.emails.send({
+  from: 'Acme <hello@mail.acme.com>',
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  markdown: '# Welcome, {{firstName}}\n\nGlad to have you on board.',
+});
+```
+
+`markdown` is mutually exclusive with `html`. Templates accept it too:
+`templates.create({ name, markdown })` creates a `format: 'emailmd'` template
+whose HTML is rendered and pinned at save time.
+
 ---
 
 ## Setup
@@ -265,6 +281,16 @@ await tratto.templates.testSend(tpl.id, 'me@example.com', { name: 'Alice' });
 await tratto.templates.delete(tpl.id);
 ```
 
+Templates created from `markdown` come back with `format: 'emailmd'`, the
+markdown in `source`, the rendered HTML in `html`, and — when part of the
+markdown could not be rendered — a `renderWarnings: string[]` array on the
+template object. The field is absent when there is nothing to report:
+
+```ts
+const tpl = await tratto.templates.create({ name: 'Welcome', markdown: '# Hi {{name}}' });
+if (tpl.renderWarnings?.length) console.warn(tpl.renderWarnings);
+```
+
 ---
 
 ### Webhooks
@@ -326,7 +352,9 @@ console.log('Open rate:', summary.openRate);
 const points = await tratto.analytics.getTimeseries('7d');
 ```
 
-Supported periods: `'7d'` | `'30d'` | `'90d'`. Results are cached server-side for 1 hour.
+Supported periods: `'7d'` | `'30d'` | `'90d'` | `'180d'` | `'1y'` (default `'30d'`).
+`'180d'` and `'1y'` read the long-term aggregate, which holds live data only:
+they are rejected for test-mode keys. Results are cached server-side for 1 hour.
 
 ---
 
@@ -418,8 +446,6 @@ import type {
   Template,
   Webhook,
   Domain,
-  ApiKey,
-  ApiKeyCreated,
   AnalyticsSummary,
   TimeseriesPoint,
   Flow,

package/dist/index.d.mts

@@ -32,6 +32,12 @@ interface SendEmailParams {
     to: string | string[];
     subject: string;
     html?: string;
+    /**
+     * emailmd markdown, rendered server-side into responsive email HTML
+     * (plus a text part). Mutually exclusive with `html` — the API rejects
+     * requests carrying both.
+     */
+    markdown?: string;
     text?: string;
     cc?: string[];
     bcc?: string[];
@@ -170,6 +176,14 @@ interface Campaign {
     sentAt: string | null;
     stats: CampaignStats;
     createdAt: string;
+    /**
+     * The editable markdown of an emailmd campaign (its own copy — editing it
+     * never touches the template). Returned by `get()` only: `list()` omits
+     * `source` and `renderWarnings` to keep the payload small.
+     */
+    source?: string;
+    /** Markdown that could not be rendered. Returned by `get()` only, absent when empty. */
+    renderWarnings?: string[];
 }
 interface CampaignStatsDetail {
     campaignId: string;
@@ -199,6 +213,7 @@ interface ListCampaignsParams {
 interface SendCampaignParams {
     scheduledAt?: Date | string;
 }
+type TemplateFormat = 'html' | 'emailmd';
 type TemplateStatus = 'draft' | 'published';
 interface TemplateSummary {
     id: string;
@@ -209,15 +224,29 @@ interface TemplateSummary {
     updatedAt: string;
 }
 interface Template extends TemplateSummary {
+    /** Always the pinned, ready-to-send HTML — for emailmd templates it is derived from `source`. */
     html: string;
+    /** 'html' for templates created before formats existed. Immutable after creation. */
+    format: TemplateFormat;
+    /** The markdown source of truth for emailmd templates. */
+    source?: string;
+    renderWarnings?: string[];
 }
 interface CreateTemplateParams {
     name: string;
     html?: string;
+    /**
+     * emailmd markdown source. Creates a `format: 'emailmd'` template whose
+     * HTML is rendered server-side at save time. Mutually exclusive with
+     * `html` — sending both (or `html` on an emailmd template) is rejected.
+     */
+    markdown?: string;
 }
 interface UpdateTemplateParams {
     name?: string;
     html?: string;
+    /** New markdown source for an emailmd template (re-rendered at save). */
+    markdown?: string;
     status?: TemplateStatus;
 }
 interface ListTemplatesParams {
@@ -285,7 +314,8 @@ interface ListDomainsParams {
     after?: string;
     limit?: number;
 }
-type AnalyticsPeriod = '7d' | '30d' | '90d';
+/** `'180d'` and `'1y'` read the long-term aggregate (live data only) and are rejected for test-mode keys. */
+type AnalyticsPeriod = '7d' | '30d' | '90d' | '180d' | '1y';
 interface AnalyticsSummary {
     period: AnalyticsPeriod;
     totalSent: number;
@@ -350,6 +380,20 @@ interface Workspace {
     timezone: string;
     locale: WorkspaceLocale;
     plan: WorkspacePlan;
+    /** Workspace default sender, used when a send does not specify one. */
+    defaultFromName: string | null;
+    defaultFromEmail: string | null;
+    /**
+     * Tenant-hosted unsubscribe/preference page. When set, {{unsubscribe_url}}
+     * resolves here instead of the Tratto-hosted page.
+     */
+    customUnsubscribeUrl: string | null;
+    /**
+     * Keep the "Sent using Tratto" branded footer on every HTML send even on a
+     * paid plan. On the free plan the branded footer is always applied
+     * regardless of this flag.
+     */
+    keepTrattoBranding: boolean;
     createdAt: string;
 }
 interface WorkspaceMember {
@@ -372,6 +416,16 @@ interface UpdateWorkspaceParams {
     slug?: string;
     timezone?: string;
     locale?: WorkspaceLocale;
+    defaultFromName?: string;
+    defaultFromEmail?: string;
+    /** Set to null to clear and fall back to the Tratto-hosted page. */
+    customUnsubscribeUrl?: string | null;
+    /**
+     * Opt in to keep the branded footer on paid plans. Accepted on any plan
+     * (no effect on free, where branding is mandatory) and never auto-reset
+     * by plan changes.
+     */
+    keepTrattoBranding?: boolean;
 }
 interface UpdateWorkspacePreferencesParams {
     locale?: WorkspaceLocale;

package/dist/index.d.ts

@@ -32,6 +32,12 @@ interface SendEmailParams {
     to: string | string[];
     subject: string;
     html?: string;
+    /**
+     * emailmd markdown, rendered server-side into responsive email HTML
+     * (plus a text part). Mutually exclusive with `html` — the API rejects
+     * requests carrying both.
+     */
+    markdown?: string;
     text?: string;
     cc?: string[];
     bcc?: string[];
@@ -170,6 +176,14 @@ interface Campaign {
     sentAt: string | null;
     stats: CampaignStats;
     createdAt: string;
+    /**
+     * The editable markdown of an emailmd campaign (its own copy — editing it
+     * never touches the template). Returned by `get()` only: `list()` omits
+     * `source` and `renderWarnings` to keep the payload small.
+     */
+    source?: string;
+    /** Markdown that could not be rendered. Returned by `get()` only, absent when empty. */
+    renderWarnings?: string[];
 }
 interface CampaignStatsDetail {
     campaignId: string;
@@ -199,6 +213,7 @@ interface ListCampaignsParams {
 interface SendCampaignParams {
     scheduledAt?: Date | string;
 }
+type TemplateFormat = 'html' | 'emailmd';
 type TemplateStatus = 'draft' | 'published';
 interface TemplateSummary {
     id: string;
@@ -209,15 +224,29 @@ interface TemplateSummary {
     updatedAt: string;
 }
 interface Template extends TemplateSummary {
+    /** Always the pinned, ready-to-send HTML — for emailmd templates it is derived from `source`. */
     html: string;
+    /** 'html' for templates created before formats existed. Immutable after creation. */
+    format: TemplateFormat;
+    /** The markdown source of truth for emailmd templates. */
+    source?: string;
+    renderWarnings?: string[];
 }
 interface CreateTemplateParams {
     name: string;
     html?: string;
+    /**
+     * emailmd markdown source. Creates a `format: 'emailmd'` template whose
+     * HTML is rendered server-side at save time. Mutually exclusive with
+     * `html` — sending both (or `html` on an emailmd template) is rejected.
+     */
+    markdown?: string;
 }
 interface UpdateTemplateParams {
     name?: string;
     html?: string;
+    /** New markdown source for an emailmd template (re-rendered at save). */
+    markdown?: string;
     status?: TemplateStatus;
 }
 interface ListTemplatesParams {
@@ -285,7 +314,8 @@ interface ListDomainsParams {
     after?: string;
     limit?: number;
 }
-type AnalyticsPeriod = '7d' | '30d' | '90d';
+/** `'180d'` and `'1y'` read the long-term aggregate (live data only) and are rejected for test-mode keys. */
+type AnalyticsPeriod = '7d' | '30d' | '90d' | '180d' | '1y';
 interface AnalyticsSummary {
     period: AnalyticsPeriod;
     totalSent: number;
@@ -350,6 +380,20 @@ interface Workspace {
     timezone: string;
     locale: WorkspaceLocale;
     plan: WorkspacePlan;
+    /** Workspace default sender, used when a send does not specify one. */
+    defaultFromName: string | null;
+    defaultFromEmail: string | null;
+    /**
+     * Tenant-hosted unsubscribe/preference page. When set, {{unsubscribe_url}}
+     * resolves here instead of the Tratto-hosted page.
+     */
+    customUnsubscribeUrl: string | null;
+    /**
+     * Keep the "Sent using Tratto" branded footer on every HTML send even on a
+     * paid plan. On the free plan the branded footer is always applied
+     * regardless of this flag.
+     */
+    keepTrattoBranding: boolean;
     createdAt: string;
 }
 interface WorkspaceMember {
@@ -372,6 +416,16 @@ interface UpdateWorkspaceParams {
     slug?: string;
     timezone?: string;
     locale?: WorkspaceLocale;
+    defaultFromName?: string;
+    defaultFromEmail?: string;
+    /** Set to null to clear and fall back to the Tratto-hosted page. */
+    customUnsubscribeUrl?: string | null;
+    /**
+     * Opt in to keep the branded footer on paid plans. Accepted on any plan
+     * (no effect on free, where branding is mandatory) and never auto-reset
+     * by plan changes.
+     */
+    keepTrattoBranding?: boolean;
 }
 interface UpdateWorkspacePreferencesParams {
     locale?: WorkspaceLocale;

package/dist/index.js

@@ -36,6 +36,9 @@ var TrattoError = class extends Error {
   }
 };
 
+// package.json
+var version = "1.1.1";
+
 // src/resources/base.ts
 var BaseResource = class {
   constructor(apiKey, baseUrl) {
@@ -47,7 +50,7 @@ var BaseResource = class {
     const contentType = options?.contentType ?? (hasBody ? "application/json" : void 0);
     const headers = {
       Authorization: `Bearer ${this.apiKey}`,
-      "User-Agent": "@tratto/email/0.1.0",
+      "User-Agent": `@tratto/email/${version}`,
       ...contentType ? { "Content-Type": contentType } : {},
       ...options?.headers
     };
@@ -212,7 +215,8 @@ var TemplatesResource = class extends BaseResource {
     return this.fetch("GET", `/v1/templates${qs}`);
   }
   create(params) {
-    return this.fetchData("POST", "/v1/templates", { body: params });
+    const body = params.markdown !== void 0 ? { ...params, format: "emailmd" } : params;
+    return this.fetchData("POST", "/v1/templates", { body });
   }
   get(id) {
     return this.fetchData("GET", `/v1/templates/${id}`);
@@ -226,8 +230,8 @@ var TemplatesResource = class extends BaseResource {
   listVersions(id) {
     return this.fetchData("GET", `/v1/templates/${id}/versions`);
   }
-  getVersion(id, version) {
-    return this.fetchData("GET", `/v1/templates/${id}/versions/${version}`);
+  getVersion(id, version2) {
+    return this.fetchData("GET", `/v1/templates/${id}/versions/${version2}`);
   }
   testSend(id, to, variables = {}) {
     return this.fetchData(

package/dist/index.mjs

@@ -9,6 +9,9 @@ var TrattoError = class extends Error {
   }
 };
 
+// package.json
+var version = "1.1.1";
+
 // src/resources/base.ts
 var BaseResource = class {
   constructor(apiKey, baseUrl) {
@@ -20,7 +23,7 @@ var BaseResource = class {
     const contentType = options?.contentType ?? (hasBody ? "application/json" : void 0);
     const headers = {
       Authorization: `Bearer ${this.apiKey}`,
-      "User-Agent": "@tratto/email/0.1.0",
+      "User-Agent": `@tratto/email/${version}`,
       ...contentType ? { "Content-Type": contentType } : {},
       ...options?.headers
     };
@@ -185,7 +188,8 @@ var TemplatesResource = class extends BaseResource {
     return this.fetch("GET", `/v1/templates${qs}`);
   }
   create(params) {
-    return this.fetchData("POST", "/v1/templates", { body: params });
+    const body = params.markdown !== void 0 ? { ...params, format: "emailmd" } : params;
+    return this.fetchData("POST", "/v1/templates", { body });
   }
   get(id) {
     return this.fetchData("GET", `/v1/templates/${id}`);
@@ -199,8 +203,8 @@ var TemplatesResource = class extends BaseResource {
   listVersions(id) {
     return this.fetchData("GET", `/v1/templates/${id}/versions`);
   }
-  getVersion(id, version) {
-    return this.fetchData("GET", `/v1/templates/${id}/versions/${version}`);
+  getVersion(id, version2) {
+    return this.fetchData("GET", `/v1/templates/${id}/versions/${version2}`);
   }
   testSend(id, to, variables = {}) {
     return this.fetchData(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tratto/email",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Tratto Node.js SDK \u2014 send transactional and marketing email",
   "author": "Tratto <hello@tratto.email>",
   "license": "MIT",