@inboundemail/sdk/dist/index.d.ts

Official SDK for Inbound Email API

/**
 * Type definitions for the Inbound Email SDK
 */
interface InboundEmailConfig {
    apiKey: string;
    baseUrl?: string;
}
interface ApiResponse<T = any> {
    data: T;
    success: boolean;
    error?: string;
}
interface Pagination {
    limit: number;
    offset: number;
    total: number;
    hasMore?: boolean;
}
interface EmailItem {
    id: string;
    emailId: string;
    messageId: string | null;
    subject: string;
    from: string;
    fromName: string | null;
    recipient: string;
    preview: string;
    receivedAt: Date;
    isRead: boolean;
    readAt: Date | null;
    isArchived: boolean;
    archivedAt: Date | null;
    hasAttachments: boolean;
    attachmentCount: number;
    parseSuccess: boolean | null;
    parseError: string | null;
    createdAt: Date;
}
interface GetMailRequest {
    limit?: number;
    offset?: number;
    search?: string;
    status?: 'all' | 'processed' | 'failed';
    domain?: string;
    timeRange?: '24h' | '7d' | '30d' | '90d';
    includeArchived?: boolean;
}
interface GetMailResponse {
    emails: EmailItem[];
    pagination: Pagination;
}
interface PostMailRequest {
    emailId: string;
    to: string;
    subject: string;
    textBody: string;
    htmlBody?: string;
}
interface PostMailResponse {
    message: string;
}
interface GetMailByIdResponse {
    id: string;
    emailId: string;
    subject: string;
    from: string;
    to: string;
    textBody: string;
    htmlBody: string;
    receivedAt: Date;
    attachments: any[];
}
interface WebhookConfig {
    url: string;
    timeout: number;
    retryAttempts: number;
    headers?: Record<string, string>;
}
interface EmailConfig {
    email: string;
}
interface EmailGroupConfig {
    emails: string[];
}
type EndpointConfig = WebhookConfig | EmailConfig | EmailGroupConfig;
interface EndpointWithStats {
    id: string;
    name: string;
    type: 'webhook' | 'email' | 'email_group';
    config: EndpointConfig;
    isActive: boolean;
    description: string | null;
    userId: string;
    createdAt: Date;
    updatedAt: Date;
    groupEmails: string[] | null;
    deliveryStats: {
        total: number;
        successful: number;
        failed: number;
        lastDelivery: string | null;
    };
}
interface GetEndpointsRequest {
    limit?: number;
    offset?: number;
    type?: 'webhook' | 'email' | 'email_group';
    active?: 'true' | 'false';
}
interface GetEndpointsResponse {
    data: EndpointWithStats[];
    pagination: Pagination;
}
interface PostEndpointsRequest {
    name: string;
    type: 'webhook' | 'email' | 'email_group';
    description?: string;
    config: EndpointConfig;
}
interface PostEndpointsResponse {
    id: string;
    name: string;
    type: string;
    config: EndpointConfig;
    isActive: boolean;
    description: string | null;
    createdAt: Date;
}
interface GetEndpointByIdResponse {
    id: string;
    name: string;
    type: string;
    config: EndpointConfig;
    isActive: boolean;
    description: string | null;
    deliveryStats: {
        total: number;
        successful: number;
        failed: number;
    };
    recentDeliveries: any[];
    associatedEmails: any[];
    catchAllDomains: any[];
    createdAt: Date;
    updatedAt: Date;
}
interface PutEndpointByIdRequest {
    name?: string;
    description?: string;
    isActive?: boolean;
    config?: EndpointConfig;
}
interface PutEndpointByIdResponse {
    id: string;
    name: string;
    description: string | null;
    isActive: boolean;
    config: EndpointConfig;
    updatedAt: Date;
}
interface DeleteEndpointByIdResponse {
    message: string;
    cleanup: {
        emailAddressesUpdated: number;
        domainsUpdated: number;
        groupEmailsDeleted: number;
        deliveriesDeleted: number;
        emailAddresses: any[];
        domains: any[];
    };
}
interface DomainWithStats {
    id: string;
    domain: string;
    status: string;
    canReceiveEmails: boolean;
    hasMxRecords: boolean;
    domainProvider: string | null;
    providerConfidence: string | null;
    lastDnsCheck: Date | null;
    lastSesCheck: Date | null;
    isCatchAllEnabled: boolean;
    catchAllEndpointId: string | null;
    createdAt: Date;
    updatedAt: Date;
    userId: string;
    stats: {
        totalEmailAddresses: number;
        activeEmailAddresses: number;
        hasCatchAll: boolean;
    };
    catchAllEndpoint?: {
        id: string;
        name: string;
        type: string;
        isActive: boolean;
    } | null;
    verificationCheck?: {
        dnsRecords?: Array<{
            type: string;
            name: string;
            value: string;
            status: string;
            lastChecked: Date;
        }>;
        sesStatus?: string;
        isFullyVerified?: boolean;
        lastChecked?: Date;
    };
}
interface GetDomainsRequest {
    limit?: number;
    offset?: number;
    status?: 'pending' | 'verified' | 'failed';
    canReceive?: 'true' | 'false';
    check?: 'true' | 'false';
}
interface GetDomainsResponse {
    data: DomainWithStats[];
    pagination: Pagination;
    meta: {
        totalCount: number;
        verifiedCount: number;
        statusBreakdown: Record<string, number>;
    };
}
interface PostDomainsRequest {
    domain: string;
}
interface PostDomainsResponse {
    id: string;
    domain: string;
    status: string;
    dnsRecords: Array<{
        type: string;
        name: string;
        value: string;
    }>;
    createdAt: Date;
}
interface GetDomainByIdResponse {
    id: string;
    domain: string;
    status: string;
    canReceiveEmails: boolean;
    isCatchAllEnabled: boolean;
    catchAllEndpointId: string | null;
    stats: {
        totalEmailAddresses: number;
        activeEmailAddresses: number;
    };
    catchAllEndpoint?: {
        id: string;
        name: string;
        type: string;
    } | null;
    createdAt: Date;
    updatedAt: Date;
}
interface PutDomainByIdRequest {
    isCatchAllEnabled: boolean;
    catchAllEndpointId: string | null;
}
interface PutDomainByIdResponse {
    id: string;
    domain: string;
    isCatchAllEnabled: boolean;
    catchAllEndpointId: string | null;
    catchAllEndpoint?: {
        id: string;
        name: string;
        type: string;
    } | null;
    updatedAt: Date;
}
interface EmailAddressWithDomain {
    id: string;
    address: string;
    domainId: string;
    webhookId: string | null;
    endpointId: string | null;
    isActive: boolean;
    isReceiptRuleConfigured: boolean;
    receiptRuleName: string | null;
    createdAt: Date;
    updatedAt: Date;
    userId: string;
    domain: {
        id: string;
        name: string;
        status: string;
    };
    routing: {
        type: 'webhook' | 'endpoint' | 'none';
        id: string | null;
        name: string | null;
        config?: any;
        isActive: boolean;
    };
}
interface GetEmailAddressesRequest {
    limit?: number;
    offset?: number;
    domainId?: string;
    isActive?: 'true' | 'false';
    isReceiptRuleConfigured?: 'true' | 'false';
}
interface GetEmailAddressesResponse {
    data: EmailAddressWithDomain[];
    pagination: Pagination;
}
interface PostEmailAddressesRequest {
    address: string;
    domainId: string;
    endpointId?: string;
    isActive?: boolean;
}
interface PostEmailAddressesResponse {
    id: string;
    address: string;
    domainId: string;
    endpointId: string | null;
    isActive: boolean;
    domain: {
        name: string;
    };
    routing: {
        type: 'webhook' | 'endpoint' | 'none';
    };
    createdAt: Date;
}
interface GetEmailAddressByIdResponse {
    id: string;
    address: string;
    domainId: string;
    endpointId: string | null;
    isActive: boolean;
    isReceiptRuleConfigured: boolean;
    domain: {
        name: string;
    };
    routing: {
        type: 'webhook' | 'endpoint' | 'none';
        id: string | null;
        name: string | null;
        config?: any;
        isActive: boolean;
    };
    createdAt: Date;
    updatedAt: Date;
}
interface PutEmailAddressByIdRequest {
    isActive?: boolean;
    endpointId?: string | null;
}
interface PutEmailAddressByIdResponse {
    id: string;
    address: string;
    isActive: boolean;
    domain: {
        name: string;
    };
    routing: {
        type: 'webhook' | 'endpoint' | 'none';
    };
    updatedAt: Date;
}
interface DeleteEmailAddressByIdResponse {
    message: string;
    cleanup: {
        emailAddress: string;
        domain: string;
        sesRuleUpdated: boolean;
    };
}
interface PostEmailsRequest {
    from: string;
    to: string | string[];
    subject: string;
    bcc?: string | string[];
    cc?: string | string[];
    replyTo?: string | string[];
    html?: string;
    text?: string;
    headers?: Record<string, string>;
    attachments?: Array<{
        content: string;
        filename: string;
        path?: string;
        contentType?: string;
    }>;
    tags?: Array<{
        name: string;
        value: string;
    }>;
}
interface PostEmailsResponse {
    id: string;
}
interface GetEmailByIdResponse {
    object: string;
    id: string;
    from: string;
    to: string[];
    cc: string[];
    bcc: string[];
    reply_to: string[];
    subject: string;
    text: string;
    html: string;
    created_at: Date;
    last_event: 'pending' | 'delivered' | 'failed';
}
interface PostEmailReplyRequest {
    from: string;
    to?: string | string[];
    cc?: string | string[];
    bcc?: string | string[];
    subject?: string;
    text?: string;
    html?: string;
    replyTo?: string | string[];
    headers?: Record<string, string>;
    attachments?: Array<{
        content: string;
        filename: string;
        path?: string;
        contentType?: string;
    }>;
    tags?: Array<{
        name: string;
        value: string;
    }>;
    includeOriginal?: boolean;
}
interface PostEmailReplyResponse {
    id: string;
}

