migma 1.3.2 → 1.3.3

package/README.md

@@ -36,7 +36,7 @@ const { data: email } = await migma.emails.generateAndWait({
 if (email?.status === 'completed') {
   console.log('Subject:', email.result.subject);
   console.log('HTML:', email.result.html); // primary email HTML
-  console.log('Artifact:', email.result.emails[0].artifactId);
+  console.log('Email ID:', email.result.emails[0].emailId);
 }
 ```
 
@@ -66,20 +66,20 @@ const { data: email } = await migma.emails.generateAndWait({
 
 if (!email?.result) throw new Error('Email generation failed');
 
-// 3. Send it — artifactId works for single emails and series slots
+// 3. Send it — emailId works for single emails and series slots
 const selectedEmail = email.result.emails[0];
-if (!selectedEmail.artifactId) throw new Error('No artifactId returned');
+if (!selectedEmail.emailId) throw new Error('No emailId returned');
 await migma.sending.send({
   recipientType: 'email',
   recipientEmail: 'sarah@example.com',
   from: 'hello@yourcompany.migma.email',
   fromName: 'Your Company',
   subject: selectedEmail.subject,
-  artifactId: selectedEmail.artifactId,
+  emailId: selectedEmail.emailId,
 });
 
 // conversationId also works for single-email conversations.
-// For multi-slot emails or series, use result.emails[].artifactId.
+// For multi-slot emails or series, use result.emails[].emailId.
 ```
 
 [Full OpenClaw tutorial](https://docs.migma.ai/tutorials/send-emails-from-openclaw)
@@ -228,14 +228,14 @@ const { data: result } = await migma.contacts.bulkImport({
 Send to a single recipient, segment, tag, or full audience.
 
 ```typescript
-// Send a generated email by artifactId
+// Send a generated email by emailId
 await migma.sending.send({
   recipientType: 'email',
   recipientEmail: 'user@example.com',
   from: 'hello@yourdomain.com',
   fromName: 'Your Company',
   subject: 'Welcome!',
-  artifactId: 'artifact_abc123',
+  emailId: 'email_abc123',
 });
 
 // Single-email conversations can also be sent by conversationId.
@@ -255,7 +255,7 @@ await migma.sending.send({
   from: 'hello@yourdomain.com',
   fromName: 'Your Company',
   subject: 'Big Announcement',
-  artifactId: 'artifact_abc123',
+  emailId: 'email_abc123',
 });
 
 // Single sends are automatically transactional — no flag needed
@@ -266,7 +266,7 @@ await migma.sending.send({
   from: 'noreply@yourdomain.com',
   fromName: 'Your Company',
   subject: 'Your subscription renews tomorrow',
-  artifactId: 'artifact_abc123',
+  emailId: 'email_abc123',
   transactional: true,
 });
 ```
@@ -275,7 +275,7 @@ await migma.sending.send({
 
 ### Generated Series and Editing
 
-Generate a series with `count`, then use each email's `artifactId` to fetch, compile, update, or send one slot.
+Generate a series with `count`, then use each email's `emailId` to fetch, prompt-edit, or send one email.
 
 ```typescript
 const { data: series } = await migma.emails.generateAndWait({
@@ -285,18 +285,15 @@ const { data: series } = await migma.emails.generateAndWait({
 });
 
 for (const generated of series?.result?.emails ?? []) {
-  console.log(generated.slot, generated.artifactId, generated.html);
+  console.log(generated.slot, generated.emailId, generated.html);
+  console.log(generated.screenshotUrl);
 }
 
-const { data: email } = await migma.emails.get('artifact_abc123');
-if (!email?.source) throw new Error('Editable source unavailable');
+const { data: email } = await migma.emails.get('email_abc123');
+console.log(email?.html);
 
-await migma.emails.compile('artifact_abc123', {
-  source: email.source.replace('Start now', 'Start your trial'),
-});
-
-await migma.emails.update('artifact_abc123', {
-  source: email.source.replace('Start now', 'Start your trial'),
+await migma.emails.edit('email_abc123', {
+  prompt: 'Change the CTA from "Start now" to "Start your trial"',
 });
 ```
 
@@ -457,8 +454,9 @@ await migma.images.updateLogos('proj_abc123', {
 | `migma.segments` | `create` `list` `get` `update` `remove` | [Segments](https://docs.migma.ai/api-reference/audiences/list-audiences) |
 | `migma.topics` | `create` `list` `get` `update` `remove` `subscribe` `unsubscribe` | [Topics](https://docs.migma.ai/api-reference/topics/list-topics) |
 | `migma.sending` | `send` `getBatchStatus` | [Sending](https://docs.migma.ai/api-reference/sending/send-email) |
-| `migma.projects` | `list` `get` `import` `getImportStatus` `retryImport` `importAndWait` | [Projects](https://docs.migma.ai/api-reference/projects/list-projects) |
-| `migma.emails` | `generate` `getGenerationStatus` `generateAndWait` `sendTest` | [Email Generation](https://docs.migma.ai/api-reference/email/generate-email-async) |
+| `migma.projects` | `list` `get` `import` `getImportStatus` `retryImport` `fieldCatalog` `importAndWait` | [Projects](https://docs.migma.ai/api-reference/projects/list-projects) |
+| `migma.emails` | `generate` `getGenerationStatus` `generateAndWait` `sendTest` `get` `edit` | [Email Generation](https://docs.migma.ai/api-reference/email/generate-email-async) |
+| `migma.campaigns` | `list` `create` `get` `send` `schedule` `cancel` `archive` `unarchive` | [Campaigns](https://docs.migma.ai/campaigns/overview) |
 | `migma.validation` | `all` `compatibility` `links` `spelling` `deliverability` | [Validation](https://docs.migma.ai/api-reference/email-validation/run-all-validation-checks) |
 | `migma.previews` | `create` `get` `getStatus` `getDevice` `getSupportedDevices` `createAndWait` | [Previews](https://docs.migma.ai/api-reference/email-previews/create-email-preview) |
 | `migma.export` | `getFormats` `getStatus` `html` `mjml` `pdf` `klaviyo` `mailchimp` `hubspot` | [Export](https://docs.migma.ai/api-reference/export/list-export-formats) |

package/dist/index.d.mts

@@ -64,6 +64,7 @@ interface RequestOptions {
 declare class MigmaClient {
     private readonly apiKey;
     private readonly config;
+    private readonly headers;
     constructor(apiKey: string, config: ClientConfig);
     request<T>(options: RequestOptions): Promise<MigmaResult<T>>;
     /**
@@ -94,6 +95,7 @@ interface Contact {
     email: string;
     firstName?: string;
     lastName?: string;
+    phone?: string;
     country?: string;
     language?: string;
     tags: string[];
@@ -107,6 +109,7 @@ interface CreateContactParams {
     email: string;
     firstName?: string;
     lastName?: string;
+    phone?: string;
     /** ISO 3166-1 alpha-2 country code (e.g., US, CA, GB) */
     country?: string;
     /** Language code in ISO 639-1 or BCP 47 format (e.g., en, en-US) */
@@ -118,6 +121,7 @@ interface CreateContactParams {
 interface UpdateContactParams {
     firstName?: string;
     lastName?: string;
+    phone?: string | null;
     country?: string;
     language?: string;
     tags?: string[];
@@ -141,6 +145,7 @@ interface BulkImportContactItem {
     email: string;
     firstName?: string;
     lastName?: string;
+    phone?: string;
     country?: string;
     language?: string;
     tags?: string[];
@@ -241,10 +246,28 @@ declare class Tags {
     remove(id: string, projectId: string): Promise<MigmaResult<DeleteResponse>>;
 }
 
+interface SegmentFieldFilter {
+    key: string;
+    mode?: 'is' | 'is_not';
+    values: string[];
+}
+interface SegmentActivityFilter {
+    action: 'sent' | 'opened' | 'clicked';
+    mode: 'within' | 'before' | 'never' | 'between';
+    unit?: 'hours' | 'days';
+    amount?: number;
+    from?: string | Date;
+    to?: string | Date;
+    campaignId?: string;
+}
 interface SegmentFilters {
     tags?: string[];
+    excludeTags?: string[];
     status?: 'subscribed' | 'unsubscribed' | 'non-subscribed' | 'bounced';
+    validationStatus?: 'valid' | 'invalid' | 'risky' | 'unknown';
     customFields?: Record<string, string[]>;
+    fields?: SegmentFieldFilter[];
+    activity?: SegmentActivityFilter[];
 }
 interface Segment {
     id: string;
@@ -352,21 +375,19 @@ interface SendEmailParams {
     replyTo?: string;
     bcc?: string[];
     subject: string;
-    /** Email template source. Required unless conversationId or artifactId is provided. */
-    template?: string;
     variables?: Record<string, unknown>;
     providerType?: ProviderType;
-    /** Required unless conversationId or artifactId is provided. */
+    /** Optional when emailId or conversationId can resolve project automatically. */
     projectId?: string;
     /**
-     * Slot-precise email artifact id. Use this for a selected email inside a
-     * multi-slot conversation or series. Resolves template, projectId, and parent
-     * conversation automatically.
+     * Generated email id from result.emails[].emailId. Use this for selected
+     * emails inside multi-slot conversations or series. Resolves template,
+     * projectId, and parent conversation automatically.
      */
-    artifactId?: string;
+    emailId?: string;
     /**
      * Conversation id. Works for single-email conversations. For multi-slot
-     * conversations, also provide artifactId so API knows which email to send.
+     * conversations, use emailId so API knows which email to send.
      */
     conversationId?: string;
     /** Defaults to true for single sends, false for batch sends. Set explicitly to override. Transactional emails bypass subscription status and topic filters, and omit List-Unsubscribe headers. */
@@ -476,6 +497,24 @@ interface RetryImportResponse {
     status: string;
     message: string;
 }
+interface FieldCatalogParams {
+    segmentId?: string;
+    tag?: string;
+}
+type FieldCatalogEntryType = 'string' | 'number' | 'boolean' | 'date' | 'url' | 'unknown';
+interface FieldCatalogEntry {
+    key: string;
+    label: string;
+    type: FieldCatalogEntryType;
+    fillRate: number;
+    sample: string[];
+    auto: boolean;
+}
+interface FieldCatalogResponse {
+    entries: FieldCatalogEntry[];
+    totalSubscribers: number;
+    computedAt: string;
+}
 
 interface PollingOptions {
     /** Polling interval in ms. Default: 2000 */
@@ -502,6 +541,7 @@ declare class Projects {
     import(params: ImportProjectParams): Promise<MigmaResult<ImportProjectResponse>>;
     getImportStatus(projectId: string): Promise<MigmaResult<ImportStatusResponse>>;
     retryImport(projectId: string): Promise<MigmaResult<RetryImportResponse>>;
+    fieldCatalog(projectId: string, params?: FieldCatalogParams): Promise<MigmaResult<FieldCatalogResponse>>;
     /**
      * Import a project and wait for completion.
      * Polls getImportStatus until status is 'active' or 'error'.
@@ -539,8 +579,7 @@ interface EmailGenerationResult {
     subject: string;
     previewText: string;
     html: string;
-    source?: string;
-    emails: GeneratedEmailArtifact[];
+    emails: GeneratedEmail[];
     seriesPlan?: {
         name?: string;
         count?: number;
@@ -555,10 +594,10 @@ interface EmailGenerationResult {
         colors: string[];
     };
     languages: string[];
-    templateVariables?: unknown[];
 }
-interface GeneratedEmailArtifact {
-    artifactId: string | null;
+interface GeneratedEmail {
+    id: string | null;
+    emailId: string | null;
     conversationId: string;
     messageId: string | null;
     slotIdx: number;
@@ -566,11 +605,10 @@ interface GeneratedEmailArtifact {
     subject: string;
     preheader: string;
     html: string;
-    source?: string;
     sendOffsetDays?: number;
     status: 'ready' | 'processing' | 'failed';
+    screenshotUrl?: string | null;
     thumbnailUrl?: string | null;
-    templateVariables?: unknown[];
 }
 interface EmailGenerationStatus {
     conversationId: string;
@@ -607,50 +645,38 @@ interface ListEmailsResponse {
     };
 }
 interface SendTestEmailParams {
-    conversationId: string;
+    emailId?: string;
+    conversationId?: string;
     to: string;
 }
 interface SendTestEmailResponse {
     messageId: string;
+    emailId?: string;
     conversationId: string;
     sentTo: string;
     sentAt: string;
     subject: string;
 }
-interface EmailArtifact {
-    artifactId: string;
+interface Email {
+    id: string;
+    emailId: string;
     conversationId: string;
     messageId: string | null;
     slotIdx: number;
     slotUuid: string | null;
     status: string;
-    engine: 'zinn' | 'react-email';
     subject: string;
     preheader: string;
     html: string;
-    source?: string;
-    templateVariables: unknown[];
+    screenshotUrl: string | null;
     warnings: string[];
     thumbnailUrl: string | null;
     updatedAt: string;
 }
-interface UpdateEmailArtifactParams {
-    source: string;
-    vars?: Record<string, unknown>;
-    lang?: string;
+interface EditEmailParams {
+    prompt: string;
     label?: string;
 }
-interface CompileEmailArtifactParams {
-    source?: string;
-    vars?: Record<string, unknown>;
-    lang?: string;
-}
-interface CompileEmailArtifactResponse {
-    artifactId: string;
-    html: string;
-    warnings: string[];
-    metadata?: Record<string, unknown>;
-}
 
 declare class Emails {
     private readonly client;
@@ -661,12 +687,10 @@ declare class Emails {
     generate(params: GenerateEmailParams): Promise<MigmaResult<GenerateEmailResponse>>;
     /** Check email generation status */
     getGenerationStatus(conversationId: string): Promise<MigmaResult<EmailGenerationStatus>>;
-    /** Fetch one generated email by artifact id */
-    get(artifactId: string): Promise<MigmaResult<EmailArtifact>>;
-    /** Replace one generated email's Migma Email source and persist compiled HTML */
-    update(artifactId: string, params: UpdateEmailArtifactParams): Promise<MigmaResult<EmailArtifact>>;
-    /** Compile an email artifact's source without persisting */
-    compile(artifactId: string, params?: CompileEmailArtifactParams): Promise<MigmaResult<CompileEmailArtifactResponse>>;
+    /** Fetch one generated email by email id */
+    get(emailId: string): Promise<MigmaResult<Email>>;
+    /** Prompt Migma to edit one generated email */
+    edit(emailId: string, params: EditEmailParams): Promise<MigmaResult<Email>>;
     /**
      * Generate an email and wait for completion.
      * Polls getGenerationStatus until status is 'completed' or 'failed'.
@@ -1160,6 +1184,7 @@ interface Campaign {
     projectId: string;
     name: string;
     conversationId: string;
+    emailId?: string | null;
     subject: string;
     preheaderText?: string | null;
     from: string;
@@ -1178,6 +1203,8 @@ interface Campaign {
     sentAt?: string | null;
     completedAt?: string | null;
     error?: string | null;
+    archived?: boolean;
+    archivedAt?: string | null;
     triggeredBy?: 'manual' | 'api' | 'automation';
     createdAt: string;
     updatedAt: string;
@@ -1186,6 +1213,8 @@ interface CreateCampaignParams {
     projectId: string;
     name: string;
     conversationId: string;
+    /** Generated email ID from result.emails[].emailId. Recommended for series slots. */
+    emailId?: string;
     subject?: string;
     preheaderText?: string;
     from: string;
@@ -1202,6 +1231,7 @@ interface ListCampaignsParams {
     status?: CampaignStatus;
     page?: number;
     limit?: number;
+    archived?: boolean;
 }
 interface ListCampaignsResponse {
     campaigns: Campaign[];
@@ -1221,6 +1251,8 @@ declare class Campaigns {
     send(id: string): Promise<MigmaResult<Campaign>>;
     schedule(id: string, params: ScheduleCampaignParams): Promise<MigmaResult<Campaign>>;
     cancel(id: string): Promise<MigmaResult<Campaign>>;
+    archive(id: string): Promise<MigmaResult<Campaign>>;
+    unarchive(id: string): Promise<MigmaResult<Campaign>>;
 }
 
 interface MigmaConfig {
@@ -1251,4 +1283,4 @@ declare class Migma {
     constructor(apiKey: string, config?: MigmaConfig);
 }
 
-export { type AddImageParams, type AddKnowledgeBaseParams, type AnalyzeDeliverabilityParams, type AnalyzeLinksParams, type ApiResponse, type BatchStatus, type BulkImportAsyncResponse, type BulkImportContactItem, type BulkImportJobStatus, type BulkImportParams, type BulkImportResponse, type BulkImportSyncResponse, type Campaign, type CampaignStatus, type ChangeStatusParams, type CheckCompatibilityParams, type CheckSpellingParams, type CheckedLink, type ClientConfig, type CompatibilityResponse, type CompileEmailArtifactParams, type CompileEmailArtifactResponse, type Contact, type ContactStatus, type CreateCampaignParams, type CreateContactParams, type CreateDomainParams, type CreateManagedDomainParams, type CreatePreviewParams, type CreatePreviewResponse, type CreateSegmentParams, type CreateTagParams, type CreateTopicParams, type CreateWebhookParams, type DeleteResponse, type DeliverabilityResponse, type DeviceCategoriesResponse, type DnsRecord, type Domain, type DomainAvailability, type DomainDeleteResponse, type DomainVerificationResult, type EmailArtifact, type EmailGenerationResult, type EmailGenerationStatus, type EmailImage, type ExportFile, type ExportFormat, type ExportFormatsResponse, type ExportResult, type ExportStatusResponse, type GenerateEmailParams, type GenerateEmailResponse, type GeneratedEmailArtifact, type GetDevicePreviewResponse, type GetPreviewResponse, type GetPreviewStatusResponse, type GetSupportedDevicesResponse, type HubspotExportParams, type ImportProjectParams, type ImportProjectResponse, type ImportStatusResponse, type KnowledgeBaseEntry, type KnowledgeBaseListResponse, type LinkAnalysisResponse, type ListCampaignsParams, type ListCampaignsResponse, type ListContactsParams, type ListContactsResponse, type ListEmailsEmail, type ListEmailsParams, type ListEmailsResponse, type ListProjectsParams, type ListProjectsResponse, type ListSegmentsResponse, type ListTagsParams, type ListTagsResponse, type ListTopicsParams, type ListTopicsResponse, type ListWebhooksResponse, type LogosResponse, type MessageResponse, Migma, MigmaClient, type MigmaConfig, MigmaError, MigmaErrorCode, type MigmaResult, type PollingOptions, type PreviewDevice, type PreviewDeviceCategory, type PreviewDeviceStatus, type PreviewMetadata, type PreviewStatus, type Project, type ProjectImage, type ProviderType, type RecipientType, type RetryImportResponse, type ScheduleCampaignParams, type Segment, type SegmentFilters, type SendEmailParams, type SendEmailResponse, type SendTestEmailParams, type SendTestEmailResponse, type SpellingResponse, type SupportedDevice, type Tag, type Topic, type TopicSubscriptionParams, type TopicSubscriptionResponse, type UpdateContactParams, type UpdateDomainParams, type UpdateEmailArtifactParams, type UpdateImageParams, type UpdateKnowledgeBaseParams, type UpdateLogosParams, type UpdateSegmentParams, type UpdateTagParams, type UpdateTopicParams, type UpdateWebhookParams, type ValidateAllParams, type ValidateAllResponse, type Webhook, type WebhookDeliveriesResponse, type WebhookDelivery, type WebhookDetail, type WebhookEvent, type WebhookEventType, type WebhookEventsResponse, type WebhookTestResult, poll };
+export { type AddImageParams, type AddKnowledgeBaseParams, type AnalyzeDeliverabilityParams, type AnalyzeLinksParams, type ApiResponse, type BatchStatus, type BulkImportAsyncResponse, type BulkImportContactItem, type BulkImportJobStatus, type BulkImportParams, type BulkImportResponse, type BulkImportSyncResponse, type Campaign, type CampaignStatus, type ChangeStatusParams, type CheckCompatibilityParams, type CheckSpellingParams, type CheckedLink, type ClientConfig, type CompatibilityResponse, type Contact, type ContactStatus, type CreateCampaignParams, type CreateContactParams, type CreateDomainParams, type CreateManagedDomainParams, type CreatePreviewParams, type CreatePreviewResponse, type CreateSegmentParams, type CreateTagParams, type CreateTopicParams, type CreateWebhookParams, type DeleteResponse, type DeliverabilityResponse, type DeviceCategoriesResponse, type DnsRecord, type Domain, type DomainAvailability, type DomainDeleteResponse, type DomainVerificationResult, type EditEmailParams, type Email, type EmailGenerationResult, type EmailGenerationStatus, type EmailImage, type ExportFile, type ExportFormat, type ExportFormatsResponse, type ExportResult, type ExportStatusResponse, type FieldCatalogEntry, type FieldCatalogEntryType, type FieldCatalogParams, type FieldCatalogResponse, type GenerateEmailParams, type GenerateEmailResponse, type GeneratedEmail, type GetDevicePreviewResponse, type GetPreviewResponse, type GetPreviewStatusResponse, type GetSupportedDevicesResponse, type HubspotExportParams, type ImportProjectParams, type ImportProjectResponse, type ImportStatusResponse, type KnowledgeBaseEntry, type KnowledgeBaseListResponse, type LinkAnalysisResponse, type ListCampaignsParams, type ListCampaignsResponse, type ListContactsParams, type ListContactsResponse, type ListEmailsEmail, type ListEmailsParams, type ListEmailsResponse, type ListProjectsParams, type ListProjectsResponse, type ListSegmentsResponse, type ListTagsParams, type ListTagsResponse, type ListTopicsParams, type ListTopicsResponse, type ListWebhooksResponse, type LogosResponse, type MessageResponse, Migma, MigmaClient, type MigmaConfig, MigmaError, MigmaErrorCode, type MigmaResult, type PollingOptions, type PreviewDevice, type PreviewDeviceCategory, type PreviewDeviceStatus, type PreviewMetadata, type PreviewStatus, type Project, type ProjectImage, type ProviderType, type RecipientType, type RetryImportResponse, type ScheduleCampaignParams, type Segment, type SegmentActivityFilter, type SegmentFieldFilter, type SegmentFilters, type SendEmailParams, type SendEmailResponse, type SendTestEmailParams, type SendTestEmailResponse, type SpellingResponse, type SupportedDevice, type Tag, type Topic, type TopicSubscriptionParams, type TopicSubscriptionResponse, type UpdateContactParams, type UpdateDomainParams, type UpdateImageParams, type UpdateKnowledgeBaseParams, type UpdateLogosParams, type UpdateSegmentParams, type UpdateTagParams, type UpdateTopicParams, type UpdateWebhookParams, type ValidateAllParams, type ValidateAllResponse, type Webhook, type WebhookDeliveriesResponse, type WebhookDelivery, type WebhookDetail, type WebhookEvent, type WebhookEventType, type WebhookEventsResponse, type WebhookTestResult, poll };