groundmail 0.14.8 → 0.15.1

package/dist/authjs.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail } from './client-UTorFXe6.js';
+import { G as Groundmail } from './client-DYUh2ub4.js';
 
 /** Subset of Auth.js theme used for the default magic-link email. */
 type AuthjsTheme = {

package/dist/authjs.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_BASE_URL,
   Groundmail
-} from "./chunk-LKMNSXA3.js";
+} from "./chunk-N2LD34ND.js";
 
 // src/authjs.ts
 function escapeHtml(value) {

package/dist/better-auth.d.ts

@@ -1,4 +1,4 @@
-import { S as SendEmailResult, G as Groundmail } from './client-UTorFXe6.js';
+import { S as SendEmailResult, G as Groundmail } from './client-DYUh2ub4.js';
 
 type BetterAuthEmailUser = {
     email: string;

package/dist/better-auth.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_BASE_URL,
   Groundmail
-} from "./chunk-LKMNSXA3.js";
+} from "./chunk-N2LD34ND.js";
 
 // src/better-auth.ts
 function linkHtml(label, url) {

package/dist/{chunk-LKMNSXA3.js → chunk-N2LD34ND.js}

@@ -1414,6 +1414,17 @@ var Groundmail = class {
     this.templates = new TemplatesResource(this);
     this.migrations = new MigrationsResource(this);
   }
+  /**
+   * Check one address with Groundmail validation before you accept it (for
+   * example on a signup form): syntax, mail server, disposable and role
+   * addresses, recent hard bounces, and a typo suggestion. Free; sends nothing.
+   */
+  async validate(email) {
+    return this.request("/validate", {
+      method: "POST",
+      body: JSON.stringify({ email })
+    });
+  }
   get baseUrl() {
     return (this.options.baseUrl || DEFAULT_API_BASE_URL).replace(/\/$/, "");
   }

package/dist/clerk.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail, S as SendEmailResult } from './client-UTorFXe6.js';
+import { G as Groundmail, S as SendEmailResult } from './client-DYUh2ub4.js';
 
 /**
  * Subset of Clerk `email.created` webhook `data` used for delivery.

package/dist/clerk.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_BASE_URL,
   Groundmail
-} from "./chunk-LKMNSXA3.js";
+} from "./chunk-N2LD34ND.js";
 
 // src/clerk.ts
 function resolveApiKey(options) {

package/dist/{client-UTorFXe6.d.ts → client-DYUh2ub4.d.ts}

@@ -1,4 +1,6 @@
-type ApiErrorCode = 'validation_error' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'plan_limit' | 'domain_limit' | 'idempotency_conflict' | 'rate_limited' | 'upstream_error' | 'not_configured' | 'internal_error';
+type ApiErrorCode = 'validation_error' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'plan_limit'
+/** 429: the send would go over a new account's daily ramp-up limit; see `details.resets_at`. */
+ | 'daily_ramp_limit' | 'domain_limit' | 'idempotency_conflict' | 'rate_limited' | 'upstream_error' | 'not_configured' | 'internal_error';
 type SendEmailParams = {
     from: string | {
         email: string;
@@ -58,15 +60,57 @@ type SendEmailParams = {
      */
     category?: 'transactional' | 'product';
 };
+/**
+ * Why Groundmail validation held a recipient back before sending:
+ * - `invalid_address`: the address cannot exist (syntax).
+ * - `no_mail_server`: the domain does not exist or takes no email (no MX or A record, or a null MX).
+ * - `previously_bounced`: the address hard-bounced (mailbox does not exist) for a Groundmail
+ *   sender in the last 90 days.
+ * - `mailbox_not_found`: Groundmail validation already knows the mailbox does not exist.
+ */
+type HeldBackReason = 'invalid_address' | 'no_mail_server' | 'previously_bounced' | 'mailbox_not_found';
+type HeldBackRecipient = {
+    email: string;
+    reason: HeldBackReason | (string & {});
+};
 type SendEmailResult = {
     id: string;
     status: string;
+    /** Present when some recipients were held back and the email went to the rest. */
+    held_back?: HeldBackRecipient[];
+};
+/** `details` on `POST /emails` 422 when Groundmail validation held back every `to` recipient. */
+type HeldBackErrorDetails = {
+    held_back: HeldBackRecipient[];
+    email_id: string;
+};
+type ValidationVerdict = 'valid' | 'risky' | 'invalid';
+/**
+ * - invalid: `syntax`, `no_mail_server`, `mailbox_not_found`, `previously_bounced`
+ * - risky: `disposable`, `catch_all`, `possible_typo`
+ * - informational (does not change the verdict): `role`
+ */
+type ValidationReason = 'syntax' | 'no_mail_server' | 'mailbox_not_found' | 'previously_bounced' | 'disposable' | 'catch_all' | 'possible_typo' | 'role';
+/** `POST /validate` result. */
+type ValidateEmailResult = {
+    /** The address as checked: trimmed and lowercased. */
+    email: string;
+    domain: string | null;
+    verdict: ValidationVerdict;
+    reasons: Array<ValidationReason | (string & {})>;
+    /** The address with a likely-mistyped domain corrected (`ada@gmial.com` → `ada@gmail.com`), or null. */
+    suggestion: string | null;
+    /** A throwaway-inbox service. It can receive mail; accepting it is your call. */
+    disposable: boolean;
+    /** Reaches a team or queue (`info@`, `support@`) rather than a person. */
+    role: boolean;
 };
 type BatchSendEmailResult = {
     data: Array<{
         index: number;
         id?: string;
         status?: string;
+        held_back?: HeldBackRecipient[];
         error?: {
             message: string;
             code?: string;
@@ -102,6 +146,8 @@ type EmailListItem = {
     bounce_reason: string | null;
     /** `hard` or `block` once the email has bounced; null otherwise. */
     bounce_type: BounceType | null;
+    /** Recipients Groundmail validation held back before sending, with why. Empty when none were. */
+    held_back: HeldBackRecipient[];
     tags: unknown;
     scheduled_at: string | null;
     cancelled_at: string | null;
@@ -308,6 +354,23 @@ type SuppressedErrorDetails = {
     suppressed: string[];
     email_id: string;
 };
+/**
+ * `details` on a 429 `daily_ramp_limit`: the send would go over a new account's
+ * daily ramp-up limit for its stream. Send the rest after `resets_at`.
+ */
+type DailyRampLimitErrorDetails = {
+    stream: 'transactional' | 'product';
+    /** Today's recipient limit for this stream. */
+    daily_limit: number;
+    /** Recipients already sent today on this stream. */
+    used_today: number;
+    /** Recipients (to + cc + bcc) in the refused send. */
+    recipients: number;
+    /** Ramp-up stage, 1-based; null with a fixed limit set by support. */
+    ramp_stage: number | null;
+    /** The next 00:00 UTC, ISO 8601. */
+    resets_at: string;
+};
 /** Event types accepted by `POST /emails/test`. */
 type EmailWebhookEventType = 'email.received' | 'email.sent' | 'email.delivered' | 'email.delivery_delayed' | 'email.bounced' | 'email.complained' | 'email.opened' | 'email.clicked' | 'email.failed' | 'email.suppressed' | 'email.scheduled';
 type TestEmailWebhookParams = {
@@ -1139,9 +1202,15 @@ declare class Groundmail {
     /** Import from SendGrid, Postmark or Mailgun (Beta). */
     readonly migrations: MigrationsResource;
     constructor(apiKey: string, options?: GroundmailOptions);
+    /**
+     * Check one address with Groundmail validation before you accept it (for
+     * example on a signup form): syntax, mail server, disposable and role
+     * addresses, recent hard bounces, and a typo suggestion. Free; sends nothing.
+     */
+    validate(email: string): Promise<ValidateEmailResult>;
     get baseUrl(): string;
     get fetchImpl(): typeof fetch;
     request<T>(path: string, init: RequestInit): Promise<T>;
 }
 
-export { type EmailWebhookEventType as $, type ApiErrorBody as A, type BatchSendEmailResult as B, type CategoryUnsubscribedErrorDetails as C, type DnsRecord as D, type CreateSuppressionParams as E, type CreateTemplateParams as F, Groundmail as G, type CreateWebhookParams as H, DEFAULT_API_BASE_URL as I, type DeliverabilityBucket as J, type DeliverabilityDomainInsight as K, type DeliverabilityInsightsResult as L, type DeliverabilityMailServerRelay as M, type DeliverabilityWindow as N, type DnsProviderName as O, type Domain as P, type DomainBimiAnalysis as Q, type DomainDetailResult as R, type SendEmailResult as S, type DomainDmarcAnalysis as T, type DomainDnsAnalysis as U, type DomainStatus as V, type DomainTlsMode as W, type DomainTrackingDns as X, type DomainTrackingStatus as Y, type EmailListItem as Z, type EmailWebhookEventPayload as _, type ApiErrorCode as a, type EnrollmentSkip as a0, type EventRecord as a1, type GroundmailOptions as a2, type ListApiKeysParams as a3, type ListApiKeysResult as a4, type ListAutomationRunsParams as a5, type ListAutomationRunsResult as a6, type ListAutomationsResult as a7, type ListDomainsParams as a8, type ListDomainsResult as a9, type TemplateFormat as aA, type TemplateLintWarning as aB, type TemplateStarter as aC, type TemplateStatus as aD, type TemplateVersion as aE, type TestEmailWebhookParams as aF, type TestEmailWebhookResult as aG, type TriggerEventParams as aH, type TriggerEventResult as aI, type TwilioIntegrationResponse as aJ, type TwilioIntegrationStatus as aK, type UpdateAutomationParams as aL, type UpdateDomainParams as aM, type UpdateEmailParams as aN, type UpdateTemplateParams as aO, type UpdateWebhookParams as aP, type VerifyDomainResult as aQ, type WebhookEndpoint as aR, type WebhookEndpointWithSecret as aS, type WebhookEventType as aT, mergeMigrations as aU, type ListEmailsParams as aa, type ListEmailsResult as ab, type ListReceivedEmailsParams as ac, type ListReceivedEmailsResult as ad, type ListSuppressionsParams as ae, type ListSuppressionsResult as af, type ListTemplatesParams as ag, type ListTemplatesResult as ah, type MailServerSigningStatus as ai, type Migration as aj, type MigrationDomainItem as ak, type MigrationItemStatus as al, type MigrationProvider as am, type MigrationResource as an, type MigrationTemplateItem as ao, type MigrationTotals as ap, type MigrationWebhookItem as aq, type ReceivedEmail as ar, type ReceivedEmailAttachment as as, type ReceivedEmailAttachmentMeta as at, type RemoteApplyDnsCredentials as au, type RunMigrationOptions as av, type SendEmailParams as aw, type SuppressedErrorDetails as ax, type Suppression as ay, type Template as az, type ApiKey as b, type ApiKeyScope as c, type ApplyDnsParams as d, type ApplyDnsRecordResult as e, type ApplyDnsResult as f, type Asset as g, type Automation as h, type AutomationResult as i, type AutomationRun as j, type AutomationRunResponse as k, type AutomationRunStatus as l, type AutomationRunStep as m, type AutomationRunStepStatus as n, type AutomationStatus as o, type AutomationStep as p, type AutomationTrigger as q, type BounceType as r, type ConnectTwilioParams as s, type ContactWebhookEventPayload as t, type CreateApiKeyParams as u, type CreateApiKeyResult as v, type CreateAutomationParams as w, type CreateDomainParams as x, type CreateDomainResult as y, type CreateMigrationParams as z };
+export { type EmailWebhookEventPayload as $, type ApiErrorBody as A, type BatchSendEmailResult as B, type CategoryUnsubscribedErrorDetails as C, type DnsRecord as D, type CreateSuppressionParams as E, type CreateTemplateParams as F, Groundmail as G, type CreateWebhookParams as H, DEFAULT_API_BASE_URL as I, type DailyRampLimitErrorDetails as J, type DeliverabilityBucket as K, type DeliverabilityDomainInsight as L, type DeliverabilityInsightsResult as M, type DeliverabilityMailServerRelay as N, type DeliverabilityWindow as O, type DnsProviderName as P, type Domain as Q, type DomainBimiAnalysis as R, type SendEmailResult as S, type DomainDetailResult as T, type DomainDmarcAnalysis as U, type DomainDnsAnalysis as V, type DomainStatus as W, type DomainTlsMode as X, type DomainTrackingDns as Y, type DomainTrackingStatus as Z, type EmailListItem as _, type ApiErrorCode as a, mergeMigrations as a$, type EmailWebhookEventType as a0, type EnrollmentSkip as a1, type EventRecord as a2, type GroundmailOptions as a3, type HeldBackErrorDetails as a4, type HeldBackReason as a5, type HeldBackRecipient as a6, type ListApiKeysParams as a7, type ListApiKeysResult as a8, type ListAutomationRunsParams as a9, type SendEmailParams as aA, type SuppressedErrorDetails as aB, type Suppression as aC, type Template as aD, type TemplateFormat as aE, type TemplateLintWarning as aF, type TemplateStarter as aG, type TemplateStatus as aH, type TemplateVersion as aI, type TestEmailWebhookParams as aJ, type TestEmailWebhookResult as aK, type TriggerEventParams as aL, type TriggerEventResult as aM, type TwilioIntegrationResponse as aN, type TwilioIntegrationStatus as aO, type UpdateAutomationParams as aP, type UpdateDomainParams as aQ, type UpdateEmailParams as aR, type UpdateTemplateParams as aS, type UpdateWebhookParams as aT, type ValidateEmailResult as aU, type ValidationReason as aV, type ValidationVerdict as aW, type VerifyDomainResult as aX, type WebhookEndpoint as aY, type WebhookEndpointWithSecret as aZ, type WebhookEventType as a_, type ListAutomationRunsResult as aa, type ListAutomationsResult as ab, type ListDomainsParams as ac, type ListDomainsResult as ad, type ListEmailsParams as ae, type ListEmailsResult as af, type ListReceivedEmailsParams as ag, type ListReceivedEmailsResult as ah, type ListSuppressionsParams as ai, type ListSuppressionsResult as aj, type ListTemplatesParams as ak, type ListTemplatesResult as al, type MailServerSigningStatus as am, type Migration as an, type MigrationDomainItem as ao, type MigrationItemStatus as ap, type MigrationProvider as aq, type MigrationResource as ar, type MigrationTemplateItem as as, type MigrationTotals as at, type MigrationWebhookItem as au, type ReceivedEmail as av, type ReceivedEmailAttachment as aw, type ReceivedEmailAttachmentMeta as ax, type RemoteApplyDnsCredentials as ay, type RunMigrationOptions as az, type ApiKey as b, type ApiKeyScope as c, type ApplyDnsParams as d, type ApplyDnsRecordResult as e, type ApplyDnsResult as f, type Asset as g, type Automation as h, type AutomationResult as i, type AutomationRun as j, type AutomationRunResponse as k, type AutomationRunStatus as l, type AutomationRunStep as m, type AutomationRunStepStatus as n, type AutomationStatus as o, type AutomationStep as p, type AutomationTrigger as q, type BounceType as r, type ConnectTwilioParams as s, type ContactWebhookEventPayload as t, type CreateApiKeyParams as u, type CreateApiKeyResult as v, type CreateAutomationParams as w, type CreateDomainParams as x, type CreateDomainResult as y, type CreateMigrationParams as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as ApiErrorBody, D as DnsRecord } from './client-UTorFXe6.js';
-export { a as ApiErrorCode, b as ApiKey, c as ApiKeyScope, d as ApplyDnsParams, e as ApplyDnsRecordResult, f as ApplyDnsResult, g as Asset, h as Automation, i as AutomationResult, j as AutomationRun, k as AutomationRunResponse, l as AutomationRunStatus, m as AutomationRunStep, n as AutomationRunStepStatus, o as AutomationStatus, p as AutomationStep, q as AutomationTrigger, B as BatchSendEmailResult, r as BounceType, C as CategoryUnsubscribedErrorDetails, s as ConnectTwilioParams, t as ContactWebhookEventPayload, u as CreateApiKeyParams, v as CreateApiKeyResult, w as CreateAutomationParams, x as CreateDomainParams, y as CreateDomainResult, z as CreateMigrationParams, E as CreateSuppressionParams, F as CreateTemplateParams, H as CreateWebhookParams, I as DEFAULT_API_BASE_URL, J as DeliverabilityBucket, K as DeliverabilityDomainInsight, L as DeliverabilityInsightsResult, M as DeliverabilityMailServerRelay, N as DeliverabilityWindow, O as DnsProviderName, P as Domain, Q as DomainBimiAnalysis, R as DomainDetailResult, T as DomainDmarcAnalysis, U as DomainDnsAnalysis, V as DomainStatus, W as DomainTlsMode, X as DomainTrackingDns, Y as DomainTrackingStatus, Z as EmailListItem, _ as EmailWebhookEventPayload, $ as EmailWebhookEventType, a0 as EnrollmentSkip, a1 as EventRecord, G as Groundmail, a2 as GroundmailOptions, a3 as ListApiKeysParams, a4 as ListApiKeysResult, a5 as ListAutomationRunsParams, a6 as ListAutomationRunsResult, a7 as ListAutomationsResult, a8 as ListDomainsParams, a9 as ListDomainsResult, aa as ListEmailsParams, ab as ListEmailsResult, ac as ListReceivedEmailsParams, ad as ListReceivedEmailsResult, ae as ListSuppressionsParams, af as ListSuppressionsResult, ag as ListTemplatesParams, ah as ListTemplatesResult, ai as MailServerSigningStatus, aj as Migration, ak as MigrationDomainItem, al as MigrationItemStatus, am as MigrationProvider, an as MigrationResource, ao as MigrationTemplateItem, ap as MigrationTotals, aq as MigrationWebhookItem, ar as ReceivedEmail, as as ReceivedEmailAttachment, at as ReceivedEmailAttachmentMeta, au as RemoteApplyDnsCredentials, av as RunMigrationOptions, aw as SendEmailParams, S as SendEmailResult, ax as SuppressedErrorDetails, ay as Suppression, az as Template, aA as TemplateFormat, aB as TemplateLintWarning, aC as TemplateStarter, aD as TemplateStatus, aE as TemplateVersion, aF as TestEmailWebhookParams, aG as TestEmailWebhookResult, aH as TriggerEventParams, aI as TriggerEventResult, aJ as TwilioIntegrationResponse, aK as TwilioIntegrationStatus, aL as UpdateAutomationParams, aM as UpdateDomainParams, aN as UpdateEmailParams, aO as UpdateTemplateParams, aP as UpdateWebhookParams, aQ as VerifyDomainResult, aR as WebhookEndpoint, aS as WebhookEndpointWithSecret, aT as WebhookEventType, aU as mergeMigrations } from './client-UTorFXe6.js';
+import { A as ApiErrorBody, D as DnsRecord } from './client-DYUh2ub4.js';
+export { a as ApiErrorCode, b as ApiKey, c as ApiKeyScope, d as ApplyDnsParams, e as ApplyDnsRecordResult, f as ApplyDnsResult, g as Asset, h as Automation, i as AutomationResult, j as AutomationRun, k as AutomationRunResponse, l as AutomationRunStatus, m as AutomationRunStep, n as AutomationRunStepStatus, o as AutomationStatus, p as AutomationStep, q as AutomationTrigger, B as BatchSendEmailResult, r as BounceType, C as CategoryUnsubscribedErrorDetails, s as ConnectTwilioParams, t as ContactWebhookEventPayload, u as CreateApiKeyParams, v as CreateApiKeyResult, w as CreateAutomationParams, x as CreateDomainParams, y as CreateDomainResult, z as CreateMigrationParams, E as CreateSuppressionParams, F as CreateTemplateParams, H as CreateWebhookParams, I as DEFAULT_API_BASE_URL, J as DailyRampLimitErrorDetails, K as DeliverabilityBucket, L as DeliverabilityDomainInsight, M as DeliverabilityInsightsResult, N as DeliverabilityMailServerRelay, O as DeliverabilityWindow, P as DnsProviderName, Q as Domain, R as DomainBimiAnalysis, T as DomainDetailResult, U as DomainDmarcAnalysis, V as DomainDnsAnalysis, W as DomainStatus, X as DomainTlsMode, Y as DomainTrackingDns, Z as DomainTrackingStatus, _ as EmailListItem, $ as EmailWebhookEventPayload, a0 as EmailWebhookEventType, a1 as EnrollmentSkip, a2 as EventRecord, G as Groundmail, a3 as GroundmailOptions, a4 as HeldBackErrorDetails, a5 as HeldBackReason, a6 as HeldBackRecipient, a7 as ListApiKeysParams, a8 as ListApiKeysResult, a9 as ListAutomationRunsParams, aa as ListAutomationRunsResult, ab as ListAutomationsResult, ac as ListDomainsParams, ad as ListDomainsResult, ae as ListEmailsParams, af as ListEmailsResult, ag as ListReceivedEmailsParams, ah as ListReceivedEmailsResult, ai as ListSuppressionsParams, aj as ListSuppressionsResult, ak as ListTemplatesParams, al as ListTemplatesResult, am as MailServerSigningStatus, an as Migration, ao as MigrationDomainItem, ap as MigrationItemStatus, aq as MigrationProvider, ar as MigrationResource, as as MigrationTemplateItem, at as MigrationTotals, au as MigrationWebhookItem, av as ReceivedEmail, aw as ReceivedEmailAttachment, ax as ReceivedEmailAttachmentMeta, ay as RemoteApplyDnsCredentials, az as RunMigrationOptions, aA as SendEmailParams, S as SendEmailResult, aB as SuppressedErrorDetails, aC as Suppression, aD as Template, aE as TemplateFormat, aF as TemplateLintWarning, aG as TemplateStarter, aH as TemplateStatus, aI as TemplateVersion, aJ as TestEmailWebhookParams, aK as TestEmailWebhookResult, aL as TriggerEventParams, aM as TriggerEventResult, aN as TwilioIntegrationResponse, aO as TwilioIntegrationStatus, aP as UpdateAutomationParams, aQ as UpdateDomainParams, aR as UpdateEmailParams, aS as UpdateTemplateParams, aT as UpdateWebhookParams, aU as ValidateEmailResult, aV as ValidationReason, aW as ValidationVerdict, aX as VerifyDomainResult, aY as WebhookEndpoint, aZ as WebhookEndpointWithSecret, a_ as WebhookEventType, a$ as mergeMigrations } from './client-DYUh2ub4.js';
 
 type GroundmailErrorOptions = {
     code?: string;

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   mergeSpfInclude,
   signWebhookPayload,
   verifyWebhookSignature
-} from "./chunk-LKMNSXA3.js";
+} from "./chunk-N2LD34ND.js";
 export {
   DEFAULT_API_BASE_URL,
   Groundmail,

package/dist/payload.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail } from './client-UTorFXe6.js';
+import { G as Groundmail } from './client-DYUh2ub4.js';
 
 /**
  * Minimal Payload `SendEmailOptions` / address shapes used by this adapter.

package/dist/payload.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_BASE_URL,
   Groundmail
-} from "./chunk-LKMNSXA3.js";
+} from "./chunk-N2LD34ND.js";
 
 // src/payload.ts
 function resolveApiKey(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groundmail",
-  "version": "0.14.8",
+  "version": "0.15.1",
   "description": "Groundmail transactional email API client",
   "license": "MIT",
   "type": "module",
@@ -89,7 +89,7 @@
     "prepublishOnly": "npm run build && npm run build:nodemailer-bridge"
   },
   "dependencies": {
-    "groundmail-nodemailer": "0.14.8"
+    "groundmail-nodemailer": "0.15.1"
   },
   "devDependencies": {
     "@types/nodemailer": "^8.0.1",