/**
 * TypeScript types for Inbound Email webhook payloads
 * Use these types to add type safety to your webhook handlers
 */
interface InboundEmailAddress {
    text: string;
    addresses: Array<{
        name: string | null;
        address: string | null;
    }>;
}
interface InboundEmailAttachment {
    filename: string | undefined;
    contentType: string | undefined;
    size: number | undefined;
    contentId: string | undefined;
    contentDisposition: string | undefined;
}
interface InboundEmailHeaders extends Record<string, any> {
    'return-path'?: {
        value?: Array<{
            address: string;
            name: string;
        }> | string;
        html?: string;
        text?: string;
        params?: Record<string, string>;
    };
    'received'?: string | string[];
    'received-spf'?: string;
    'authentication-results'?: string;
    'x-ses-receipt'?: string;
    'x-ses-dkim-signature'?: string;
    'dkim-signature'?: Array<{
        value: string;
        params: Record<string, string>;
    }> | {
        value?: Array<{
            address: string;
            name: string;
        }> | string;
        html?: string;
        text?: string;
        params?: Record<string, string>;
    };
    'list'?: {
        unsubscribe?: {
            url: string;
        };
        'unsubscribe-post'?: {
            name: string;
        };
    };
    'x-entity-ref-id'?: string;
    'from'?: {
        value?: Array<{
            address: string;
            name: string;
        }> | string;
        html?: string;
        text?: string;
        params?: Record<string, string>;
    };
    'to'?: {
        value?: Array<{
            address: string;
            name: string;
        }> | string;
        html?: string;
        text?: string;
        params?: Record<string, string>;
    };
    'subject'?: string;
    'message-id'?: string;
    'date'?: string;
    'mime-version'?: string;
    'content-type'?: {
        value: string;
        params: Record<string, string>;
    };
    'feedback-id'?: string;
    'x-ses-outgoing'?: string;
}
interface InboundParsedEmailData {
    messageId: string | undefined;
    date: Date | undefined;
    subject: string | undefined;
    from: InboundEmailAddress | null;
    to: InboundEmailAddress | null;
    cc: InboundEmailAddress | null;
    bcc: InboundEmailAddress | null;
    replyTo: InboundEmailAddress | null;
    inReplyTo: string | undefined;
    references: string[] | undefined;
    textBody: string | undefined;
    htmlBody: string | undefined;
    raw?: string;
    attachments: InboundEmailAttachment[];
    headers: InboundEmailHeaders;
    priority: string | false | undefined;
}
interface InboundWebhookEmail {
    id: string;
    messageId: string | null;
    from: InboundEmailAddress | null;
    to: InboundEmailAddress | null;
    recipient: string;
    subject: string | null;
    receivedAt: Date | string;
    parsedData: InboundParsedEmailData;
    cleanedContent: {
        html: string | null;
        text: string | null;
        hasHtml: boolean;
        hasText: boolean;
        attachments: InboundEmailAttachment[];
        headers: InboundEmailHeaders;
    };
}
interface InboundWebhookEndpoint {
    id: string;
    name: string;
    type: 'webhook' | 'email' | 'email_group';
}
interface InboundWebhookPayload {
    event: 'email.received';
    timestamp: string;
    email: InboundWebhookEmail;
    endpoint: InboundWebhookEndpoint;
}
interface InboundWebhookHeaders {
    'content-type': 'application/json';
    'user-agent': 'InboundEmail-Webhook/1.0';
    'x-webhook-event': 'email.received';
    'x-endpoint-id': string;
    'x-webhook-timestamp': string;
    'x-email-id': string;
    'x-message-id': string;
    [key: string]: string;
}
interface InboundWebhookRequest {
    method: 'POST';
    headers: InboundWebhookHeaders;
    body: InboundWebhookPayload;
}
declare function isInboundWebhook(payload: any): payload is InboundWebhookPayload;
type InboundEmailContent = Pick<InboundWebhookEmail, 'subject' | 'parsedData' | 'cleanedContent'>;
type InboundAttachmentInfo = InboundEmailAttachment & {
    hasContent: boolean;
    isImage: boolean;
    isDocument: boolean;
};
declare function getAttachmentInfo(attachment: InboundEmailAttachment): InboundAttachmentInfo;
declare function getEmailText(email: InboundWebhookEmail): string;
declare function getEmailHtml(email: InboundWebhookEmail): string;
declare function getSenderInfo(email: InboundWebhookEmail): {
    name: string | null;
    address: string | null;
};
declare function getRecipientAddresses(email: InboundWebhookEmail): string[];

