mailbreeze 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1280 @@
+/**
+ * Parameters for creating an attachment upload.
+ */
+interface CreateAttachmentUploadParams {
+    /** Original filename */
+    fileName: string;
+    /** MIME type of the file */
+    contentType: string;
+    /** File size in bytes */
+    fileSize: number;
+}
+/**
+ * Result of creating an attachment upload.
+ */
+interface CreateAttachmentUploadResult {
+    /** Attachment ID to use when sending emails */
+    attachmentId: string;
+    /** Presigned URL for uploading the file */
+    uploadUrl: string;
+    /** Upload token for confirmation */
+    uploadToken: string;
+    /** Expiration time for the upload URL */
+    expiresAt: string;
+}
+/**
+ * Parameters for confirming an attachment upload.
+ */
+interface ConfirmAttachmentParams {
+    /** Upload token received from createUpload */
+    uploadToken: string;
+}
+/**
+ * Attachment record.
+ */
+interface Attachment {
+    id: string;
+    fileName: string;
+    contentType: string;
+    fileSize: number;
+    status: "pending" | "uploaded" | "expired";
+    createdAt: string;
+    expiresAt: string;
+}
+
+/**
+ * Pagination information returned with list endpoints.
+ */
+interface Pagination {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+/**
+ * Paginated list response.
+ */
+interface PaginatedList<T> {
+    data: T[];
+    pagination: Pagination;
+}
+/**
+ * Common query parameters for list endpoints.
+ */
+interface ListParams {
+    page?: number;
+    limit?: number;
+}
+/**
+ * SDK configuration options.
+ */
+interface MailBreezeConfig {
+    /** Your MailBreeze API key (starts with sk_) */
+    apiKey: string;
+    /** Base URL for the API (defaults to https://api.mailbreeze.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (defaults to 30000) */
+    timeout?: number;
+    /** Maximum number of retries for failed requests (defaults to 3) */
+    maxRetries?: number;
+    /** Authentication style: 'header' uses X-API-Key, 'bearer' uses Authorization header */
+    authStyle?: "header" | "bearer";
+}
+/**
+ * Domain context header for multi-tenant operations.
+ */
+interface DomainContext {
+    domainId: string;
+}
+
+/**
+ * Parameters for enrolling a contact in an automation.
+ */
+interface EnrollParams {
+    /** Automation ID to enroll in */
+    automationId: string;
+    /** Contact ID to enroll */
+    contactId: string;
+    /** Optional variables to pass to the automation */
+    variables?: Record<string, unknown>;
+}
+/**
+ * Result of enrolling a contact.
+ */
+interface EnrollResult {
+    /** Enrollment ID */
+    enrollmentId: string;
+    /** Current status */
+    status: "active" | "paused" | "completed" | "cancelled";
+    /** When enrolled */
+    enrolledAt: string;
+}
+/**
+ * Enrollment record.
+ */
+interface Enrollment {
+    id: string;
+    automationId: string;
+    automationName: string;
+    contactId: string;
+    contactEmail: string;
+    status: "active" | "paused" | "completed" | "cancelled";
+    currentStep: number;
+    totalSteps: number;
+    variables?: Record<string, unknown>;
+    enrolledAt: string;
+    completedAt?: string;
+    cancelledAt?: string;
+}
+/**
+ * Parameters for listing enrollments.
+ */
+interface ListEnrollmentsParams extends ListParams {
+    /** Filter by automation ID */
+    automationId?: string;
+    /** Filter by status */
+    status?: "active" | "paused" | "completed" | "cancelled";
+}
+/**
+ * Result of cancelling an enrollment.
+ */
+interface CancelEnrollmentResult {
+    /** Whether cancellation was successful */
+    cancelled: boolean;
+    /** Cancellation timestamp */
+    cancelledAt: string;
+}
+
+/**
+ * Parameters for creating a contact.
+ */
+interface CreateContactParams {
+    /** Contact's email address */
+    email: string;
+    /** First name */
+    firstName?: string;
+    /** Last name */
+    lastName?: string;
+    /** Phone number */
+    phoneNumber?: string;
+    /** Custom fields defined in the contact list */
+    customFields?: Record<string, unknown>;
+    /** Source of the contact (e.g., 'api', 'import', 'form') */
+    source?: string;
+}
+/**
+ * Parameters for updating a contact.
+ */
+interface UpdateContactParams {
+    /** First name */
+    firstName?: string;
+    /** Last name */
+    lastName?: string;
+    /** Phone number */
+    phoneNumber?: string;
+    /** Custom fields defined in the contact list */
+    customFields?: Record<string, unknown>;
+}
+/**
+ * Contact record.
+ */
+interface Contact {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phoneNumber?: string;
+    customFields?: Record<string, unknown>;
+    status: "active" | "unsubscribed" | "bounced" | "complained" | "suppressed";
+    source: string;
+    createdAt: string;
+    updatedAt: string;
+    subscribedAt?: string;
+    unsubscribedAt?: string;
+}
+/**
+ * Parameters for listing contacts.
+ */
+interface ListContactsParams extends ListParams {
+    /** Filter by status */
+    status?: "active" | "unsubscribed" | "bounced" | "complained" | "suppressed";
+}
+/**
+ * Reason for suppressing a contact.
+ */
+type SuppressReason = "manual" | "unsubscribed" | "bounced" | "complained" | "spam_trap";
+
+/**
+ * Parameters for sending an email.
+ */
+interface SendEmailParams {
+    /** Sender email address (must match verified domain) */
+    from: string;
+    /** Recipient email address(es) */
+    to: string | string[];
+    /** Email subject line */
+    subject?: string;
+    /** HTML content of the email */
+    html?: string;
+    /** Plain text content of the email */
+    text?: string;
+    /** Template ID to use instead of raw content */
+    templateId?: string;
+    /** Variables to substitute in the template */
+    variables?: Record<string, unknown>;
+    /** IDs of uploaded attachments to include */
+    attachmentIds?: string[];
+    /** Optional CC recipients */
+    cc?: string | string[];
+    /** Optional BCC recipients */
+    bcc?: string | string[];
+    /** Optional reply-to address */
+    replyTo?: string;
+    /** Custom headers to include */
+    headers?: Record<string, string>;
+    /** Idempotency key for safe retries */
+    idempotencyKey?: string;
+}
+/**
+ * Result of sending an email.
+ */
+interface SendEmailResult {
+    /** Unique email ID */
+    id: string;
+    /** Current status */
+    status: "queued" | "sent" | "delivered" | "bounced" | "failed";
+    /** Message ID (SMTP) */
+    messageId?: string;
+    /** Timestamp when queued */
+    createdAt: string;
+}
+/**
+ * Email record returned from list/get.
+ */
+interface Email {
+    id: string;
+    from: string;
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    status: "queued" | "sent" | "delivered" | "bounced" | "failed";
+    messageId?: string;
+    templateId?: string;
+    createdAt: string;
+    sentAt?: string;
+    deliveredAt?: string;
+    openedAt?: string;
+    clickedAt?: string;
+}
+/**
+ * Parameters for listing emails.
+ */
+interface ListEmailsParams extends ListParams {
+    /** Filter by status */
+    status?: "queued" | "sent" | "delivered" | "bounced" | "failed";
+    /** Filter by recipient email */
+    to?: string;
+    /** Filter by sender email */
+    from?: string;
+    /** Filter by date range start */
+    startDate?: string;
+    /** Filter by date range end */
+    endDate?: string;
+}
+/**
+ * Email statistics.
+ */
+interface EmailStats {
+    sent: number;
+    delivered: number;
+    bounced: number;
+    opened: number;
+    clicked: number;
+    complained: number;
+    deliveryRate: number;
+    openRate: number;
+    clickRate: number;
+    bounceRate: number;
+}
+
+/**
+ * Parameters for creating a contact list.
+ */
+interface CreateListParams {
+    /** List name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Custom field definitions */
+    customFields?: CustomFieldDefinition[];
+}
+/**
+ * Parameters for updating a contact list.
+ */
+interface UpdateListParams {
+    /** List name */
+    name?: string;
+    /** Optional description */
+    description?: string;
+    /** Custom field definitions */
+    customFields?: CustomFieldDefinition[];
+}
+/**
+ * Custom field definition for a contact list.
+ */
+interface CustomFieldDefinition {
+    /** Field key (used in API) */
+    key: string;
+    /** Display label */
+    label: string;
+    /** Field type */
+    type: "text" | "number" | "date" | "boolean" | "select";
+    /** Whether field is required */
+    required?: boolean;
+    /** Default value */
+    defaultValue?: unknown;
+    /** Options for select type */
+    options?: string[];
+}
+/**
+ * Contact list record.
+ */
+interface ContactList {
+    id: string;
+    name: string;
+    description?: string;
+    customFields: CustomFieldDefinition[];
+    contactCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Parameters for listing contact lists.
+ */
+type ListListsParams = ListParams;
+/**
+ * Contact list statistics.
+ */
+interface ListStats {
+    totalContacts: number;
+    activeContacts: number;
+    unsubscribedContacts: number;
+    bouncedContacts: number;
+    complainedContacts: number;
+    suppressedContacts: number;
+}
+
+/**
+ * Result of verifying a single email.
+ */
+interface VerifyEmailResult {
+    /** The email address that was verified */
+    email: string;
+    /** Whether the email is valid and deliverable */
+    isValid: boolean;
+    /** Detailed result category */
+    result: "valid" | "invalid" | "risky" | "unknown";
+    /** Reason for the result */
+    reason: string;
+    /** Whether this was a cached result */
+    cached: boolean;
+    /** Risk score (0-100, lower is better) */
+    riskScore?: number;
+    /** Additional details */
+    details?: {
+        isFreeProvider?: boolean;
+        isDisposable?: boolean;
+        isRoleAccount?: boolean;
+        hasMxRecords?: boolean;
+        isSpamTrap?: boolean;
+    };
+}
+/**
+ * Parameters for batch verification.
+ */
+interface BatchVerifyParams {
+    /** Array of email addresses to verify (max 1000) */
+    emails: string[];
+}
+/**
+ * Result of starting a batch verification.
+ */
+interface BatchVerifyResult {
+    /** Verification batch ID for polling */
+    verificationId: string;
+    /** Total emails in batch */
+    totalEmails: number;
+    /** Credits deducted for this batch */
+    creditsDeducted: number;
+    /** Current status */
+    status: "pending" | "processing" | "completed" | "failed";
+    /** Results (only populated when all emails are cached) */
+    results?: VerifyEmailResult[];
+}
+/**
+ * Batch verification status response.
+ */
+interface VerificationStatus {
+    id: string;
+    status: "pending" | "processing" | "completed" | "failed";
+    totalEmails: number;
+    processedEmails: number;
+    creditsDeducted: number;
+    createdAt: string;
+    completedAt?: string;
+    /** Results when completed */
+    results?: VerifyEmailResult[];
+    /** Analytics summary when completed */
+    analytics?: {
+        valid: number;
+        invalid: number;
+        risky: number;
+        unknown: number;
+    };
+}
+/**
+ * Parameters for listing verifications.
+ */
+interface ListVerificationsParams extends ListParams {
+    /** Filter by status */
+    status?: "pending" | "processing" | "completed" | "failed";
+}
+/**
+ * Verification statistics.
+ */
+interface VerificationStats {
+    totalVerified: number;
+    valid: number;
+    invalid: number;
+    risky: number;
+    unknown: number;
+    cached: number;
+    creditsUsed: number;
+}
+
+interface FetcherConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+    maxRetries: number;
+    authStyle?: "header" | "bearer";
+}
+interface RequestOptions {
+    idempotencyKey?: string;
+    timeout?: number;
+}
+/**
+ * HTTP client for making requests to the MailBreeze API.
+ * Handles authentication, retries, timeouts, and error mapping.
+ */
+declare class Fetcher {
+    private readonly config;
+    constructor(config: FetcherConfig);
+    /**
+     * Make an HTTP request to the API.
+     *
+     * @param method - HTTP method
+     * @param path - API path (will be appended to baseUrl)
+     * @param body - Request body (for POST/PUT/PATCH)
+     * @param query - Query parameters
+     * @param options - Additional request options
+     * @returns Parsed response data
+     */
+    request<T>(method: string, path: string, body?: Record<string, unknown>, query?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    private executeRequest;
+    private handleResponse;
+    private buildUrl;
+    private buildHeaders;
+    private isRetryable;
+    private getRetryDelay;
+    private sleep;
+}
+
+/**
+ * Base class for all API resources.
+ * Provides common functionality for making API requests.
+ */
+declare abstract class BaseResource {
+    protected readonly fetcher: Fetcher;
+    protected readonly domainId?: string;
+    constructor(fetcher: Fetcher, domainId?: string);
+    /**
+     * Make a GET request.
+     */
+    protected _get<T>(path: string, query?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    /**
+     * Make a POST request.
+     */
+    protected _post<T>(path: string, body?: object, query?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    /**
+     * Make a PUT request.
+     */
+    protected _put<T>(path: string, body?: object, query?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    /**
+     * Make a PATCH request.
+     */
+    protected _patch<T>(path: string, body?: object, query?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    /**
+     * Make a DELETE request.
+     */
+    protected _delete<T>(path: string, query?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    /**
+     * Build the full path including any base path for the resource.
+     */
+    protected buildPath(path: string): string;
+    /**
+     * Add domain ID to query params if configured.
+     */
+    private addDomainId;
+    /**
+     * Helper to extract pagination from list response.
+     */
+    protected extractPaginatedList<T>(response: {
+        data: T[];
+        pagination: PaginatedList<T>["pagination"];
+    } | T[]): PaginatedList<T>;
+    /**
+     * Convert list params to query object.
+     */
+    protected listParamsToQuery(params?: ListParams): Record<string, unknown> | undefined;
+}
+
+/**
+ * Email attachment handling.
+ *
+ * Attachments use a two-step process:
+ * 1. Create an upload URL with `createUpload()`
+ * 2. Upload the file directly to the URL
+ * 3. Confirm the upload with `confirm()`
+ * 4. Use the attachment ID when sending emails
+ *
+ * @example
+ * ```ts
+ * // Create upload
+ * const { attachmentId, uploadUrl, uploadToken } = await mailbreeze.attachments.createUpload({
+ *   fileName: "report.pdf",
+ *   contentType: "application/pdf",
+ *   fileSize: 1024000,
+ * });
+ *
+ * // Upload file directly
+ * await fetch(uploadUrl, {
+ *   method: "PUT",
+ *   body: fileBuffer,
+ *   headers: { "Content-Type": "application/pdf" },
+ * });
+ *
+ * // Confirm upload
+ * const attachment = await mailbreeze.attachments.confirm({
+ *   uploadToken,
+ * });
+ *
+ * // Use in email
+ * await mailbreeze.emails.send({
+ *   from: "hello@yourdomain.com",
+ *   to: "user@example.com",
+ *   subject: "Your report",
+ *   html: "<p>Please find the report attached.</p>",
+ *   attachmentIds: [attachmentId],
+ * });
+ * ```
+ */
+declare class Attachments extends BaseResource {
+    /**
+     * Create a presigned URL for uploading an attachment.
+     *
+     * @param params - Attachment metadata
+     * @returns Upload URL and attachment ID
+     *
+     * @example
+     * ```ts
+     * const { attachmentId, uploadUrl, uploadToken, expiresAt } =
+     *   await mailbreeze.attachments.createUpload({
+     *     fileName: "document.pdf",
+     *     contentType: "application/pdf",
+     *     fileSize: 2048000,
+     *   });
+     * ```
+     */
+    createUpload(params: CreateAttachmentUploadParams): Promise<CreateAttachmentUploadResult>;
+    /**
+     * Confirm that an attachment has been uploaded.
+     *
+     * Must be called after uploading the file to the presigned URL.
+     * The attachment is only available for use after confirmation.
+     *
+     * @param params - Confirmation parameters including upload token
+     * @returns Confirmed attachment record
+     *
+     * @example
+     * ```ts
+     * const attachment = await mailbreeze.attachments.confirm({
+     *   uploadToken: "token_xxx",
+     * });
+     * console.log(attachment.status); // "uploaded"
+     * ```
+     */
+    confirm(params: ConfirmAttachmentParams): Promise<Attachment>;
+}
+
+/**
+ * Automation enrollment management.
+ *
+ * Enroll contacts in automations, list enrollments, and cancel them.
+ *
+ * @example
+ * ```ts
+ * // Enroll a contact
+ * const enrollment = await mailbreeze.automations.enroll({
+ *   automationId: "auto_xxx",
+ *   contactId: "contact_xxx",
+ *   variables: { couponCode: "WELCOME10" },
+ * });
+ *
+ * // List active enrollments
+ * const { data } = await mailbreeze.automations.enrollments.list({
+ *   status: "active",
+ * });
+ * ```
+ */
+declare class Automations extends BaseResource {
+    /**
+     * Enrollments sub-resource for listing and cancelling.
+     */
+    readonly enrollments: AutomationEnrollments;
+    constructor(fetcher: Fetcher, domainId?: string);
+    /**
+     * Enroll a contact in an automation.
+     *
+     * @param params - Enrollment parameters
+     * @returns Enrollment result
+     *
+     * @example
+     * ```ts
+     * const enrollment = await mailbreeze.automations.enroll({
+     *   automationId: "auto_welcome",
+     *   contactId: "contact_xxx",
+     *   variables: { firstName: "John" },
+     * });
+     * console.log(enrollment.enrollmentId);
+     * ```
+     */
+    enroll(params: EnrollParams): Promise<EnrollResult>;
+}
+/**
+ * Automation enrollments sub-resource.
+ */
+declare class AutomationEnrollments extends BaseResource {
+    /**
+     * List automation enrollments.
+     *
+     * @param params - Filter and pagination options
+     * @returns Paginated list of enrollments
+     *
+     * @example
+     * ```ts
+     * const { data, pagination } = await mailbreeze.automations.enrollments.list({
+     *   automationId: "auto_xxx",
+     *   status: "active",
+     * });
+     * ```
+     */
+    list(params?: ListEnrollmentsParams): Promise<PaginatedList<Enrollment>>;
+    /**
+     * Cancel an enrollment.
+     *
+     * The contact will stop receiving emails from this automation.
+     *
+     * @param enrollmentId - Enrollment ID
+     * @returns Cancellation result
+     *
+     * @example
+     * ```ts
+     * const result = await mailbreeze.automations.enrollments.cancel("enroll_xxx");
+     * console.log(result.cancelled); // true
+     * ```
+     */
+    cancel(enrollmentId: string): Promise<CancelEnrollmentResult>;
+}
+
+/**
+ * Contact management within a list.
+ *
+ * All contact operations require a list context. Get a contacts instance
+ * by calling `mailbreeze.contacts(listId)`.
+ *
+ * @example
+ * ```ts
+ * const contacts = mailbreeze.contacts("list_xxx");
+ *
+ * // Create a contact
+ * const contact = await contacts.create({
+ *   email: "user@example.com",
+ *   firstName: "John",
+ *   lastName: "Doe",
+ *   customFields: { company: "Acme Inc" },
+ * });
+ *
+ * // List contacts
+ * const { data, pagination } = await contacts.list({ status: "active" });
+ * ```
+ */
+declare class Contacts extends BaseResource {
+    private readonly listId;
+    constructor(fetcher: Fetcher, listId: string, domainId?: string);
+    protected buildPath(path: string): string;
+    /**
+     * Create a new contact in the list.
+     *
+     * @param params - Contact data
+     * @returns Created contact record
+     *
+     * @example
+     * ```ts
+     * const contact = await contacts.create({
+     *   email: "user@example.com",
+     *   firstName: "Jane",
+     *   lastName: "Smith",
+     *   customFields: { plan: "pro" },
+     * });
+     * ```
+     */
+    create(params: CreateContactParams): Promise<Contact>;
+    /**
+     * List contacts in the list.
+     *
+     * @param params - Filter and pagination options
+     * @returns Paginated list of contacts
+     *
+     * @example
+     * ```ts
+     * const { data, pagination } = await contacts.list({
+     *   status: "active",
+     *   page: 1,
+     *   limit: 50,
+     * });
+     * ```
+     */
+    list(params?: ListContactsParams): Promise<PaginatedList<Contact>>;
+    /**
+     * Get a contact by ID.
+     *
+     * @param id - Contact ID
+     * @returns Contact record
+     *
+     * @example
+     * ```ts
+     * const contact = await contacts.get("contact_xxx");
+     * ```
+     */
+    get(id: string): Promise<Contact>;
+    /**
+     * Update a contact.
+     *
+     * @param id - Contact ID
+     * @param params - Fields to update
+     * @returns Updated contact record
+     *
+     * @example
+     * ```ts
+     * const contact = await contacts.update("contact_xxx", {
+     *   firstName: "Updated Name",
+     *   customFields: { plan: "enterprise" },
+     * });
+     * ```
+     */
+    update(id: string, params: UpdateContactParams): Promise<Contact>;
+    /**
+     * Delete a contact.
+     *
+     * @param id - Contact ID
+     * @returns void
+     *
+     * @example
+     * ```ts
+     * await contacts.delete("contact_xxx");
+     * ```
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Suppress a contact.
+     *
+     * Suppressed contacts will not receive any emails.
+     * This is different from unsubscribing - suppression is
+     * typically used for bounces, complaints, or manual removal.
+     *
+     * @param id - Contact ID
+     * @param reason - Reason for suppression
+     * @returns void
+     *
+     * @example
+     * ```ts
+     * await contacts.suppress("contact_xxx", "manual");
+     * ```
+     */
+    suppress(id: string, reason: SuppressReason): Promise<void>;
+}
+
+/**
+ * Email sending and management.
+ *
+ * @example
+ * ```ts
+ * // Send an email
+ * const result = await mailbreeze.emails.send({
+ *   from: "hello@yourdomain.com",
+ *   to: "user@example.com",
+ *   subject: "Welcome!",
+ *   html: "<h1>Welcome to our platform!</h1>",
+ * });
+ *
+ * // Send with a template
+ * const result = await mailbreeze.emails.send({
+ *   from: "hello@yourdomain.com",
+ *   to: "user@example.com",
+ *   templateId: "welcome-template",
+ *   variables: { name: "John", plan: "Pro" },
+ * });
+ * ```
+ */
+declare class Emails extends BaseResource {
+    /**
+     * Send an email.
+     *
+     * @param params - Email parameters
+     * @returns Send result with email ID and status
+     *
+     * @example
+     * ```ts
+     * const result = await mailbreeze.emails.send({
+     *   from: "hello@yourdomain.com",
+     *   to: "user@example.com",
+     *   subject: "Hello",
+     *   html: "<p>Hello World!</p>",
+     * });
+     * console.log(result.id); // email_xxx
+     * ```
+     */
+    send(params: SendEmailParams): Promise<SendEmailResult>;
+    /**
+     * List sent emails with optional filtering.
+     *
+     * @param params - Filter and pagination options
+     * @returns Paginated list of emails
+     *
+     * @example
+     * ```ts
+     * const { data, pagination } = await mailbreeze.emails.list({
+     *   status: "delivered",
+     *   page: 1,
+     *   limit: 20,
+     * });
+     * ```
+     */
+    list(params?: ListEmailsParams): Promise<PaginatedList<Email>>;
+    /**
+     * Get a single email by ID.
+     *
+     * @param id - Email ID
+     * @returns Email record
+     *
+     * @example
+     * ```ts
+     * const email = await mailbreeze.emails.get("email_xxx");
+     * console.log(email.status); // "delivered"
+     * ```
+     */
+    get(id: string): Promise<Email>;
+    /**
+     * Get email statistics for the domain.
+     *
+     * @returns Email statistics including delivery rates
+     *
+     * @example
+     * ```ts
+     * const stats = await mailbreeze.emails.stats();
+     * console.log(stats.deliveryRate); // 0.98
+     * ```
+     */
+    stats(): Promise<EmailStats>;
+}
+
+/**
+ * Contact list management.
+ *
+ * @example
+ * ```ts
+ * // Create a list
+ * const list = await mailbreeze.lists.create({
+ *   name: "Newsletter Subscribers",
+ *   description: "Weekly newsletter recipients",
+ *   customFields: [
+ *     { key: "company", label: "Company", type: "text" },
+ *     { key: "plan", label: "Plan", type: "select", options: ["free", "pro", "enterprise"] },
+ *   ],
+ * });
+ *
+ * // Get list stats
+ * const stats = await mailbreeze.lists.stats(list.id);
+ * console.log(stats.activeContacts);
+ * ```
+ */
+declare class Lists extends BaseResource {
+    /**
+     * Create a new contact list.
+     *
+     * @param params - List configuration
+     * @returns Created list record
+     *
+     * @example
+     * ```ts
+     * const list = await mailbreeze.lists.create({
+     *   name: "VIP Customers",
+     *   customFields: [
+     *     { key: "tier", label: "Tier", type: "select", options: ["gold", "platinum"] },
+     *   ],
+     * });
+     * ```
+     */
+    create(params: CreateListParams): Promise<ContactList>;
+    /**
+     * List all contact lists.
+     *
+     * @param params - Pagination options
+     * @returns Paginated list of contact lists
+     *
+     * @example
+     * ```ts
+     * const { data, pagination } = await mailbreeze.lists.list({ page: 1, limit: 10 });
+     * ```
+     */
+    list(params?: ListListsParams): Promise<PaginatedList<ContactList>>;
+    /**
+     * Get a contact list by ID.
+     *
+     * @param id - List ID
+     * @returns Contact list record
+     *
+     * @example
+     * ```ts
+     * const list = await mailbreeze.lists.get("list_xxx");
+     * ```
+     */
+    get(id: string): Promise<ContactList>;
+    /**
+     * Update a contact list.
+     *
+     * @param id - List ID
+     * @param params - Fields to update
+     * @returns Updated list record
+     *
+     * @example
+     * ```ts
+     * const list = await mailbreeze.lists.update("list_xxx", {
+     *   name: "Updated List Name",
+     * });
+     * ```
+     */
+    update(id: string, params: UpdateListParams): Promise<ContactList>;
+    /**
+     * Delete a contact list.
+     *
+     * Warning: This will also delete all contacts in the list.
+     *
+     * @param id - List ID
+     * @returns void
+     *
+     * @example
+     * ```ts
+     * await mailbreeze.lists.delete("list_xxx");
+     * ```
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Get statistics for a contact list.
+     *
+     * @param id - List ID
+     * @returns List statistics
+     *
+     * @example
+     * ```ts
+     * const stats = await mailbreeze.lists.stats("list_xxx");
+     * console.log(`Active: ${stats.activeContacts}, Bounced: ${stats.bouncedContacts}`);
+     * ```
+     */
+    stats(id: string): Promise<ListStats>;
+}
+
+/**
+ * Email verification services.
+ *
+ * Verify email addresses before sending to reduce bounces
+ * and protect sender reputation.
+ *
+ * @example
+ * ```ts
+ * // Verify a single email
+ * const result = await mailbreeze.verification.verify("user@example.com");
+ * if (result.isValid) {
+ *   // Safe to send
+ * }
+ *
+ * // Batch verification
+ * const batch = await mailbreeze.verification.batch({
+ *   emails: ["user1@example.com", "user2@example.com"],
+ * });
+ *
+ * // Poll for results
+ * const status = await mailbreeze.verification.get(batch.verificationId);
+ * ```
+ */
+declare class Verification extends BaseResource {
+    /**
+     * Verify a single email address.
+     *
+     * This is a synchronous operation - the result is returned immediately.
+     * Results are cached for 24 hours.
+     *
+     * @param email - Email address to verify
+     * @returns Verification result
+     *
+     * @example
+     * ```ts
+     * const result = await mailbreeze.verification.verify("test@example.com");
+     * console.log(result.isValid); // true
+     * console.log(result.result); // "valid"
+     * console.log(result.details?.isDisposable); // false
+     * ```
+     */
+    verify(email: string): Promise<VerifyEmailResult>;
+    /**
+     * Start batch verification.
+     *
+     * Submits a batch of emails for verification. For large batches,
+     * results are processed asynchronously - poll with `get()` for status.
+     *
+     * If all emails are cached, results are returned immediately.
+     *
+     * @param params - Batch parameters including emails array
+     * @returns Batch verification result with ID for polling
+     *
+     * @example
+     * ```ts
+     * const batch = await mailbreeze.verification.batch({
+     *   emails: ["user1@example.com", "user2@example.com", "user3@example.com"],
+     * });
+     *
+     * if (batch.results) {
+     *   // All cached - results available immediately
+     *   console.log(batch.results);
+     * } else {
+     *   // Poll for results
+     *   const status = await mailbreeze.verification.get(batch.verificationId);
+     * }
+     * ```
+     */
+    batch(params: BatchVerifyParams): Promise<BatchVerifyResult>;
+    /**
+     * Get verification batch status and results.
+     *
+     * @param verificationId - Verification batch ID
+     * @returns Current status and results when complete
+     *
+     * @example
+     * ```ts
+     * const status = await mailbreeze.verification.get("ver_xxx");
+     * if (status.status === "completed") {
+     *   console.log(status.results);
+     *   console.log(status.analytics);
+     * }
+     * ```
+     */
+    get(verificationId: string): Promise<VerificationStatus>;
+    /**
+     * List verification batches.
+     *
+     * @param params - Filter and pagination options
+     * @returns Paginated list of verification batches
+     *
+     * @example
+     * ```ts
+     * const { data, pagination } = await mailbreeze.verification.list({
+     *   status: "completed",
+     *   page: 1,
+     * });
+     * ```
+     */
+    list(params?: ListVerificationsParams): Promise<PaginatedList<VerificationStatus>>;
+    /**
+     * Get verification statistics.
+     *
+     * @returns Aggregate verification stats
+     *
+     * @example
+     * ```ts
+     * const stats = await mailbreeze.verification.stats();
+     * console.log(`Verified: ${stats.totalVerified}, Valid: ${stats.valid}`);
+     * ```
+     */
+    stats(): Promise<VerificationStats>;
+}
+
+/**
+ * MailBreeze SDK client.
+ *
+ * Create a client with your API key to access all MailBreeze APIs.
+ *
+ * @example
+ * ```ts
+ * import { MailBreeze } from "mailbreeze";
+ *
+ * const mailbreeze = new MailBreeze({
+ *   apiKey: "sk_live_xxx",
+ * });
+ *
+ * // Send an email
+ * const result = await mailbreeze.emails.send({
+ *   from: "hello@yourdomain.com",
+ *   to: "user@example.com",
+ *   subject: "Hello!",
+ *   html: "<h1>Welcome!</h1>",
+ * });
+ *
+ * // Create a contact
+ * const contacts = mailbreeze.contacts("list_xxx");
+ * const contact = await contacts.create({
+ *   email: "user@example.com",
+ *   firstName: "John",
+ * });
+ * ```
+ */
+declare class MailBreeze {
+    /**
+     * Email sending and management.
+     */
+    readonly emails: Emails;
+    /**
+     * Email attachment handling.
+     */
+    readonly attachments: Attachments;
+    /**
+     * Contact list management.
+     */
+    readonly lists: Lists;
+    /**
+     * Email verification services.
+     */
+    readonly verification: Verification;
+    /**
+     * Automation enrollment management.
+     */
+    readonly automations: Automations;
+    private readonly fetcher;
+    private readonly domainId?;
+    /**
+     * Create a new MailBreeze client.
+     *
+     * @param config - Client configuration
+     *
+     * @example
+     * ```ts
+     * // Basic usage
+     * const mailbreeze = new MailBreeze({
+     *   apiKey: "sk_live_xxx",
+     * });
+     *
+     * // With custom options
+     * const mailbreeze = new MailBreeze({
+     *   apiKey: "sk_live_xxx",
+     *   baseUrl: "https://api.eu.mailbreeze.com",
+     *   timeout: 60000,
+     *   maxRetries: 5,
+     * });
+     * ```
+     */
+    constructor(config: MailBreezeConfig);
+    /**
+     * Get a contacts resource for a specific list.
+     *
+     * @param listId - Contact list ID
+     * @returns Contacts resource bound to the list
+     *
+     * @example
+     * ```ts
+     * const contacts = mailbreeze.contacts("list_xxx");
+     *
+     * // Create a contact in this list
+     * const contact = await contacts.create({
+     *   email: "user@example.com",
+     * });
+     *
+     * // List contacts in this list
+     * const { data } = await contacts.list();
+     * ```
+     */
+    contacts(listId: string): Contacts;
+}
+
+/**
+ * Base error class for all MailBreeze SDK errors.
+ * All API-related errors extend from this class.
+ */
+declare class MailBreezeError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    /** HTTP status code (if applicable) */
+    readonly statusCode?: number;
+    /** Unique request ID for debugging with support */
+    readonly requestId?: string;
+    /** Additional error details (e.g., field-level validation errors) */
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, statusCode?: number, requestId?: string, details?: Record<string, unknown>);
+    /**
+     * Serialize error to JSON-friendly object.
+     * Useful for logging and error reporting.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Authentication failed (401).
+ * Thrown when API key is missing, invalid, or expired.
+ */
+declare class AuthenticationError extends MailBreezeError {
+    constructor(message: string, code?: string, requestId?: string);
+}
+/**
+ * Validation failed (400).
+ * Thrown when request data fails validation.
+ */
+declare class ValidationError extends MailBreezeError {
+    constructor(message: string, code?: string, requestId?: string, details?: Record<string, unknown>);
+}
+/**
+ * Resource not found (404).
+ * Thrown when the requested resource does not exist.
+ */
+declare class NotFoundError extends MailBreezeError {
+    constructor(message: string, code?: string, requestId?: string);
+}
+/**
+ * Rate limit exceeded (429).
+ * Thrown when too many requests are made in a time window.
+ */
+declare class RateLimitError extends MailBreezeError {
+    /** Seconds to wait before retrying */
+    readonly retryAfter?: number;
+    constructor(message: string, code?: string, requestId?: string, retryAfter?: number);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Server error (5xx).
+ * Thrown when the API encounters an internal error.
+ */
+declare class ServerError extends MailBreezeError {
+    constructor(message: string, code?: string, statusCode?: number, requestId?: string);
+}
+
+export { type Attachment, AuthenticationError, type BatchVerifyParams, type BatchVerifyResult, type CancelEnrollmentResult, type ConfirmAttachmentParams, type Contact, type ContactList, type CreateAttachmentUploadParams, type CreateAttachmentUploadResult, type CreateContactParams, type CreateListParams, type CustomFieldDefinition, type DomainContext, type Email, type EmailStats, type EnrollParams, type EnrollResult, type Enrollment, type ListContactsParams, type ListEmailsParams, type ListEnrollmentsParams, type ListListsParams, type ListParams, type ListStats, type ListVerificationsParams, MailBreeze, type MailBreezeConfig, MailBreezeError, NotFoundError, type PaginatedList, type Pagination, RateLimitError, type SendEmailParams, type SendEmailResult, ServerError, type SuppressReason, type UpdateContactParams, type UpdateListParams, ValidationError, type VerificationStats, type VerificationStatus, type VerifyEmailResult };