mailchannels-sdk 0.6.1 → 0.7.1

package/README.md

@@ -77,6 +77,7 @@ Already implemented features are marked with a checkmark. Please open an issue i
 
 - 📧 Emails
   - ✅ [Send an Email](https://docs.mailchannels.net/email-api/api-reference/send-an-email)
+  - ✅ [Send an Email Asynchronously](https://docs.mailchannels.net/email-api/api-reference/send-an-email-asynchronously)
   - ✅ [DKIM, SPF & Domain Lockdown Check](https://docs.mailchannels.net/email-api/api-reference/dkim-spf-domain-lockdown-check)
   - ✅ [Create DKIM Key Pair](https://docs.mailchannels.net/email-api/api-reference/create-dkim-key-pair)
   - ✅ [Retrieve DKIM Keys](https://docs.mailchannels.net/email-api/api-reference/retrieve-dkim-keys)

package/dist/mailchannels.d.mts

@@ -12,27 +12,41 @@ declare class MailChannelsClient {
     patch<T>(path: string, options?: Omit<FetchOptions<"json">, "method">): Promise<T>;
 }
 
+interface ErrorResponse {
+  message: string;
+  statusCode: number | null;
+}
+
 interface SuccessResponse {
   /**
    * Whether the operation was successful.
    */
   success: boolean;
   /**
-   * Error message if the operation failed.
+   * Error information if the operation failed.
    */
-  error: string | null;
+  error: ErrorResponse | null;
 }
 
-interface DataResponse<T> {
+type DataResponse$1<T> = {
   /**
    * The response data.
    */
-  data: T | null;
+  data: T;
   /**
-   * Error message if the operation failed.
+   * Error information if the operation failed.
    */
-  error: string | null;
-}
+  error: null;
+} | {
+  /**
+   * The response data.
+   */
+  data: null;
+  /**
+   * Error information if the operation failed.
+   */
+  error: ErrorResponse;
+};
 
 interface EmailsSendRecipient {
   /**
@@ -238,41 +252,45 @@ type EmailsSendOptions = EmailsSendOptionsBase & (
   }
 );
 
-interface EmailsSendResponse {
+type EmailsSendResponse = SuccessResponse & DataResponse$1<{
   /**
-   * Indicates if the email was successfully sent.
+   * Fully rendered message if `dryRun` was set to `true`. A string representation of a rendered message, one per personalization in the request.
    */
-  success: boolean;
-  data: {
+  rendered?: string[];
+  /**
+   * The Request ID is a unique identifier generated by the service to track the HTTP request. It will also be included in all webhooks for reference.
+   */
+  requestId?: string;
+  results?: {
     /**
-     * Fully rendered message if `dryRun` was set to `true`. A string representation of a rendered message, one per personalization in the request.
+     * The index of the personalization in the request. Starts at 0.
      */
-    rendered?: string[];
+    index?: number;
     /**
-     * The Request ID is a unique identifier generated by the service to track the HTTP request. It will also be included in all webhooks for reference.
+     * The Message ID is a unique identifier generated by the service. Each personalization has a distinct Message ID, which is also used in the `Message-Id` header and included in webhooks.
      */
-    requestId?: string;
-    results?: {
-      /**
-       * The index of the personalization in the request. Starts at 0.
-       */
-      index?: number;
-      /**
-       * The Message ID is a unique identifier generated by the service. Each personalization has a distinct Message ID, which is also used in the `Message-Id` header and included in webhooks.
-       */
-      messageId: string;
-      /**
-       * A human-readable explanation of the status.
-       */
-      reason?: string;
-      /**
-       * The status of the message. Note that 'sent' is a temporary status; the final status will be provided through webhooks, if configured.
-       */
-      status: "sent" | "failed";
-    }[];
-  } | null;
-  error: string | null;
-}
+    messageId: string;
+    /**
+     * A human-readable explanation of the status.
+     */
+    reason?: string;
+    /**
+     * The status of the message. Note that 'sent' is a temporary status; the final status will be provided through webhooks, if configured.
+     */
+    status: "sent" | "failed";
+  }[];
+}>;
+
+type EmailsSendAsyncResponse = DataResponse<{
+  /**
+   * ISO 8601 timestamp when the request was queued for processing.
+   */
+  queuedAt: string[];
+  /**
+   * Unique identifier for tracking this async request. Will be included in all webhook events for this request.
+   */
+  requestId: string;
+}>;
 
 interface EmailsCreateDkimKeyOptions {
   /**
@@ -341,7 +359,7 @@ interface EmailsDkimKey {
   statusModifiedAt?: string;
 }
 
-type EmailsCreateDkimKeyResponse = DataResponse<EmailsDkimKey>;
+type EmailsCreateDkimKeyResponse = DataResponse$1<EmailsDkimKey>;
 
 interface EmailsCheckDomainDkim {
   /**
@@ -381,7 +399,7 @@ interface EmailsCheckDomainOptions {
 
 type EmailsCheckDomainVerdict = "passed" | "failed" | "soft failed" | "temporary error" | "permanent error" | "neutral" | "none" | "unknown";
 
-type EmailsCheckDomainResponse = DataResponse<{
+type EmailsCheckDomainResponse = DataResponse$1<{
   dkim: {
     domain: string;
     /**
@@ -463,7 +481,7 @@ interface EmailsGetDkimKeysOptions {
 
 type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 
-type EmailsGetDkimKeysResponse = DataResponse<Optional<EmailsDkimKey, "dnsRecords">[]>;
+type EmailsGetDkimKeysResponse = DataResponse$1<Optional<EmailsDkimKey, "dnsRecords">[]>;
 
 interface EmailsUpdateDkimKeyOptions {
   /**
@@ -488,7 +506,7 @@ interface EmailsRotateDkimKeyOptions {
   };
 }
 
-type EmailsRotateDkimKeyResponse = DataResponse<{
+type EmailsRotateDkimKeyResponse = DataResponse$1<{
   new: EmailsDkimKey;
   rotated: EmailsDkimKey;
 }>;
@@ -496,14 +514,15 @@ type EmailsRotateDkimKeyResponse = DataResponse<{
 declare class Emails {
     protected mailchannels: MailChannelsClient;
     constructor(mailchannels: MailChannelsClient);
+    private _sendEmail;
     /**
-     * Send an email using MailChannels Email API.
+     * Sends an email message to one or more recipients.
      * @param options - The email options to send.
      * @param dryRun - When set to `true`, the message will not be sent. Instead, the fully rendered message will be returned in the `data` property of the response. The default value is `false`.
      * @example
      * ```ts
      * const mailchannels = new MailChannels('your-api-key')
-     * const { success, data } = await mailchannels.emails.send({
+     * const { success, data, error } = await mailchannels.emails.send({
      *   to: 'to@example.com',
      *   from: 'from@example.com',
      *   subject: 'Test',
@@ -512,13 +531,32 @@ declare class Emails {
      * ```
      */
     send(options: EmailsSendOptions, dryRun?: boolean): Promise<EmailsSendResponse>;
+    /**
+     * Queues an email message for asynchronous processing and returns immediately with a request ID.
+     *
+     * The email will be processed in the background, and you'll receive webhook events for all delivery status updates (e.g. `dropped`, `processed`, `delivered`, `hard-bounced`). These webhook events are identical to those sent for the synchronous /send endpoint.
+     *
+     * Use this endpoint when you need to send emails without waiting for processing to complete. This can improve your application's response time, especially when sending to multiple recipients.
+     * @param options - The email options to send.
+     * @example
+     * ```ts
+     * const mailchannels = new MailChannels('your-api-key')
+     * const { data, error } = await mailchannels.emails.sendAsync({
+     *   to: 'to@example.com',
+     *   from: 'from@example.com',
+     *   subject: 'Test',
+     *   html: 'Test'
+     * })
+     * ```
+     */
+    sendAsync(options: EmailsSendOptions): Promise<EmailsSendAsyncResponse>;
     /**
      * Validates a domain's email authentication setup by retrieving its DKIM, SPF, and Domain Lockdown status. This endpoint checks whether the domain is properly configured for secure email delivery.
      * @param options - The domain options to check.
      * @example
      * ```ts
      * const mailchannels = new MailChannels('your-api-key')
-     * const { results } = await mailchannels.emails.checkDomain({
+     * const { data, error } = await mailchannels.emails.checkDomain({
      *   dkim: [{
      *     domain: 'example.com',
      *     privateKey: 'your-private-key',
@@ -588,13 +626,13 @@ declare class Emails {
     rotateDkimKey(domain: string, selector: string, options: EmailsRotateDkimKeyOptions): Promise<EmailsRotateDkimKeyResponse>;
 }
 
-type WebhooksListResponse = DataResponse<string[]>;
+type WebhooksListResponse = DataResponse$1<string[]>;
 
-type WebhooksSigningKeyResponse = DataResponse<{
+type WebhooksSigningKeyResponse = DataResponse$1<{
   key: string;
 }>;
 
-type WebhooksValidateResponse = DataResponse<{
+type WebhooksValidateResponse = DataResponse$1<{
   /**
    * Indicates whether all webhook validations passed.
    */
@@ -695,7 +733,7 @@ interface SubAccountsAccount {
   handle: string;
 }
 
-type SubAccountsCreateResponse = DataResponse<SubAccountsAccount>;
+type SubAccountsCreateResponse = DataResponse$1<SubAccountsAccount>;
 
 interface SubAccountsListOptions {
   /**
@@ -710,7 +748,7 @@ interface SubAccountsListOptions {
   offset?: number;
 }
 
-type SubAccountsListResponse = DataResponse<SubAccountsAccount[]>;
+type SubAccountsListResponse = DataResponse$1<SubAccountsAccount[]>;
 
 interface SubAccountsApiKey {
   /**
@@ -723,7 +761,7 @@ interface SubAccountsApiKey {
   value: string;
 }
 
-type SubAccountsCreateApiKeyResponse = DataResponse<SubAccountsApiKey>;
+type SubAccountsCreateApiKeyResponse = DataResponse$1<SubAccountsApiKey>;
 
 interface SubAccountsListApiKeyOptions {
   /**
@@ -738,7 +776,7 @@ interface SubAccountsListApiKeyOptions {
   offset?: number;
 }
 
-type SubAccountsListApiKeyResponse = DataResponse<SubAccountsApiKey[]>;
+type SubAccountsListApiKeyResponse = DataResponse$1<SubAccountsApiKey[]>;
 
 interface SubAccountsSmtpPassword {
   /**
@@ -755,15 +793,15 @@ interface SubAccountsSmtpPassword {
   value: string;
 }
 
-type SubAccountsCreateSmtpPasswordResponse = DataResponse<SubAccountsSmtpPassword>;
+type SubAccountsCreateSmtpPasswordResponse = DataResponse$1<SubAccountsSmtpPassword>;
 
-type SubAccountsListSmtpPasswordResponse = DataResponse<SubAccountsSmtpPassword[]>;
+type SubAccountsListSmtpPasswordResponse = DataResponse$1<SubAccountsSmtpPassword[]>;
 
 interface SubAccountsLimit {
   sends: number;
 }
 
-type SubAccountsLimitResponse = DataResponse<SubAccountsLimit>;
+type SubAccountsLimitResponse = DataResponse$1<SubAccountsLimit>;
 
 interface SubAccountsUsage {
   /**
@@ -782,7 +820,7 @@ interface SubAccountsUsage {
   total: number;
 }
 
-type SubAccountsUsageResponse = DataResponse<SubAccountsUsage>;
+type SubAccountsUsageResponse = DataResponse$1<SubAccountsUsage>;
 
 declare class SubAccounts {
     protected mailchannels: MailChannelsClient;
@@ -963,7 +1001,7 @@ interface MetricsEngagement {
   startTime: string;
 }
 
-type MetricsEngagementResponse = DataResponse<MetricsEngagement>;
+type MetricsEngagementResponse = DataResponse$1<MetricsEngagement>;
 
 interface MetricsPerformance {
   /**
@@ -996,7 +1034,7 @@ interface MetricsPerformance {
   startTime: string;
 }
 
-type MetricsPerformanceResponse = DataResponse<MetricsPerformance>;
+type MetricsPerformanceResponse = DataResponse$1<MetricsPerformance>;
 
 interface MetricsRecipientBehaviour {
   /**
@@ -1024,7 +1062,7 @@ interface MetricsRecipientBehaviour {
   unsubscribed: number;
 }
 
-type MetricsRecipientBehaviourResponse = DataResponse<MetricsRecipientBehaviour>;
+type MetricsRecipientBehaviourResponse = DataResponse$1<MetricsRecipientBehaviour>;
 
 interface MetricsVolume {
   /**
@@ -1057,9 +1095,9 @@ interface MetricsVolume {
   startTime: string;
 }
 
-type MetricsVolumeResponse = DataResponse<MetricsVolume>;
+type MetricsVolumeResponse = DataResponse$1<MetricsVolume>;
 
-type MetricsUsageResponse = DataResponse<{
+type MetricsUsageResponse = DataResponse$1<{
   /**
    * The end date of the current billing period (ISO 8601 format).
    * @example "2025-04-11"
@@ -1127,7 +1165,7 @@ interface MetricsSenders {
   total: number;
 }
 
-type MetricsSendersResponse = DataResponse<MetricsSenders>;
+type MetricsSendersResponse = DataResponse$1<MetricsSenders>;
 
 interface MetricsBucket {
   /**
@@ -1298,7 +1336,7 @@ interface SuppressionsListEntry {
   types: SuppressionsTypes[];
 }
 
-type SuppressionsListResponse = DataResponse<SuppressionsListEntry[]>;
+type SuppressionsListResponse = DataResponse$1<SuppressionsListEntry[]>;
 
 declare class Suppressions {
     protected mailchannels: MailChannelsClient;
@@ -1356,9 +1394,9 @@ interface ListEntry {
   type: "domain" | "email_address" | "ip_address";
 }
 
-type ListEntryResponse = DataResponse<ListEntry>;
+type ListEntryResponse = DataResponse$1<ListEntry>;
 
-type ListEntriesResponse = DataResponse<ListEntry[]>;
+type ListEntriesResponse = DataResponse$1<ListEntry[]>;
 
 interface DomainsData {
   /**
@@ -1434,9 +1472,9 @@ interface DomainsProvisionOptions {
 
 type DomainsBulkProvisionOptions = DomainsProvisionOptions & Pick<DomainsData, "subscriptionHandle">;
 
-type DomainsProvisionResponse = DataResponse<DomainsData>;
+type DomainsProvisionResponse = DataResponse$1<DomainsData>;
 
-type DomainsBulkProvisionResponse = DataResponse<{
+type DomainsBulkProvisionResponse = DataResponse$1<{
   /**
    * Domains that were successfully provisioned or updated.
    */
@@ -1478,7 +1516,7 @@ interface DomainsListOptions {
   offset?: number;
 }
 
-type DomainsListResponse = DataResponse<{
+type DomainsListResponse = DataResponse$1<{
   /**
    * A list of domains.
    */
@@ -1496,7 +1534,7 @@ interface DomainsCreateLoginLink {
   link: string;
 }
 
-type DomainsCreateLoginLinkResponse = DataResponse<DomainsCreateLoginLink>;
+type DomainsCreateLoginLinkResponse = DataResponse$1<DomainsCreateLoginLink>;
 
 interface DomainsListDownstreamAddressesOptions {
   /**
@@ -1530,7 +1568,7 @@ interface DomainsDownstreamAddress {
   weight: number;
 }
 
-type DomainsListDownstreamAddressesResponse = DataResponse<DomainsDownstreamAddress[]>;
+type DomainsListDownstreamAddressesResponse = DataResponse$1<DomainsDownstreamAddress[]>;
 
 interface DomainsBulkCreateLoginLinkResult {
   /**
@@ -1553,7 +1591,7 @@ interface DomainsBulkCreateLoginLinks {
   errors: Omit<DomainsBulkCreateLoginLinkResult, "loginLink">[];
 }
 
-type DomainsBulkCreateLoginLinksResponse = DataResponse<DomainsBulkCreateLoginLinks>;
+type DomainsBulkCreateLoginLinksResponse = DataResponse$1<DomainsBulkCreateLoginLinks>;
 
 declare class Domains {
     protected mailchannels: MailChannelsClient;
@@ -1777,7 +1815,7 @@ interface UsersCreateOptions {
   };
 }
 
-type UsersCreateResponse = DataResponse<{
+type UsersCreateResponse = DataResponse$1<{
   email: string;
   roles: string[];
   filter?: boolean;
@@ -1845,7 +1883,7 @@ declare class Users {
     deleteListEntry(email: string, options: ListEntryOptions): Promise<SuccessResponse>;
 }
 
-type ServiceSubscriptionsResponse = DataResponse<{
+type ServiceSubscriptionsResponse = DataResponse$1<{
   active: boolean;
   activeAccountsCount: number;
   handle: string;
@@ -1933,4 +1971,4 @@ declare class MailChannels extends MailChannelsClient {
 }
 
 export { Domains, Emails, Lists, MailChannels, MailChannelsClient, Metrics, Service, SubAccounts, Suppressions, Users, Webhooks };
-export type { DataResponse, DomainsBulkCreateLoginLinkResult, DomainsBulkCreateLoginLinks, DomainsBulkCreateLoginLinksResponse, DomainsBulkProvisionOptions, DomainsBulkProvisionResponse, DomainsCreateLoginLink, DomainsCreateLoginLinkResponse, DomainsData, DomainsDownstreamAddress, DomainsListDownstreamAddressesOptions, DomainsListDownstreamAddressesResponse, DomainsListOptions, DomainsListResponse, DomainsProvisionOptions, DomainsProvisionResponse, EmailsCheckDomainDkim, EmailsCheckDomainOptions, EmailsCheckDomainResponse, EmailsCheckDomainVerdict, EmailsCreateDkimKeyOptions, EmailsCreateDkimKeyResponse, EmailsDkimKey, EmailsDkimKeyStatus, EmailsGetDkimKeysOptions, EmailsGetDkimKeysResponse, EmailsRotateDkimKeyOptions, EmailsRotateDkimKeyResponse, EmailsSendAttachment, EmailsSendOptions, EmailsSendOptionsBase, EmailsSendRecipient, EmailsSendResponse, EmailsSendTracking, EmailsUpdateDkimKeyOptions, ListEntriesResponse, ListEntry, ListEntryOptions, ListEntryResponse, ListNames, MetricsBucket, MetricsEngagement, MetricsEngagementResponse, MetricsOptions, MetricsPerformance, MetricsPerformanceResponse, MetricsRecipientBehaviour, MetricsRecipientBehaviourResponse, MetricsSenders, MetricsSendersOptions, MetricsSendersResponse, MetricsSendersType, MetricsUsageResponse, MetricsVolume, MetricsVolumeResponse, Optional, ServiceReportOptions, ServiceSubscriptionsResponse, SubAccountsAccount, SubAccountsApiKey, SubAccountsCreateApiKeyResponse, SubAccountsCreateResponse, SubAccountsCreateSmtpPasswordResponse, SubAccountsLimit, SubAccountsLimitResponse, SubAccountsListApiKeyOptions, SubAccountsListApiKeyResponse, SubAccountsListOptions, SubAccountsListResponse, SubAccountsListSmtpPasswordResponse, SubAccountsSmtpPassword, SubAccountsUsage, SubAccountsUsageResponse, SuccessResponse, SuppressionsCreateOptions, SuppressionsListEntry, SuppressionsListOptions, SuppressionsListResponse, SuppressionsSource, SuppressionsTypes, UsersCreateOptions, UsersCreateResponse, WebhooksListResponse, WebhooksSigningKeyResponse, WebhooksValidateResponse };
+export type { DataResponse$1 as DataResponse, DomainsBulkCreateLoginLinkResult, DomainsBulkCreateLoginLinks, DomainsBulkCreateLoginLinksResponse, DomainsBulkProvisionOptions, DomainsBulkProvisionResponse, DomainsCreateLoginLink, DomainsCreateLoginLinkResponse, DomainsData, DomainsDownstreamAddress, DomainsListDownstreamAddressesOptions, DomainsListDownstreamAddressesResponse, DomainsListOptions, DomainsListResponse, DomainsProvisionOptions, DomainsProvisionResponse, EmailsCheckDomainDkim, EmailsCheckDomainOptions, EmailsCheckDomainResponse, EmailsCheckDomainVerdict, EmailsCreateDkimKeyOptions, EmailsCreateDkimKeyResponse, EmailsDkimKey, EmailsDkimKeyStatus, EmailsGetDkimKeysOptions, EmailsGetDkimKeysResponse, EmailsRotateDkimKeyOptions, EmailsRotateDkimKeyResponse, EmailsSendAsyncResponse, EmailsSendAttachment, EmailsSendOptions, EmailsSendOptionsBase, EmailsSendRecipient, EmailsSendResponse, EmailsSendTracking, EmailsUpdateDkimKeyOptions, ErrorResponse, ListEntriesResponse, ListEntry, ListEntryOptions, ListEntryResponse, ListNames, MetricsBucket, MetricsEngagement, MetricsEngagementResponse, MetricsOptions, MetricsPerformance, MetricsPerformanceResponse, MetricsRecipientBehaviour, MetricsRecipientBehaviourResponse, MetricsSenders, MetricsSendersOptions, MetricsSendersResponse, MetricsSendersType, MetricsUsageResponse, MetricsVolume, MetricsVolumeResponse, Optional, ServiceReportOptions, ServiceSubscriptionsResponse, SubAccountsAccount, SubAccountsApiKey, SubAccountsCreateApiKeyResponse, SubAccountsCreateResponse, SubAccountsCreateSmtpPasswordResponse, SubAccountsLimit, SubAccountsLimitResponse, SubAccountsListApiKeyOptions, SubAccountsListApiKeyResponse, SubAccountsListOptions, SubAccountsListResponse, SubAccountsListSmtpPasswordResponse, SubAccountsSmtpPassword, SubAccountsUsage, SubAccountsUsageResponse, SuccessResponse, SuppressionsCreateOptions, SuppressionsListEntry, SuppressionsListOptions, SuppressionsListResponse, SuppressionsSource, SuppressionsTypes, UsersCreateOptions, UsersCreateResponse, WebhooksListResponse, WebhooksSigningKeyResponse, WebhooksValidateResponse };