/**
 * Main client class for the Inbound Email SDK
 */

declare class InboundEmailClient {
    private readonly apiKey;
    private readonly baseUrl;
    constructor(apiKey: string, baseUrl?: string);
    /**
     * Make an authenticated request to the API
     */
    private request;
    /**
     * Mail API - for managing received emails
     */
    mail: {
        /**
         * List all emails in the mailbox
         */
        list: (params?: GetMailRequest) => Promise<GetMailResponse>;
        /**
         * Get a specific email by ID
         */
        get: (id: string) => Promise<GetMailByIdResponse>;
        /**
         * Reply to an email
         */
        reply: (params: PostMailRequest) => Promise<PostMailResponse>;
    };
    /**
     * Endpoints API - for managing webhook and email endpoints
     */
    endpoints: {
        /**
         * List all endpoints
         */
        list: (params?: GetEndpointsRequest) => Promise<GetEndpointsResponse>;
        /**
         * Create a new endpoint
         */
        create: (params: PostEndpointsRequest) => Promise<PostEndpointsResponse>;
        /**
         * Get a specific endpoint by ID
         */
        get: (id: string) => Promise<GetEndpointByIdResponse>;
        /**
         * Update an endpoint
         */
        update: (id: string, params: PutEndpointByIdRequest) => Promise<PutEndpointByIdResponse>;
        /**
         * Delete an endpoint
         */
        delete: (id: string) => Promise<DeleteEndpointByIdResponse>;
    };
    /**
     * Domains API - for managing email domains
     */
    domains: {
        /**
         * List all domains
         */
        list: (params?: GetDomainsRequest) => Promise<GetDomainsResponse>;
        /**
         * Create a new domain
         */
        create: (params: PostDomainsRequest) => Promise<PostDomainsResponse>;
        /**
         * Get a specific domain by ID
         */
        get: (id: string) => Promise<GetDomainByIdResponse>;
        /**
         * Update domain settings (catch-all configuration)
         */
        update: (id: string, params: PutDomainByIdRequest) => Promise<PutDomainByIdResponse>;
    };
    /**
     * Email Addresses API - for managing individual email addresses
     */
    emailAddresses: {
        /**
         * List all email addresses
         */
        list: (params?: GetEmailAddressesRequest) => Promise<GetEmailAddressesResponse>;
        /**
         * Create a new email address
         */
        create: (params: PostEmailAddressesRequest) => Promise<PostEmailAddressesResponse>;
        /**
         * Get a specific email address by ID
         */
        get: (id: string) => Promise<GetEmailAddressByIdResponse>;
        /**
         * Update an email address
         */
        update: (id: string, params: PutEmailAddressByIdRequest) => Promise<PutEmailAddressByIdResponse>;
        /**
         * Delete an email address
         */
        delete: (id: string) => Promise<DeleteEmailAddressByIdResponse>;
    };
    /**
     * Emails API - for sending emails (Resend-compatible)
     */
    emails: {
        /**
         * Send an email
         */
        send: (params: PostEmailsRequest) => Promise<PostEmailsResponse>;
        /**
         * Get a sent email by ID
         */
        get: (id: string) => Promise<GetEmailByIdResponse>;
        /**
         * Reply to an email by ID
         */
        reply: (id: string, params: PostEmailReplyRequest) => Promise<PostEmailReplyResponse>;
    };
    /**
     * Legacy send method for backwards compatibility (similar to Resend)
     */
    send: (params: PostEmailsRequest) => Promise<PostEmailsResponse>;
    /**
     * Streamlined reply method for webhook handlers
     * Works directly with webhook email objects for better DX
     *
     * Usage:
     * - inbound.reply("email-id", { from: "support@domain.com", text: "Thanks!" })
     * - inbound.reply(email, { from: "support@domain.com", text: "Thanks!" })
     */
    reply: (emailOrId: InboundWebhookEmail | string, replyParams: PostEmailReplyRequest) => Promise<PostEmailReplyResponse>;
    endpoint: {
        /**
         * List all endpoints
         */
        list: (params?: GetEndpointsRequest) => Promise<GetEndpointsResponse>;
        /**
         * Create a new endpoint
         */
        create: (params: PostEndpointsRequest) => Promise<PostEndpointsResponse>;
        /**
         * Get a specific endpoint by ID
         */
        get: (id: string) => Promise<GetEndpointByIdResponse>;
        /**
         * Update an endpoint
         */
        update: (id: string, params: PutEndpointByIdRequest) => Promise<PutEndpointByIdResponse>;
        /**
         * Delete an endpoint
         */
        delete: (id: string) => Promise<DeleteEndpointByIdResponse>;
    };
    domain: {
        /**
         * List all domains
         */
        list: (params?: GetDomainsRequest) => Promise<GetDomainsResponse>;
        /**
         * Create a new domain
         */
        create: (params: PostDomainsRequest) => Promise<PostDomainsResponse>;
        /**
         * Get a specific domain by ID
         */
        get: (id: string) => Promise<GetDomainByIdResponse>;
        /**
         * Update domain settings (catch-all configuration)
         */
        update: (id: string, params: PutDomainByIdRequest) => Promise<PutDomainByIdResponse>;
    };
    emailAddress: {
        /**
         * List all email addresses
         */
        list: (params?: GetEmailAddressesRequest) => Promise<GetEmailAddressesResponse>;
        /**
         * Create a new email address
         */
        create: (params: PostEmailAddressesRequest) => Promise<PostEmailAddressesResponse>;
        /**
         * Get a specific email address by ID
         */
        get: (id: string) => Promise<GetEmailAddressByIdResponse>;
        /**
         * Update an email address
         */
        update: (id: string, params: PutEmailAddressByIdRequest) => Promise<PutEmailAddressByIdResponse>;
        /**
         * Delete an email address
         */
        delete: (id: string) => Promise<DeleteEmailAddressByIdResponse>;
    };
    email: {
        /**
         * Send an email
         */
        send: (params: PostEmailsRequest) => Promise<PostEmailsResponse>;
        /**
         * Get a sent email by ID
         */
        get: (id: string) => Promise<GetEmailByIdResponse>;
        /**
         * Reply to an email by ID
         */
        reply: (id: string, params: PostEmailReplyRequest) => Promise<PostEmailReplyResponse>;
    };
}

