mailtea-sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,960 @@
+/** A stored-template reference, used in place of inline `html`/`text`. */
+interface TemplateRef {
+    id: string;
+    variables?: Record<string, string | number>;
+}
+/** Input for `emails.send`. Provide inline content (`html`/`text`) OR a `template`. */
+interface SendEmailInput {
+    from: string;
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    template?: TemplateRef;
+    cc?: string | string[];
+    bcc?: string | string[];
+    reply_to?: string | string[];
+    /** ISO 8601 datetime to schedule the send. */
+    scheduled_at?: string;
+    tags?: Array<{
+        name: string;
+        value: string;
+    }>;
+    headers?: Record<string, string>;
+    attachments?: Array<{
+        filename: string;
+        /** Base64-encoded file content. */
+        content: string;
+        content_type?: string;
+        content_id?: string;
+    }>;
+}
+/** One item in an `emails.batch` call — like `SendEmailInput` minus attachments/scheduling. */
+type BatchEmailItemInput = Omit<SendEmailInput, "attachments" | "scheduled_at">;
+/** Input for `emails.batch` (1–100 items). */
+type BatchEmailInput = BatchEmailItemInput[];
+/** Input for `emails.update` — currently only a reschedule. */
+interface UpdateEmailInput {
+    scheduled_at: string;
+}
+interface SendEmailResponse {
+    id: string;
+}
+interface BatchEmailResponse {
+    data: {
+        id: string;
+    }[];
+}
+interface UpdateEmailResponse {
+    object: "email";
+    id: string;
+}
+interface CancelEmailResponse {
+    object: "email";
+    id: string;
+}
+/**
+ * Email lifecycle status. Mirrors the API's `last_event`. The open string union
+ * keeps autocomplete for known values while tolerating new ones.
+ */
+type EmailStatus = "queued" | "scheduled" | "sent" | "delivered" | "delivery_delayed" | "bounced" | "complained" | "failed" | "suppressed" | "canceled" | (string & {});
+interface EmailTag {
+    name: string;
+    value: string;
+}
+interface EmailAttachmentMeta {
+    filename: string;
+    content_type: string;
+    size: number;
+}
+/**
+ * Shape returned by `emails.get(id)`. Date fields are ISO 8601 strings on the
+ * wire. `status` is a friendly alias the SDK derives from `last_event`.
+ */
+interface RetrievedEmail {
+    object: "email";
+    id: string;
+    from: string | null;
+    to: string | null;
+    cc: string | null;
+    bcc: string | null;
+    reply_to: string | null;
+    subject: string;
+    html: string | null;
+    text: string | null;
+    created_at: string | null;
+    scheduled_at: string | null;
+    /** Most recent delivery event (the raw API wire field). */
+    last_event: EmailStatus | null;
+    /** Friendly alias of `last_event`. */
+    status: EmailStatus | null;
+    delayed_at: string | null;
+    opened_at: string | null;
+    open_count: number;
+    clicked_at: string | null;
+    click_count: number;
+    tags: EmailTag[] | null;
+    headers: Record<string, string> | null;
+    attachments: EmailAttachmentMeta[];
+}
+/** A lightweight email row returned by `emails.list` (no body/attachments). */
+interface EmailListItem {
+    object: "email";
+    id: string;
+    from: string | null;
+    to: string | null;
+    subject: string;
+    created_at: string | null;
+    scheduled_at: string | null;
+    last_event: EmailStatus | null;
+    open_count: number;
+    click_count: number;
+    tags: EmailTag[] | null;
+}
+/** Filters + offset pagination for `emails.list`. */
+interface ListEmailsParams {
+    status?: EmailStatus;
+    tag_name?: string;
+    tag_value?: string;
+    /** ISO 8601 lower bound on `created_at`. */
+    from_date?: string;
+    /** ISO 8601 upper bound on `created_at`. */
+    to_date?: string;
+    /** Max results, 1–100 (default 50). */
+    limit?: number;
+    offset?: number;
+}
+/** Offset-paginated list returned by `emails.list`. */
+interface EmailListResponse {
+    object: "list";
+    data: EmailListItem[];
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+/** Optional date window for `emails.analytics`. */
+interface EmailAnalyticsParams {
+    /** ISO 8601 lower bound on `created_at`. */
+    from_date?: string;
+    /** ISO 8601 upper bound on `created_at`. */
+    to_date?: string;
+}
+/** Aggregate transactional metrics returned by `emails.analytics`. */
+interface EmailAnalytics {
+    object: "analytics";
+    from_date: string | null;
+    to_date: string | null;
+    /** Emails created in the window. */
+    total: number;
+    /** Emails dispatched to the provider (total minus queued/scheduled/canceled); the rate denominator. */
+    sent: number;
+    delivered: number;
+    bounced: number;
+    /** Distinct emails with at least one open / click. */
+    opened: number;
+    clicked: number;
+    /** Sum of open / click events. */
+    total_opens: number;
+    total_clicks: number;
+    status_counts: Record<string, number>;
+    rates: {
+        /** delivered / sent */
+        delivery_rate: number;
+        /** bounced / sent */
+        bounce_rate: number;
+        /** opened / sent */
+        open_rate: number;
+        /** clicked / sent */
+        click_rate: number;
+    };
+}
+
+type RequestFn = <T>(method: string, path: string, body?: unknown) => Promise<T>;
+/** Standard list-response envelope used by the audience endpoints. */
+interface ListResponse<T> {
+    object: "list";
+    data: T[];
+    has_more: boolean;
+    next_cursor?: string;
+}
+/** Standard delete-response envelope. */
+interface DeletedResponse {
+    object: string;
+    id: string;
+    deleted: true;
+}
+
+/** A lightweight inbound-email row returned by `emails.inbound.list` (no body/attachments). */
+interface InboundEmailListItem {
+    /** Inbound email id (`rxemail_…`). */
+    id: string;
+    from: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    reply_to: string[];
+    subject: string;
+    message_id: string | null;
+    created_at: string;
+}
+/** Attachment metadata embedded in {@link RetrievedInboundEmail} (no download URL). */
+interface InboundAttachmentMeta {
+    /** Attachment id (`rxatt_…`). */
+    id: string;
+    filename: string;
+    content_type: string;
+    content_disposition: string | null;
+    content_id: string | null;
+    size: number;
+}
+/** Shape returned by `emails.inbound.get(id)`. Date fields are ISO 8601 strings on the wire. */
+interface RetrievedInboundEmail {
+    object: "email";
+    /** Inbound email id (`rxemail_…`). */
+    id: string;
+    from: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    reply_to: string[];
+    subject: string;
+    message_id: string | null;
+    in_reply_to: string | null;
+    references: string[];
+    html: string | null;
+    text: string | null;
+    headers: Record<string, string> | null;
+    created_at: string;
+    /** Short-lived signed URL to download the raw RFC 822 message. */
+    raw: {
+        download_url: string;
+        expires_at: string;
+    };
+    attachments: InboundAttachmentMeta[];
+}
+/**
+ * A downloadable inbound attachment, returned by `emails.inbound.attachments`.
+ * `object` is present on `get` and omitted from `list` rows.
+ */
+interface InboundAttachment {
+    object?: "attachment";
+    /** Attachment id (`rxatt_…`). */
+    id: string;
+    filename: string;
+    content_type: string;
+    content_disposition: string | null;
+    content_id: string | null;
+    size: number;
+    /** Short-lived signed URL to download the file; expires at `expires_at`. */
+    download_url: string;
+    expires_at: string;
+}
+/** Cursor pagination for `emails.inbound.list`. */
+interface ListInboundEmailsParams {
+    publication_id: string;
+    /** Max results, 1–100 (default 20). */
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * Input for `emails.inbound.reply`. Provide at least one of `html`/`text`.
+ *
+ * Threading (In-Reply-To / References), the reply target (To), and the `Re: `
+ * subject default are all derived by the server from the original inbound email
+ * — they are never accepted from the caller. Omit `from` to send from the
+ * verified email-purpose domain the mail was delivered to.
+ */
+interface InboundReplyInput {
+    from?: {
+        email: string;
+        name?: string;
+    };
+    subject?: string;
+    html?: string;
+    text?: string;
+    cc?: string[];
+    bcc?: string[];
+    idempotency_key?: string;
+}
+/** Response from `emails.inbound.reply`: the resulting transactional email (`txemail_…`). */
+interface InboundReplyResponse {
+    /** Transactional email id (`txemail_…`). */
+    id: string;
+    status: string;
+}
+/**
+ * Attachments on a received email. Access via `mailtea.emails.inbound.attachments`.
+ * Each returned object carries a short-lived signed `download_url`.
+ */
+declare class InboundAttachments {
+    private readonly request;
+    constructor(request: RequestFn);
+    /** List an inbound email's attachments, each with a signed download URL. */
+    list(id: string): Promise<ListResponse<InboundAttachment>>;
+    /** Retrieve a single inbound attachment with a signed download URL. */
+    get(id: string, attachmentId: string): Promise<InboundAttachment>;
+}
+/**
+ * Inbound (received) emails. Access via `mailtea.emails.inbound`. List and
+ * retrieve mail delivered to your receiving domains, download attachments, and
+ * `reply()` — which threads correctly by construction and reuses the
+ * transactional send pipeline.
+ */
+declare class InboundEmails {
+    private readonly request;
+    /** Attachments on a received email. */
+    readonly attachments: InboundAttachments;
+    constructor(request: RequestFn);
+    /** List received emails in a publication (most recent first), cursor-paginated. */
+    list(params: ListInboundEmailsParams): Promise<ListResponse<InboundEmailListItem>>;
+    /** Retrieve a single received email, including its body, headers, and attachments. */
+    get(id: string): Promise<RetrievedInboundEmail>;
+    /**
+     * Reply to a received email. The reply target, threading headers, and the
+     * `Re: ` subject default are all server-derived — pass only the content.
+     *
+     * @returns the resulting transactional email's `id` and `status` (HTTP 202).
+     */
+    reply(id: string, input: InboundReplyInput): Promise<InboundReplyResponse>;
+}
+
+/**
+ * The `emails` resource. Access via `mailtea.emails`.
+ */
+declare class Emails {
+    private readonly request;
+    /** Inbound (received) emails: list, get, reply, and attachments. */
+    readonly inbound: InboundEmails;
+    constructor(request: RequestFn);
+    /**
+     * Send a transactional email.
+     *
+     * Provide either inline content (`html` and/or `text`) **or** a `template`
+     * reference — not both. `to`, `cc`, `bcc`, and `reply_to` each accept a single
+     * address or an array.
+     *
+     * @returns the new email's `id`.
+     */
+    send(payload: SendEmailInput): Promise<SendEmailResponse>;
+    /**
+     * Send up to 100 emails in a single request. Batch items do not support
+     * `attachments` or `scheduled_at`.
+     *
+     * @returns `{ data: [{ id }, ...] }` in request order.
+     */
+    batch(payload: BatchEmailInput): Promise<BatchEmailResponse>;
+    /**
+     * List transactional emails (most recent first), optionally filtered by
+     * status, tags, or a `created_at` date range, and offset-paginated.
+     *
+     * @returns `{ data, total, limit, offset, has_more }`.
+     */
+    list(params?: ListEmailsParams): Promise<EmailListResponse>;
+    /**
+     * Aggregate transactional metrics over an optional date window: totals,
+     * delivered/bounced/open/click counts, per-status counts, and rates.
+     */
+    analytics(params?: EmailAnalyticsParams): Promise<EmailAnalytics>;
+    /**
+     * Retrieve a single email with its current delivery status and tracking
+     * counters. The returned object exposes both `last_event` (the raw wire field)
+     * and a friendly `status` alias.
+     */
+    get(id: string): Promise<RetrievedEmail>;
+    /**
+     * Update a scheduled email — currently only its `scheduled_at`. Only emails
+     * still in the `scheduled` state can be updated.
+     */
+    update(id: string, payload: UpdateEmailInput): Promise<UpdateEmailResponse>;
+    /**
+     * Convenience wrapper over {@link Emails.update} for the common reschedule
+     * case.
+     *
+     * @param scheduledAt ISO 8601 datetime string.
+     */
+    reschedule(id: string, scheduledAt: string): Promise<UpdateEmailResponse>;
+    /** Cancel a scheduled email before it sends. */
+    cancel(id: string): Promise<CancelEmailResponse>;
+}
+
+type ContactStatus = "active" | "unsubscribed" | "suppressed";
+interface Contact {
+    object: "contact";
+    id: string;
+    publication_id: string;
+    email: string;
+    status: ContactStatus;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateContactInput {
+    publication_id: string;
+    email: string;
+    status?: ContactStatus;
+}
+interface UpdateContactInput {
+    publication_id: string;
+    status?: ContactStatus;
+}
+interface ListContactsParams {
+    publication_id: string;
+    limit?: number;
+    after?: string;
+    status?: ContactStatus;
+    search?: string;
+}
+/** The `contacts` resource. Access via `mailtea.contacts`. */
+declare class Contacts {
+    private readonly request;
+    constructor(request: RequestFn);
+    /** Create (or upsert) a contact in a publication. */
+    create(input: CreateContactInput): Promise<Contact>;
+    /** List contacts in a publication. Supports cursor pagination via `after`. */
+    list(params: ListContactsParams): Promise<ListResponse<Contact>>;
+    /** Retrieve a single contact by id or email. */
+    get(idOrEmail: string, params: {
+        publication_id: string;
+    }): Promise<Contact>;
+    /** Update a contact's status. */
+    update(idOrEmail: string, input: UpdateContactInput): Promise<Contact>;
+    /** Delete a contact by id or email. */
+    delete(idOrEmail: string, params: {
+        publication_id: string;
+    }): Promise<DeletedResponse>;
+}
+
+interface Segment {
+    object: "segment";
+    id: string;
+    publication_id: string;
+    name: string;
+    description: string;
+    status_filter: ContactStatus | null;
+    query_filter: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateSegmentInput {
+    publication_id: string;
+    name: string;
+    description?: string;
+    status_filter?: ContactStatus;
+    query_filter?: string;
+}
+interface UpdateSegmentInput {
+    publication_id: string;
+    name?: string;
+    description?: string;
+    status_filter?: ContactStatus | null;
+    query_filter?: string | null;
+}
+interface ListSegmentsParams {
+    publication_id: string;
+    limit?: number;
+    after?: string;
+}
+/** The `segments` resource. Access via `mailtea.segments`. */
+declare class Segments {
+    private readonly request;
+    constructor(request: RequestFn);
+    /** Create a segment. */
+    create(input: CreateSegmentInput): Promise<Segment>;
+    /** List segments in a publication. */
+    list(params: ListSegmentsParams): Promise<ListResponse<Segment>>;
+    /** Retrieve a single segment. */
+    get(id: string, params: {
+        publication_id: string;
+    }): Promise<Segment>;
+    /** Update a segment. */
+    update(id: string, input: UpdateSegmentInput): Promise<Segment>;
+    /** Delete a segment. */
+    delete(id: string, params: {
+        publication_id: string;
+    }): Promise<DeletedResponse>;
+}
+
+type TagSubscription = "opt_in" | "opt_out";
+type TagVisibility = "public" | "private";
+interface Tag {
+    object: "tag";
+    id: string;
+    publication_id: string;
+    name: string;
+    description: string;
+    default_subscription: TagSubscription;
+    visibility: TagVisibility;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateTagInput {
+    publication_id: string;
+    name: string;
+    default_subscription: TagSubscription;
+    description?: string;
+    visibility?: TagVisibility;
+}
+interface UpdateTagInput {
+    publication_id: string;
+    name?: string;
+    description?: string;
+    default_subscription?: TagSubscription;
+    visibility?: TagVisibility;
+}
+interface ListTagsParams {
+    publication_id: string;
+    limit?: number;
+    after?: string;
+}
+/** The `tags` resource. Access via `mailtea.tags`. */
+declare class Tags {
+    private readonly request;
+    constructor(request: RequestFn);
+    /** Create a tag. */
+    create(input: CreateTagInput): Promise<Tag>;
+    /** List tags in a publication. */
+    list(params: ListTagsParams): Promise<ListResponse<Tag>>;
+    /** Retrieve a single tag. */
+    get(id: string, params: {
+        publication_id: string;
+    }): Promise<Tag>;
+    /** Update a tag. */
+    update(id: string, input: UpdateTagInput): Promise<Tag>;
+    /** Delete a tag. */
+    delete(id: string, params: {
+        publication_id: string;
+    }): Promise<DeletedResponse>;
+}
+
+/** Input for `posts.sendTest`. */
+interface SendPostTestInput {
+    /** Up to 10 test recipients (yourself / teammates). */
+    recipients: string[];
+    /** Sender, e.g. `"Acme <hello@acme.com>"`. Must use a verified domain. */
+    from: string;
+    reply_to?: string;
+}
+/** Result of `posts.sendTest`. */
+interface PostTestSendResult {
+    object: "test_send";
+    id: string;
+    sent_at: string;
+    from: string;
+    sent_to: string[];
+    failed_to: Array<{
+        address: string;
+        reason: string;
+    }>;
+}
+/** Input for `posts.create`. */
+interface CreatePostInput {
+    /** Publication the post belongs to. */
+    publication_id: string;
+    /** Subject line (also the post's working title). */
+    subject: string;
+    /**
+     * Seed the post from a published server template (see the `templates` tools).
+     * Provide this OR `html` — not both. `{{variables}}` are substituted.
+     */
+    template_id?: string;
+    /** Values substituted into the template's `{{variable}}` placeholders. */
+    variables?: Record<string, string | number>;
+    /** Inline HTML body (use this OR `template_id`). */
+    html?: string;
+    /** `newsletter` (default, can publish to the site) or `broadcast` (email-only). */
+    kind?: "newsletter" | "broadcast";
+    /** Send right after creating (requires the `issues:send` scope). */
+    send?: boolean;
+    /** ISO-8601; with `send`, schedules the send instead of sending now. */
+    scheduled_at?: string;
+}
+/** Result of `posts.create`. */
+interface CreatePostResult {
+    /** The new post's id. */
+    id: string;
+}
+/**
+ * The `posts` resource (newsletter posts/issues). Access via `mailtea.posts`.
+ */
+declare class Posts {
+    private readonly request;
+    constructor(request: RequestFn);
+    /**
+     * Create a newsletter post (draft by default). Seed it from a published
+     * server template with `template_id` + `variables`, or pass inline `html`.
+     * Set `send: true` to deliver immediately (or with `scheduled_at` to
+     * schedule) — that requires the `issues:send` scope. Returns `{ id }`.
+     */
+    create(input: CreatePostInput): Promise<CreatePostResult>;
+    /**
+     * Send a TEST copy of a post to specific recipients to check it before
+     * subscribers see it. Renders the post exactly as a subscriber would receive
+     * it and delivers a one-shot `[TEST]` email — it does NOT send to the
+     * audience. Returns `{ sent_to, failed_to }`.
+     */
+    sendTest(id: string, input: SendPostTestInput): Promise<PostTestSendResult>;
+}
+
+type DomainStatus = "pending" | "verified";
+type DomainPurpose = "email" | "site" | "both";
+interface DomainRecord {
+    record?: string;
+    type: string;
+    name: string;
+    value: string;
+    status: DomainStatus;
+}
+interface Domain {
+    object: "domain";
+    id: string;
+    publication_id: string;
+    name: string;
+    status: DomainStatus;
+    purpose: DomainPurpose;
+    is_primary: boolean;
+    proxy_target: string;
+    /** DNS records to add before verifying. Present on create/get/verify. */
+    records?: DomainRecord[];
+    verified_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateDomainInput {
+    publication_id: string;
+    name: string;
+    /** Use `email` or `both` for a sending `from` domain. Defaults to `site`. */
+    purpose?: DomainPurpose;
+    is_primary?: boolean;
+    proxy_target?: string;
+}
+interface UpdateDomainInput {
+    publication_id: string;
+    purpose?: DomainPurpose;
+    is_primary?: boolean;
+    proxy_target?: string;
+}
+interface ListDomainsParams {
+    publication_id: string;
+    limit?: number;
+    after?: string;
+}
+interface TrackingDomain {
+    object: "tracking_domain";
+    id: string;
+    domain_id: string;
+    subdomain: string;
+    full_name: string;
+    status: DomainStatus;
+    /** The CNAME record to add. Present on create/verify. */
+    records?: DomainRecord[];
+    verified_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateTrackingDomainInput {
+    publication_id: string;
+    /** Sub-domain label (lowercase alphanumeric and hyphens), e.g. `links`. */
+    subdomain: string;
+}
+/**
+ * Tracking sub-domains (CNAME) under a domain — used to serve open-pixel and
+ * click-tracking links from your own domain. Access via `mailtea.domains.tracking`.
+ */
+declare class TrackingDomains {
+    private readonly request;
+    constructor(request: RequestFn);
+    /** Add a tracking sub-domain. The response `records` lists the CNAME to add. */
+    create(domainId: string, input: CreateTrackingDomainInput): Promise<TrackingDomain>;
+    /** List tracking sub-domains for a domain. */
+    list(domainId: string, params: {
+        publication_id: string;
+    }): Promise<{
+        object: "list";
+        data: TrackingDomain[];
+    }>;
+    /** Verify a tracking sub-domain by checking its CNAME record. */
+    verify(domainId: string, trackingDomainId: string, params: {
+        publication_id: string;
+    }): Promise<TrackingDomain>;
+    /** Delete a tracking sub-domain. */
+    delete(domainId: string, trackingDomainId: string, params: {
+        publication_id: string;
+    }): Promise<DeletedResponse>;
+}
+/**
+ * The `domains` resource (email/site sending domains). Access via
+ * `mailtea.domains`. Register a domain, add the returned DNS `records`, then
+ * `verify()` it before sending from it.
+ */
+declare class Domains {
+    private readonly request;
+    /** Tracking sub-domains (CNAME) under a domain. */
+    readonly tracking: TrackingDomains;
+    constructor(request: RequestFn);
+    /** Register a domain. The response `records` lists the DNS records to add. */
+    create(input: CreateDomainInput): Promise<Domain>;
+    /** List domains in a publication. */
+    list(params: ListDomainsParams): Promise<ListResponse<Domain>>;
+    /** Retrieve a single domain, including its DNS `records`. */
+    get(id: string, params: {
+        publication_id: string;
+    }): Promise<Domain>;
+    /** Verify a domain by checking its DNS records; `status` becomes `verified`. */
+    verify(id: string, params: {
+        publication_id: string;
+    }): Promise<Domain>;
+    /** Update a domain's purpose, primary flag, or proxy target. */
+    update(id: string, input: UpdateDomainInput): Promise<Domain>;
+    /** Delete a domain. */
+    delete(id: string, params: {
+        publication_id: string;
+    }): Promise<DeletedResponse>;
+}
+
+type WebhookStatus = "enabled" | "disabled";
+type WebhookEvent = "email.received" | "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.bounced" | "email.complained" | "email.opened" | "email.clicked" | "email.failed" | "email.suppressed" | "contact.created" | "contact.updated" | "contact.deleted" | "contact.unsubscribed";
+interface Webhook {
+    object: "webhook";
+    id: string;
+    publication_id: string;
+    endpoint: string;
+    events: WebhookEvent[];
+    /** Returned only on create — store it to verify payload signatures. */
+    signing_secret?: string;
+    status: WebhookStatus;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateWebhookInput {
+    publication_id: string;
+    endpoint: string;
+    events: WebhookEvent[];
+}
+interface UpdateWebhookInput {
+    publication_id: string;
+    endpoint?: string;
+    events?: WebhookEvent[];
+    status?: WebhookStatus;
+}
+interface ListWebhooksParams {
+    publication_id: string;
+    limit?: number;
+    after?: string;
+}
+/**
+ * The `webhooks` resource (outbound event subscriptions). Access via
+ * `mailtea.webhooks`. `create()` returns the `signing_secret` once.
+ */
+declare class Webhooks {
+    private readonly request;
+    constructor(request: RequestFn);
+    /** Create a webhook. The response `signing_secret` is returned only once. */
+    create(input: CreateWebhookInput): Promise<Webhook>;
+    /** List webhooks in a publication (signing secrets omitted). */
+    list(params: ListWebhooksParams): Promise<ListResponse<Webhook>>;
+    /** Retrieve a single webhook. */
+    get(id: string, params: {
+        publication_id: string;
+    }): Promise<Webhook>;
+    /** Update a webhook's endpoint, events, or enabled/disabled status. */
+    update(id: string, input: UpdateWebhookInput): Promise<Webhook>;
+    /** Delete a webhook. */
+    delete(id: string, params: {
+        publication_id: string;
+    }): Promise<DeletedResponse>;
+}
+
+type ContactPropertyType = "string" | "number";
+interface ContactProperty {
+    object: "contact_property";
+    id: string;
+    key: string;
+    type: ContactPropertyType;
+    fallback_value: string | null;
+    description: string;
+    created_at: string;
+}
+interface CreateContactPropertyInput {
+    key: string;
+    type: ContactPropertyType;
+    fallback_value?: string | number;
+    description?: string;
+}
+interface UpdateContactPropertyInput {
+    /** Pass `null` to clear the fallback. */
+    fallback_value?: string | number | null;
+    description?: string;
+}
+interface ListContactPropertiesParams {
+    limit?: number;
+    after?: string;
+}
+/**
+ * The `contactProperties` resource (custom contact fields). Access via
+ * `mailtea.contactProperties`. Definitions are team-scoped — no
+ * `publication_id`.
+ */
+declare class ContactProperties {
+    private readonly request;
+    constructor(request: RequestFn);
+    /** Define a custom contact property. */
+    create(input: CreateContactPropertyInput): Promise<ContactProperty>;
+    /** List the team's custom contact property definitions. */
+    list(params?: ListContactPropertiesParams): Promise<ListResponse<ContactProperty>>;
+    /** Update a property's fallback value or description. */
+    update(id: string, input: UpdateContactPropertyInput): Promise<ContactProperty>;
+    /** Delete a custom contact property. */
+    delete(id: string): Promise<DeletedResponse>;
+}
+
+type ApiKeyPermission = "full_access" | "sending_access";
+interface CreateApiKeyInput {
+    /** A label for the key. 1–50 characters. */
+    name: string;
+    /** Access level. Defaults to `full_access`. */
+    permission?: ApiKeyPermission;
+    /** Publication to scope a `sending_access` key to. */
+    domain_id?: string;
+}
+interface CreatedApiKey {
+    id: string;
+    /** The full token — returned ONCE on creation. Store it securely. */
+    token: string;
+}
+interface ApiKeyListItem {
+    id: string;
+    name: string;
+    created_at: string;
+}
+/**
+ * The `apiKeys` resource. Access via `mailtea.apiKeys`. Requires a token with
+ * `settings:write`; a key can never be granted scopes the calling token does
+ * not already hold.
+ */
+declare class ApiKeys {
+    private readonly request;
+    constructor(request: RequestFn);
+    /**
+     * Create an API key. The `token` is returned ONCE — store it securely. The
+     * calling token must already hold every scope the new key would grant.
+     */
+    create(input: CreateApiKeyInput): Promise<CreatedApiKey>;
+    /** List API keys (token values are never returned). */
+    list(): Promise<{
+        data: ApiKeyListItem[];
+    }>;
+    /** Revoke (delete) an API key by id. */
+    revoke(id: string): Promise<void>;
+}
+
+interface MailteaOptions {
+    /** API key (`mt_pat_...` or `mt_svc_...`). Falls back to `MAILTEA_API_KEY`. */
+    apiKey?: string;
+    /** API base URL. Defaults to `https://api.mailtea.app`. */
+    baseUrl?: string;
+    /** Custom `fetch` implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * The Mailtea client. Construct it with an API key, then use its resources:
+ *
+ * ```ts
+ * import { Mailtea } from "mailtea-sdk";
+ *
+ * const mailtea = new Mailtea(process.env.MAILTEA_API_KEY);
+ * const { id } = await mailtea.emails.send({
+ *   from: "you@yourdomain.com",
+ *   to: "recipient@example.com",
+ *   subject: "Hello",
+ *   html: "<p>Sent with Mailtea.</p>"
+ * });
+ * ```
+ *
+ * The API key can be passed as a string, inside an options object, or omitted
+ * to read `MAILTEA_API_KEY` from the environment.
+ */
+declare class Mailtea {
+    /** The `emails` resource: send, batch, get, update, reschedule, cancel. */
+    readonly emails: Emails;
+    /** The `contacts` resource: create, list, get, update, delete. */
+    readonly contacts: Contacts;
+    /** The `segments` resource: create, list, get, update, delete. */
+    readonly segments: Segments;
+    /** The `tags` resource: create, list, get, update, delete. */
+    readonly tags: Tags;
+    /** The `posts` resource: sendTest (newsletter posts). */
+    readonly posts: Posts;
+    /** The `domains` resource: create, list, get, verify, update, delete. */
+    readonly domains: Domains;
+    /** The `webhooks` resource: create, list, get, update, delete. */
+    readonly webhooks: Webhooks;
+    /** The `contactProperties` resource: create, list, update, delete. */
+    readonly contactProperties: ContactProperties;
+    /** The `apiKeys` resource: create, list, revoke. */
+    readonly apiKeys: ApiKeys;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(apiKeyOrOptions?: string | MailteaOptions, maybeOptions?: MailteaOptions);
+    /** @internal Issue an authenticated request and map errors to MailteaError. */
+    private request;
+}
+
+interface MailteaErrorInit {
+    /** HTTP status code, or `0` for client-side errors raised before a request. */
+    status: number;
+    /** Machine-readable code, when available (e.g. `missing_api_key`). */
+    code?: string;
+    /** Structured error payload from the API (e.g. Zod validation issues on 400). */
+    details?: unknown;
+    /** Value of the `x-request-id` response header, useful for support. */
+    requestId?: string;
+}
+/**
+ * Error thrown by the Mailtea SDK for both client-side problems (missing API
+ * key, no `fetch`) and non-2xx API responses. Inspect `status` and `details`
+ * to branch on validation vs. auth vs. not-found errors.
+ */
+declare class MailteaError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    readonly requestId?: string;
+    constructor(message: string, init: MailteaErrorInit);
+}
+
+/** Input for {@link signWebhook}. */
+interface SignWebhookInput {
+    secret: string;
+    msgId: string;
+    /** Unix seconds — the same value sent in the `webhook-timestamp` header. */
+    timestamp: number;
+    payload: string;
+}
+/**
+ * Sign a webhook payload. Returns the `webhook-signature` header value in
+ * Standard Webhooks form: `v1,<base64 HMAC-SHA256>`.
+ */
+declare function signWebhook(input: SignWebhookInput): string;
+/** Input for {@link verifyWebhookSignature}. */
+interface VerifyWebhookSignatureInput {
+    secret: string;
+    msgId: string;
+    /** Unix seconds, as received in the `webhook-timestamp` header. */
+    timestamp: number;
+    payload: string;
+    signatureHeader: string;
+    /** Allowed clock skew each way. Default 5 minutes. */
+    toleranceSeconds?: number;
+    /** Injectable for tests. Unix seconds. */
+    now?: number;
+}
+/**
+ * Verify a `webhook-signature` header against the expected HMAC. The header may
+ * carry multiple space-delimited `v1,<sig>` tokens (Standard Webhooks allows
+ * key rotation); a match against any `v1` token passes. Rejects when the
+ * timestamp is outside `toleranceSeconds` of `now` (replay protection).
+ */
+declare function verifyWebhookSignature(input: VerifyWebhookSignatureInput): boolean;
+
+export { type ApiKeyListItem, type ApiKeyPermission, ApiKeys, type BatchEmailInput, type BatchEmailItemInput, type BatchEmailResponse, type CancelEmailResponse, type Contact, ContactProperties, type ContactProperty, type ContactPropertyType, type ContactStatus, Contacts, type CreateApiKeyInput, type CreateContactInput, type CreateContactPropertyInput, type CreateDomainInput, type CreatePostInput, type CreatePostResult, type CreateSegmentInput, type CreateTagInput, type CreateTrackingDomainInput, type CreateWebhookInput, type CreatedApiKey, type DeletedResponse, type Domain, type DomainPurpose, type DomainRecord, type DomainStatus, Domains, type EmailAnalytics, type EmailAnalyticsParams, type EmailAttachmentMeta, type EmailListItem, type EmailListResponse, type EmailStatus, type EmailTag, Emails, type InboundAttachment, type InboundAttachmentMeta, InboundAttachments, type InboundEmailListItem, InboundEmails, type InboundReplyInput, type InboundReplyResponse, type ListContactPropertiesParams, type ListContactsParams, type ListDomainsParams, type ListEmailsParams, type ListInboundEmailsParams, type ListResponse, type ListSegmentsParams, type ListTagsParams, type ListWebhooksParams, Mailtea, MailteaError, type MailteaErrorInit, type MailteaOptions, type PostTestSendResult, Posts, type RequestFn, type RetrievedEmail, type RetrievedInboundEmail, type Segment, Segments, type SendEmailInput, type SendEmailResponse, type SendPostTestInput, type SignWebhookInput, type Tag, type TagSubscription, type TagVisibility, Tags, type TemplateRef, type TrackingDomain, TrackingDomains, type UpdateContactInput, type UpdateContactPropertyInput, type UpdateDomainInput, type UpdateEmailInput, type UpdateEmailResponse, type UpdateSegmentInput, type UpdateTagInput, type UpdateWebhookInput, type VerifyWebhookSignatureInput, type Webhook, type WebhookEvent, type WebhookStatus, Webhooks, signWebhook, verifyWebhookSignature };