@masters-union/outbound-sdk 0.4.5 → 0.4.7

package/dist/index.d.mts

@@ -47,7 +47,35 @@ interface SendEmailResponse {
 interface BulkEmailParams {
     fromEmail: string;
     emailSubject: string;
-    emails: BulkEmailRecipient[];
+    /**
+     * Inline recipients, up to 1000 per request. Mutually exclusive with `listId`.
+     * Required unless `listId` is given.
+     */
+    emails?: Array<BulkEmailRecipient | BulkEmailMergeRecipient>;
+    /**
+     * Send to a saved contact list instead. NO RECIPIENT CAP: the server expands the
+     * list in the background and returns one job id to track. `htmlBody` is required
+     * in this mode, and `mapping` says which contact column feeds each `{{variable}}`.
+     */
+    listId?: string;
+    /**
+     * OPTIONAL shared HTML body (mail merge). Supply it once and give each recipient
+     * a small `variables` object instead of its own full body: the template then
+     * crosses the wire once rather than once per recipient.
+     *
+     * BACKWARD COMPATIBLE: rendering happens if and only if a recipient carries a
+     * `variables` object. A recipient without one is sent verbatim, even if its body
+     * contains `{{...}}`.
+     */
+    htmlBody?: string;
+    /** OPTIONAL shared plain-text body (mail merge). */
+    textBody?: string;
+    /** `{ variableName: columnName }` for a list send. */
+    mapping?: VariableMapping;
+    /** Values for variables no column supplies, applied to every recipient. */
+    defaults?: Record<string, string>;
+    /** Whether a contact missing a variable is skipped (default) or sent anyway. */
+    onMissingVariable?: 'skip' | 'send';
     senderName?: string;
     replyTo?: string;
     /**
@@ -63,7 +91,38 @@ interface BulkEmailParams {
 }
 interface BulkEmailRecipient {
     toEmail: string;
+    /**
+     * This recipient's own HTML body. Still REQUIRED on this shape, deliberately —
+     * making it optional would turn `recipient.htmlBody.length` into a compile error
+     * for anyone who upgraded. To omit it, use the mail-merge shape
+     * `BulkEmailMergeRecipient` instead, which the `emails` array also accepts.
+     */
     htmlBody: string;
+    /**
+     * Optional mail-merge values. Its PRESENCE is what opts this entry into
+     * server-side rendering, so omit it entirely for a body sent verbatim — even one
+     * containing a literal `{{...}}`.
+     */
+    variables?: Record<string, string>;
+    subject?: string;
+    textBody?: string;
+    ccEmail?: string;
+    bccEmail?: string;
+    metadata?: Record<string, unknown>;
+    attachments?: Attachment[];
+}
+/**
+ * A mail-merge recipient: no body of its own, because the request carries a shared
+ * `htmlBody` that is rendered per recipient from `variables`.
+ *
+ * A SEPARATE interface rather than loosening `BulkEmailRecipient.htmlBody`, so that
+ * adding mail merge cannot break a single existing consumer's build.
+ */
+interface BulkEmailMergeRecipient {
+    toEmail: string;
+    variables?: Record<string, string>;
+    /** Overrides the shared body for just this recipient. */
+    htmlBody?: string;
     subject?: string;
     textBody?: string;
     ccEmail?: string;
@@ -268,6 +327,16 @@ interface TemplateSendParams {
 interface TemplateBulkSendParams {
     templateId: string;
     fromEmail: string;
+    /**
+     * Send to a saved contact list instead of `recipients`. No recipient cap — the
+     * server expands the list in the background.
+     */
+    listId?: string;
+    /** `{ variableName: columnName }` for a list send. */
+    mapping?: VariableMapping;
+    /** Values for variables no column supplies. */
+    defaults?: Record<string, string>;
+    onMissingVariable?: 'skip' | 'send';
     senderName?: string;
     replyTo?: string;
     /**
@@ -280,7 +349,8 @@ interface TemplateBulkSendParams {
     priority?: 'critical' | 'urgent' | 'high' | 'normal' | 'low' | 'deferred' | 'backlog';
     idempotencyKey?: string;
     campaignId?: string;
-    recipients: TemplateBulkRecipient[];
+    /** Inline recipients, up to 1000. Mutually exclusive with `listId`. */
+    recipients?: TemplateBulkRecipient[];
 }
 interface TemplateBulkRecipient {
     toEmail: string;
@@ -782,6 +852,213 @@ interface CampaignAnalytics {
     bounceReasons: CampaignBounceReason[];
     timeseries: CampaignTimeseriesPoint[];
 }
+/** Only `subscribed` is ever sent to. */
+type ContactStatus = 'subscribed' | 'invalid' | 'bounced' | 'complained' | 'unsubscribed' | 'suppressed';
+/** The precise cause behind a non-subscribed status. */
+type ContactStatusReason = 'invalid_format' | 'too_long' | 'bounce' | 'complaint' | 'unsubscribe' | 'manual' | 'ses_send_reject';
+interface ContactList {
+    id: string;
+    name: string;
+    description: string | null;
+    status: 'active' | 'deleting';
+    contactCount: number;
+    /** Every attribute key seen on import — the valid targets for a send `mapping`. */
+    fields: string[];
+    metadata: Record<string, unknown> | null;
+    lastImportAt: string | null;
+    lastSentAt: string | null;
+    lastValidatedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ContactListDetail {
+    list: ContactList;
+    /** How many contacts sit in each status. */
+    statusBreakdown: Record<ContactStatus, number>;
+    /** Shorthand for `statusBreakdown.subscribed` — how many this list can reach. */
+    sendable: number;
+    sendablePercent: number;
+}
+interface Contact {
+    id: string;
+    email: string;
+    /** The original CSV value, present only when sanitization changed it. */
+    emailRaw: string | null;
+    name: string | null;
+    attributes: Record<string, string>;
+    status: ContactStatus;
+    statusReason: ContactStatusReason | null;
+    statusChangedAt: string | null;
+    source: 'import' | 'api' | 'manual';
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateContactListParams {
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateContactListParams {
+    name?: string;
+    description?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+interface ListContactListsParams {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sort?: 'recent' | 'created' | 'name' | 'size';
+}
+interface ListContactListsResponse {
+    lists: ContactList[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+    quota: {
+        used: number;
+        allocated: number;
+        remaining: number;
+    };
+}
+interface ImportContactRow {
+    email: string;
+    name?: string;
+    /** Anything else the CSV carried. These keys become the list's `fields`. */
+    attributes?: Record<string, string>;
+}
+interface ImportContactsParams {
+    rows: ImportContactRow[];
+    /**
+     * One id per FILE. Together with `chunkIndex` it makes a retried chunk a no-op
+     * instead of a double-insert, so a failed upload is safe to retry blindly.
+     */
+    importId?: string;
+    chunkIndex?: number;
+    /** Which row wins when the same address appears twice in one chunk. */
+    duplicatesInFile?: 'first' | 'last';
+    /**
+     * What to do with an address already in the list. `update` merges attributes and
+     * refreshes the name; it NEVER re-subscribes a bounced or opted-out contact.
+     */
+    onExisting?: 'skip' | 'update';
+}
+interface ImportContactsResponse {
+    importId: string | null;
+    chunkIndex: number;
+    /** Rows with no usable address at all — the only rows that are not stored. */
+    rejected: Array<{
+        row: number;
+        value: string;
+        reason: string;
+    }>;
+    /** A sample of the addresses stored with `status: 'invalid'`. */
+    invalidSamples: Array<{
+        email: string;
+        emailRaw: string | null;
+        reason: ContactStatusReason;
+    }>;
+    summary: {
+        requested: number;
+        added: number;
+        updated: number;
+        skipped: number;
+        /** How many addresses sanitization actually changed. */
+        sanitized: number;
+        /** Stored, but marked invalid — NOT discarded. */
+        invalid: number;
+        /** Stored, but already on your suppression list. */
+        suppressed: number;
+        duplicatesInFile: number;
+        rejected: number;
+    };
+    list: {
+        id: string;
+        contactCount: number;
+        fields: string[];
+    };
+}
+interface ListContactsParams {
+    limit?: number;
+    /** From the previous response's `pagination.nextCursor`. Keyset, not offset. */
+    cursor?: string;
+    sort?: 'created' | 'email';
+    status?: ContactStatus;
+    search?: string;
+}
+interface ListContactsResponse {
+    contacts: Contact[];
+    pagination: {
+        limit: number;
+        hasMore: boolean;
+        nextCursor: string | null;
+        /** A FLOOR when `totalCapped` is true — an exact filtered count is not run per page. */
+        total: number;
+        totalCapped: boolean;
+    };
+}
+interface AddContactParams {
+    email: string;
+    name?: string;
+    attributes?: Record<string, string>;
+}
+interface UpdateContactParams {
+    name?: string;
+    /** REPLACES the stored object wholesale. Import merges instead. */
+    attributes?: Record<string, string>;
+    status?: ContactStatus;
+}
+interface BulkDeleteContactsParams {
+    contactIds?: string[];
+    emails?: string[];
+    /** A filter rather than ids — how you clear every invalid address in one call. */
+    status?: ContactStatus;
+    all?: boolean;
+}
+interface BulkDeleteContactsResponse {
+    message: string;
+    deleted?: number;
+    listId?: string;
+}
+interface ContactListFieldsResponse {
+    fields: Array<{
+        name: string;
+        sample: string | null;
+    }>;
+    /** Mappable alongside `fields`, but not attributes. */
+    reservedFields: string[];
+}
+interface RecountContactListResponse {
+    contactCount: number;
+    previous: number;
+    drift: number | null;
+    timedOut?: boolean;
+    message?: string;
+}
+interface AcceptedResponse {
+    message: string;
+    listId?: string;
+}
+/**
+ * Which contact column feeds each `{{variable}}`, as `{ variableName: columnName }`.
+ * Omit an entry when the column is already named the same as the variable.
+ * `email` and `name` are always mappable in addition to the list's own fields.
+ */
+type VariableMapping = Record<string, string>;
+interface ListSendResponse {
+    message: string;
+    mode: 'list';
+    jobId: string;
+    listId: string;
+    listName: string;
+    /** How many contacts were sendable when the send was accepted. */
+    estimatedRecipientCount: number;
+    status: 'expanding';
+    statusUrl: string;
+    usingSesTemplate?: boolean;
+}
 
 declare class HttpClient {
     private config;
@@ -801,6 +1078,23 @@ declare class EmailResource {
     private http;
     constructor(http: HttpClient);
     send(params: SendEmailParams, overrides?: RequestOverrides): Promise<SendEmailResponse>;
+    /**
+     * Send to many recipients at once.
+     *
+     * Three shapes, discriminated by what you pass:
+     *   - `emails[]` with a full `htmlBody` each — the original behaviour, unchanged.
+     *   - `emails[]` + a shared `htmlBody` + per-recipient `variables` — MAIL MERGE.
+     *     The template crosses the wire once instead of once per recipient.
+     *   - `listId` (+ `mapping`) — a saved contact list, with NO recipient cap. The
+     *     server materializes the recipients in the background and returns a job id.
+     *
+     * OVERLOADED rather than returning a union, so existing calls keep resolving to
+     * `BulkEmailResponse` exactly as before. A bare union would have made
+     * `res.recipientCount` a compile error for every caller that upgraded.
+     */
+    bulk(params: BulkEmailParams & {
+        listId: string;
+    }, overrides?: RequestOverrides): Promise<ListSendResponse>;
     bulk(params: BulkEmailParams, overrides?: RequestOverrides): Promise<BulkEmailResponse>;
     status(jobId: string, overrides?: RequestOverrides): Promise<JobStatusResponse>;
     /**
@@ -850,6 +1144,19 @@ declare class TemplatesResource {
     }, overrides?: RequestOverrides): Promise<TemplateResponse>;
     preview(id: string, params?: TemplatePreviewParams, overrides?: RequestOverrides): Promise<TemplatePreviewResponse>;
     send(params: TemplateSendParams, overrides?: RequestOverrides): Promise<SendEmailResponse>;
+    /**
+     * Send a template to many recipients.
+     *
+     * Pass `recipients[]` (up to 1000) for an inline send, or `listId` (+ `mapping`)
+     * to send to a whole saved contact list with no recipient cap — the server
+     * expands the list in the background.
+     *
+     * Overloaded rather than returning a union, so existing calls keep resolving to
+     * `TemplateBulkSendResponse` and upgrading the SDK cannot break a build.
+     */
+    bulkSend(params: TemplateBulkSendParams & {
+        listId: string;
+    }, overrides?: RequestOverrides): Promise<ListSendResponse>;
     bulkSend(params: TemplateBulkSendParams, overrides?: RequestOverrides): Promise<TemplateBulkSendResponse>;
     stats(overrides?: RequestOverrides): Promise<TemplateStatsResponse>;
 }
@@ -942,6 +1249,97 @@ declare class CampaignsResource {
     analytics(campaignId: string, params?: CampaignAnalyticsParams, overrides?: RequestOverrides): Promise<CampaignAnalytics>;
 }
 
+/**
+ * Contact lists: reusable audiences you can send to without a recipient limit.
+ *
+ * The per-request cap on `email.bulk` / `templates.bulkSend` exists because those
+ * carry their recipients in the request body. A list send carries only a `listId`,
+ * and the server expands the list in the background — so there is no cap, and the
+ * caller gets one job id to track however large the audience is.
+ *
+ * ── Address hygiene ──
+ * Every imported address is sanitized (display-name unwrapping, `mailto:`,
+ * zero-width characters, quotes, case) and then validated with the SAME rules the
+ * send path applies. Addresses that fail are STORED with `status: 'invalid'` rather
+ * than discarded, so you can list them, export them and fix them. Addresses on your
+ * suppression list are stored with the matching status. Only `subscribed` contacts
+ * are ever sent to, and bounces, complaints and unsubscribes flow back onto the
+ * contact automatically.
+ */
+declare class ContactListsResource {
+    private http;
+    constructor(http: HttpClient);
+    create(params: CreateContactListParams, overrides?: RequestOverrides): Promise<{
+        message: string;
+        list: ContactList;
+    }>;
+    list(params?: ListContactListsParams, overrides?: RequestOverrides): Promise<ListContactListsResponse>;
+    /** Auto-paginating iterator over every contact list, mirroring templates.listAll(). */
+    listAll(params?: Omit<ListContactListsParams, 'page'>, overrides?: RequestOverrides): AsyncGenerator<ContactList>;
+    /** A list plus its per-status breakdown (how many are sendable, invalid, bounced...). */
+    get(listId: string, overrides?: RequestOverrides): Promise<ContactListDetail>;
+    update(listId: string, params: UpdateContactListParams, overrides?: RequestOverrides): Promise<{
+        message: string;
+        list: ContactList;
+    }>;
+    /**
+     * Delete a list. Returns 202: the contacts are removed by a background job in
+     * chunks, so a multi-million-row list does not block on one enormous transaction.
+     * Fails with a conflict while a send is still expanding this list.
+     */
+    delete(listId: string, overrides?: RequestOverrides): Promise<AcceptedResponse>;
+    /**
+     * Import a chunk of contacts (max 1000 rows per call).
+     *
+     * Pass the same `importId` with an incrementing `chunkIndex` for every chunk of
+     * one file: that pair makes a retried chunk a no-op instead of a double-insert,
+     * so a network failure mid-upload is safe to retry blindly.
+     *
+     * `onExisting: 'update'` merges attributes into contacts already in the list. It
+     * never re-subscribes someone who bounced, complained or opted out.
+     */
+    importContacts(listId: string, params: ImportContactsParams, overrides?: RequestOverrides): Promise<ImportContactsResponse>;
+    /**
+     * List contacts. KEYSET paginated: pass the previous response's
+     * `pagination.nextCursor` as `cursor` to advance. There is no page number,
+     * because offset paging degrades badly past a few hundred pages.
+     */
+    contacts(listId: string, params?: ListContactsParams, overrides?: RequestOverrides): Promise<ListContactsResponse>;
+    /** Auto-paginating iterator over every contact in a list. */
+    contactsAll(listId: string, params?: Omit<ListContactsParams, 'cursor'>, overrides?: RequestOverrides): AsyncGenerator<Contact>;
+    addContact(listId: string, params: AddContactParams, overrides?: RequestOverrides): Promise<{
+        message: string;
+        contact: Contact;
+    }>;
+    /** `attributes` REPLACES the stored object wholesale here; import merges instead. */
+    updateContact(listId: string, contactId: string, params: UpdateContactParams, overrides?: RequestOverrides): Promise<{
+        message: string;
+        contact: Contact;
+    }>;
+    deleteContact(listId: string, contactId: string, overrides?: RequestOverrides): Promise<void>;
+    /**
+     * Delete many contacts. Pass `contactIds` or `emails` (up to 1000), or a FILTER
+     * — `{ status: 'invalid' }` or `{ all: true }` — which is how you clear tens of
+     * thousands of dead addresses in one small request. Filtered deletes return 202
+     * and run in the background.
+     */
+    bulkDeleteContacts(listId: string, params: BulkDeleteContactsParams, overrides?: RequestOverrides): Promise<BulkDeleteContactsResponse>;
+    /**
+     * The column names available for send-time variable mapping, with a sample value
+     * for each. This is what tells you which `mapping` keys a list will accept.
+     */
+    fields(listId: string, options?: {
+        refresh?: boolean;
+    }, overrides?: RequestOverrides): Promise<ContactListFieldsResponse>;
+    /**
+     * Re-run validation and re-sync suppression across the whole list. Useful after a
+     * bulk suppression import, or to refresh a list that has been sitting. Returns 202.
+     */
+    revalidate(listId: string, overrides?: RequestOverrides): Promise<AcceptedResponse>;
+    /** Reconcile the denormalized contact count with an exact COUNT. */
+    recount(listId: string, overrides?: RequestOverrides): Promise<RecountContactListResponse>;
+}
+
 declare class Outbound {
     readonly email: EmailResource;
     readonly templates: TemplatesResource;
@@ -950,6 +1348,7 @@ declare class Outbound {
     readonly dashboard: DashboardResource;
     readonly quota: QuotaResource;
     readonly campaigns: CampaignsResource;
+    readonly contactLists: ContactListsResource;
     constructor(config?: OutboundConfig);
     /**
      * Verify a webhook signature using HMAC-SHA256.
@@ -993,4 +1392,4 @@ declare class NetworkError extends OutboundError {
     constructor(message?: string);
 }
 
-export { type AddSuppressionParams, type AnyIncomingWebhookPayload, type Attachment, AuthenticationError, BadRequestError, type BulkAddSuppressionsParams, type BulkAddSuppressionsResponse, type BulkEmailParams, type BulkEmailRecipient, type BulkEmailResponse, type BulkRemoveSuppressionsParams, type BulkRemoveSuppressionsResponse, type BulkResponseRecipient, type CampaignAnalytics, type CampaignAnalyticsParams, type CampaignBounceReason, type CampaignDomainStat, type CampaignRates, type CampaignStatus, type CampaignSummary, type CampaignTimeseriesPoint, type CampaignTotals, type CancelEmailParams, type CancelEmailResponse, ConflictError, type CreateTemplateParams, type CreateWebhookParams, type CreateWebhookResponse, type DashboardResponse, type DedicatedIpWarmup, type EmailJob, type EmailList, type EmailRecipientStatus, type EmailStatus, ForbiddenError, type GlobalQuotaResponse, type IncomingWebhookEvent, type IncomingWebhookEventV2, type IncomingWebhookPayload, type IncomingWebhookPayloadV2, type IpPoolStatus, type JobStatusResponse, type ListCampaignsParams, type ListCampaignsResponse, type ListSuppressionsParams, type ListSuppressionsResponse, type ListTemplatesParams, type ListTemplatesResponse, type ListWebhooksResponse, type MessageContentResponse, type MessageStatusRecipient, type MessageStatusResponse, NetworkError, NotFoundError, Outbound, type OutboundConfig, OutboundError, type QuotaResponse, RateLimitError, type RejectedEmail, type RequestOverrides, type ResolvedConfig, type SearchSuppressionsParams, type SearchSuppressionsResponse, type SendEmailParams, type SendEmailResponse, ServerError, type Suppression, type SuppressionReason, type SuppressionResponse, type Template, type TemplateBulkRecipient, type TemplateBulkSendParams, type TemplateBulkSendResponse, type TemplatePreviewParams, type TemplatePreviewResponse, type TemplateResponse, type TemplateSendParams, type TemplateStatsResponse, TimeoutError, type UpdateTemplateParams, type UpdateWebhookParams, type UpdateWebhookResponse, type Webhook, type WebhookEvent, type WebhookEventDetails, type WebhookEventStatus, type WebhookRetryStrategy };
+export { type AcceptedResponse, type AddContactParams, type AddSuppressionParams, type AnyIncomingWebhookPayload, type Attachment, AuthenticationError, BadRequestError, type BulkAddSuppressionsParams, type BulkAddSuppressionsResponse, type BulkDeleteContactsParams, type BulkDeleteContactsResponse, type BulkEmailMergeRecipient, type BulkEmailParams, type BulkEmailRecipient, type BulkEmailResponse, type BulkRemoveSuppressionsParams, type BulkRemoveSuppressionsResponse, type BulkResponseRecipient, type CampaignAnalytics, type CampaignAnalyticsParams, type CampaignBounceReason, type CampaignDomainStat, type CampaignRates, type CampaignStatus, type CampaignSummary, type CampaignTimeseriesPoint, type CampaignTotals, type CancelEmailParams, type CancelEmailResponse, type CheckQuotaResponse, ConflictError, type Contact, type ContactList, type ContactListDetail, type ContactListFieldsResponse, type ContactStatus, type ContactStatusReason, type CreateContactListParams, type CreateTemplateParams, type CreateWebhookParams, type CreateWebhookResponse, type DashboardResponse, type DedicatedIpWarmup, type EmailJob, type EmailList, type EmailRecipientStatus, type EmailStatus, ForbiddenError, type GlobalQuotaResponse, type ImportContactRow, type ImportContactsParams, type ImportContactsResponse, type IncomingWebhookEvent, type IncomingWebhookEventV2, type IncomingWebhookPayload, type IncomingWebhookPayloadV2, type IpPoolStatus, type JobStatusResponse, type ListCampaignsParams, type ListCampaignsResponse, type ListContactListsParams, type ListContactListsResponse, type ListContactsParams, type ListContactsResponse, type ListSendResponse, type ListSuppressionsParams, type ListSuppressionsResponse, type ListTemplatesParams, type ListTemplatesResponse, type ListWebhooksResponse, type MessageContentResponse, type MessageStatusRecipient, type MessageStatusResponse, NetworkError, NotFoundError, Outbound, type OutboundConfig, OutboundError, type QuotaResponse, RateLimitError, type RecountContactListResponse, type RejectedEmail, type RequestOverrides, type ResolvedConfig, type SearchSuppressionsParams, type SearchSuppressionsResponse, type SendEmailParams, type SendEmailResponse, ServerError, type Suppression, type SuppressionReason, type SuppressionResponse, type Template, type TemplateBulkRecipient, type TemplateBulkSendParams, type TemplateBulkSendResponse, type TemplatePreviewParams, type TemplatePreviewResponse, type TemplateResponse, type TemplateSendParams, type TemplateStatsResponse, TimeoutError, type UpdateContactListParams, type UpdateContactParams, type UpdateTemplateParams, type UpdateWebhookParams, type UpdateWebhookResponse, type VariableMapping, type Webhook, type WebhookEvent, type WebhookEventDetails, type WebhookEventStatus, type WebhookRetryStrategy };