/**
 * Utility functions for the Inbound Email SDK
 */
/**
 * Check if a string is a valid email address
 */
declare function isValidEmail(email: string): boolean;
/**
 * Build query string from parameters
 */
declare function buildQueryString(params: Record<string, any>): string;

/**
 * @inboundemail/sdk
 * Official SDK for Inbound Email API
 * Version 3.0.0
 */

declare const VERSION = "3.0.0";

export { type ApiResponse, type DeleteEmailAddressByIdResponse, type DeleteEndpointByIdResponse, type DomainWithStats, type EmailAddressWithDomain, type EmailConfig, type EmailGroupConfig, type EmailItem, type EndpointConfig, type EndpointWithStats, type GetDomainByIdResponse, type GetDomainsRequest, type GetDomainsResponse, type GetEmailAddressByIdResponse, type GetEmailAddressesRequest, type GetEmailAddressesResponse, type GetEmailByIdResponse, type GetEndpointByIdResponse, type GetEndpointsRequest, type GetEndpointsResponse, type GetMailByIdResponse, type GetMailRequest, type GetMailResponse, InboundEmailClient as Inbound, type InboundAttachmentInfo, type InboundEmailAddress, type InboundEmailAttachment, InboundEmailClient, type InboundEmailConfig, type InboundEmailContent, type InboundEmailHeaders, type InboundParsedEmailData, type InboundWebhookEmail, type InboundWebhookEndpoint, type InboundWebhookHeaders, type InboundWebhookPayload, type InboundWebhookRequest, type Pagination, type PostDomainsRequest, type PostDomainsResponse, type PostEmailAddressesRequest, type PostEmailAddressesResponse, type PostEmailReplyRequest, type PostEmailReplyResponse, type PostEmailsRequest, type PostEmailsResponse, type PostEndpointsRequest, type PostEndpointsResponse, type PostMailRequest, type PostMailResponse, type PutDomainByIdRequest, type PutDomainByIdResponse, type PutEmailAddressByIdRequest, type PutEmailAddressByIdResponse, type PutEndpointByIdRequest, type PutEndpointByIdResponse, VERSION, type WebhookConfig, buildQueryString, InboundEmailClient as default, getAttachmentInfo, getEmailHtml, getEmailText, getRecipientAddresses, getSenderInfo, isInboundWebhook, isValidEmail };