@sendly/node 3.27.1 → 3.29.0

package/dist/index.d.mts

@@ -877,7 +877,12 @@ declare const ALL_SUPPORTED_COUNTRIES: string[];
 /**
  * Webhook event types
  */
-type WebhookEventType = "message.sent" | "message.delivered" | "message.failed" | "message.bounced" | "message.retrying" | "message.queued" | "message.received" | "message.opt_out" | "message.opt_in" | "verification.created" | "verification.delivered" | "verification.verified" | "verification.expired" | "verification.failed" | "verification.resent" | "verification.delivery_failed";
+type WebhookEventType = "message.sent" | "message.delivered" | "message.failed" | "message.bounced" | "message.retrying" | "message.queued" | "message.received" | "message.opt_out" | "message.opt_in" | "verification.created" | "verification.delivered" | "verification.verified" | "verification.expired" | "verification.failed" | "verification.resent" | "verification.delivery_failed" | "contact.auto_flagged" | "contact.marked_valid" | "contacts.lookup_completed" | "contacts.bulk_marked_valid";
+/**
+ * Source of a list-health event. Frozen enum — new values will be
+ * added in minor SDK versions, never removed.
+ */
+type ListHealthEventSource = "send_failure" | "carrier_lookup" | "user_action" | "bulk_mark_valid";
 /**
  * Webhook mode - filters which events are delivered
  * - "all": Receives all events (sandbox + production)
@@ -1527,6 +1532,39 @@ interface Contact {
      * Whether the contact has opted out
      */
     optedOut?: boolean;
+    /**
+     * Carrier-reported line type for this number. One of: `mobile`, `voip`,
+     * `toll free`, `fixed line`, `fixed line or mobile`, `pager`, `voicemail`,
+     * `shared cost`, `premium rate`, `uan`, `personal number`, `unknown`.
+     * Populated after a carrier lookup (either automatic or via checkNumbers).
+     */
+    lineType?: string | null;
+    /**
+     * Carrier name reported by the lookup (e.g., "AT&T", "Verizon").
+     */
+    carrierName?: string | null;
+    /**
+     * When the carrier lookup last ran for this contact.
+     */
+    lineTypeCheckedAt?: string | null;
+    /**
+     * Reason this contact is excluded from future campaigns. One of:
+     * `landline`, `invalid_number`, `non_sms_capable`. Set automatically
+     * after terminal send failures or by a carrier lookup. Clear it with
+     * `contacts.markValid(id)`.
+     */
+    invalidReason?: string | null;
+    /**
+     * When the invalid flag was set.
+     */
+    invalidatedAt?: string | null;
+    /**
+     * When a user manually cleared an auto-flag on this contact. Carrier
+     * re-checks that would re-flag the contact as invalid respect this
+     * timestamp and leave the contact clean, so your manual decisions
+     * survive future lookups.
+     */
+    userMarkedValidAt?: string | null;
     /**
      * When the contact was created
      */
@@ -1543,6 +1581,38 @@ interface Contact {
         name: string;
     }>;
 }
+/**
+ * Response from triggering a bulk carrier lookup via `contacts.checkNumbers()`.
+ */
+interface CheckNumbersResponse {
+    success: boolean;
+    /**
+     * True if a carrier lookup for this scope was already running when you
+     * called this. The dashboard renders an "already in progress" toast when
+     * it sees this flag; server-side integrators can treat it as a soft
+     * no-op and wait for `contacts.lookup_completed` webhook.
+     */
+    alreadyRunning?: boolean;
+    message?: string;
+}
+/**
+ * Scope for `contacts.bulkMarkValid()`. Pass either an explicit id array
+ * (up to 10,000 per call) OR a `listId` — not both. Foreign ids silently
+ * no-op via the per-org filter.
+ */
+interface BulkMarkValidOptions {
+    /** Explicit contact ids to clear (max 10,000). */
+    ids?: string[];
+    /** Clear every flagged member of this list. */
+    listId?: string;
+}
+/**
+ * Response from `contacts.bulkMarkValid()`.
+ */
+interface BulkMarkValidResponse {
+    /** Number of contacts whose invalid flag was actually cleared. */
+    cleared: number;
+}
 /**
  * Request to create a contact
  */
@@ -3459,6 +3529,77 @@ declare class ContactsResource {
      */
     delete(id: string): Promise<void>;
     import(request: ImportContactsRequest): Promise<ImportContactsResponse>;
+    /**
+     * Clear the invalid flag on a contact so future campaigns include it again.
+     *
+     * Contacts get auto-flagged as invalid when a send fails with a terminal
+     * bad-number error (landline, invalid number) or when a carrier lookup
+     * reports they can't receive SMS. Use this when you disagree with the
+     * auto-flag — e.g. the recipient ported from a landline to mobile.
+     *
+     * @param id - Contact ID
+     * @returns The contact with the flag cleared
+     *
+     * @example
+     * ```typescript
+     * const contact = await sendly.contacts.markValid('cnt_xxx');
+     * console.log(contact.invalidReason); // null
+     * ```
+     */
+    markValid(id: string): Promise<Contact>;
+    /**
+     * Clear the invalid flag on many contacts at once — the escape hatch
+     * for when auto-flag misclassifies at scale. Pass either an explicit
+     * id array (up to 10,000 per call) OR a `listId`, not both. Foreign
+     * ids silently no-op via the per-organization filter.
+     *
+     * @param options - `{ ids }` or `{ listId }`
+     * @returns `{ cleared }` — number of contacts whose flag was actually
+     *          cleared. Already-clean contacts and foreign ids don't count.
+     *
+     * @example
+     * ```typescript
+     * // Clear a specific set of ids
+     * const { cleared } = await sendly.contacts.bulkMarkValid({
+     *   ids: ['cnt_abc', 'cnt_def', 'cnt_ghi'],
+     * });
+     *
+     * // Clear every flagged member of a list
+     * await sendly.contacts.bulkMarkValid({ listId: 'lst_xxx' });
+     * ```
+     */
+    bulkMarkValid(options: BulkMarkValidOptions): Promise<BulkMarkValidResponse>;
+    /**
+     * Trigger a background carrier lookup across your contacts. Landlines and
+     * other non-SMS-capable numbers are auto-excluded from future campaigns.
+     *
+     * The lookup runs asynchronously and takes 1–5 minutes depending on list
+     * size. Results populate the `lineType`, `carrierName`, and `invalidReason`
+     * fields on affected contacts — fetch the contact again after a few minutes
+     * to see updated state.
+     *
+     * Idempotent: re-triggering while a lookup is already running for the same
+     * scope is a no-op.
+     *
+     * @param options - Optional: scope to a single list, or force re-check
+     * @returns Acknowledgement
+     *
+     * @example
+     * ```typescript
+     * // Check all un-checked contacts
+     * await sendly.contacts.checkNumbers();
+     *
+     * // Check a specific list only
+     * await sendly.contacts.checkNumbers({ listId: 'lst_xxx' });
+     *
+     * // Re-check contacts even if previously looked up
+     * await sendly.contacts.checkNumbers({ force: true });
+     * ```
+     */
+    checkNumbers(options?: {
+        listId?: string;
+        force?: boolean;
+    }): Promise<CheckNumbersResponse>;
     private transformContact;
 }
 /**
@@ -4480,4 +4621,4 @@ declare class Webhooks {
  */
 type WebhookMessageData = WebhookMessageObject;
 
-export { ALL_SUPPORTED_COUNTRIES, type Account, type AddLabelsRequest, type AnalyticsOverview, type AnalyticsPeriod, type ApiErrorResponse, type ApiKey, AuthenticationError, type AutoTopUpSettings, type BatchListResponse, type BatchMessageItem, type BatchMessageRequest, type BatchMessageResponse, type BatchMessageResult, type BatchStatus, type BillingBreakdown, type BillingBreakdownOptions, type BulkProvisionResult, type BulkProvisionResultItem, type BulkProvisionWorkspace, CREDITS_PER_SMS, type Campaign, type CampaignListResponse, type CampaignPreview, type CampaignStatus, type CancelledMessageResponse, type CheckVerificationRequest, type CheckVerificationResponse, type CircuitState, type Contact, type ContactList, type ContactListResponse, type ContactListsResponse, type Conversation, type ConversationListResponse, type ConversationStatus, type ConversationWithMessages, type CreateCampaignRequest, type CreateContactListRequest, type CreateContactRequest, type CreateDraftRequest, type CreateKeyOptions, type CreateLabelRequest, type CreateOptInPageOptions, type CreateOptInPageResult, type CreateTemplateRequest, type CreateVerifySessionRequest, type CreateWebhookOptions, type CreateWorkspaceOptions, type CreatedApiKey, type CreditAnalytics, type CreditAnalyticsDataPoint, type CreditTransaction, type Credits, type DeliveryAnalyticsItem, type DeliveryStatus, type DnsRecord, type DraftListResponse, type DraftStatus, type EnterpriseAccount, type EnterpriseWebhook, type EnterpriseWebhookTestResult, type EnterpriseWorkspace, type EnterpriseWorkspaceDetail, type EnterpriseWorkspaceSummary, type GenerateBusinessPageOptions, type GenerateBusinessPageResponse, type GetConversationOptions, type ImportContactItem, type ImportContactsError, type ImportContactsRequest, type ImportContactsResponse, InsufficientCreditsError, type Invitation, type Label, type LabelListResponse, type ListBatchesOptions, type ListCampaignsOptions, type ListContactsOptions, type ListConversationsOptions, type ListDraftsOptions, type ListMessagesOptions, type ListScheduledMessagesOptions, type ListVerificationsOptions, type MediaFile, type MediaUploadOptions, type Message, type MessageAnalytics, type MessageAnalyticsDataPoint, type MessageDraft, type MessageListResponse, type MessageStatus, type MessageType, NetworkError, NotFoundError, type OptInPage, type PricingTier, type ProvisionWorkspaceOptions, type ProvisionWorkspaceResult, type QuotaSettings, RateLimitError, type RateLimitInfo, type ReplyToConversationRequest, type ResumeWorkspaceResult, SANDBOX_TEST_NUMBERS, SUPPORTED_COUNTRIES, type ScheduleCampaignRequest, type ScheduleMessageRequest, type ScheduledMessage, type ScheduledMessageListResponse, type ScheduledMessageStatus, type SendInvitationOptions, type SendMessageRequest, type SendVerificationRequest, type SendVerificationResponse, type SenderType, Sendly, type SendlyConfig, SendlyError, type SendlyErrorCode, type SetCustomDomainResult, type SetWorkspaceWebhookOptions, type SetWorkspaceWebhookResult, type SuggestRepliesResponse, type SuggestedReply, type SuspendWorkspaceOptions, type SuspendWorkspaceResult, type Template, type TemplateListResponse, type TemplatePreview, type TemplateStatus, type TemplateVariable, TimeoutError, type TransferCreditsOptions, type TransferCreditsResult, type UpdateAutoTopUpOptions, type UpdateCampaignRequest, type UpdateContactListRequest, type UpdateContactRequest, type UpdateConversationRequest, type UpdateDraftRequest, type UpdateOptInPageOptions, type UpdateQuotaOptions, type UpdateTemplateRequest, type UpdateWebhookOptions, type ValidateSessionTokenRequest, type ValidateSessionTokenResponse, ValidationError, type Verification, type VerificationDeliveryStatus, type VerificationListResponse, type VerificationStatus, type VerifySession, type VerifySessionStatus, type Webhook, type WebhookCreatedResponse, type WebhookDelivery, type WebhookEvent, type WebhookEventType, type WebhookMessageData, type WebhookMessageStatus, type WebhookSecretRotation, WebhookSignatureError, type WebhookTestResult, Webhooks, type WorkspaceBillingItem, type WorkspaceCredits, type WorkspaceWebhook, calculateSegments, Sendly as default, generateWebhookSignature, getCountryFromPhone, isCountrySupported, parseWebhookEvent, validateMessageText, validatePhoneNumber, validateSenderId, verifyWebhookSignature };
+export { ALL_SUPPORTED_COUNTRIES, type Account, type AddLabelsRequest, type AnalyticsOverview, type AnalyticsPeriod, type ApiErrorResponse, type ApiKey, AuthenticationError, type AutoTopUpSettings, type BatchListResponse, type BatchMessageItem, type BatchMessageRequest, type BatchMessageResponse, type BatchMessageResult, type BatchStatus, type BillingBreakdown, type BillingBreakdownOptions, type BulkMarkValidOptions, type BulkMarkValidResponse, type BulkProvisionResult, type BulkProvisionResultItem, type BulkProvisionWorkspace, CREDITS_PER_SMS, type Campaign, type CampaignListResponse, type CampaignPreview, type CampaignStatus, type CancelledMessageResponse, type CheckNumbersResponse, type CheckVerificationRequest, type CheckVerificationResponse, type CircuitState, type Contact, type ContactList, type ContactListResponse, type ContactListsResponse, type Conversation, type ConversationListResponse, type ConversationStatus, type ConversationWithMessages, type CreateCampaignRequest, type CreateContactListRequest, type CreateContactRequest, type CreateDraftRequest, type CreateKeyOptions, type CreateLabelRequest, type CreateOptInPageOptions, type CreateOptInPageResult, type CreateTemplateRequest, type CreateVerifySessionRequest, type CreateWebhookOptions, type CreateWorkspaceOptions, type CreatedApiKey, type CreditAnalytics, type CreditAnalyticsDataPoint, type CreditTransaction, type Credits, type DeliveryAnalyticsItem, type DeliveryStatus, type DnsRecord, type DraftListResponse, type DraftStatus, type EnterpriseAccount, type EnterpriseWebhook, type EnterpriseWebhookTestResult, type EnterpriseWorkspace, type EnterpriseWorkspaceDetail, type EnterpriseWorkspaceSummary, type GenerateBusinessPageOptions, type GenerateBusinessPageResponse, type GetConversationOptions, type ImportContactItem, type ImportContactsError, type ImportContactsRequest, type ImportContactsResponse, InsufficientCreditsError, type Invitation, type Label, type LabelListResponse, type ListBatchesOptions, type ListCampaignsOptions, type ListContactsOptions, type ListConversationsOptions, type ListDraftsOptions, type ListHealthEventSource, type ListMessagesOptions, type ListScheduledMessagesOptions, type ListVerificationsOptions, type MediaFile, type MediaUploadOptions, type Message, type MessageAnalytics, type MessageAnalyticsDataPoint, type MessageDraft, type MessageListResponse, type MessageStatus, type MessageType, NetworkError, NotFoundError, type OptInPage, type PricingTier, type ProvisionWorkspaceOptions, type ProvisionWorkspaceResult, type QuotaSettings, RateLimitError, type RateLimitInfo, type ReplyToConversationRequest, type ResumeWorkspaceResult, SANDBOX_TEST_NUMBERS, SUPPORTED_COUNTRIES, type ScheduleCampaignRequest, type ScheduleMessageRequest, type ScheduledMessage, type ScheduledMessageListResponse, type ScheduledMessageStatus, type SendInvitationOptions, type SendMessageRequest, type SendVerificationRequest, type SendVerificationResponse, type SenderType, Sendly, type SendlyConfig, SendlyError, type SendlyErrorCode, type SetCustomDomainResult, type SetWorkspaceWebhookOptions, type SetWorkspaceWebhookResult, type SuggestRepliesResponse, type SuggestedReply, type SuspendWorkspaceOptions, type SuspendWorkspaceResult, type Template, type TemplateListResponse, type TemplatePreview, type TemplateStatus, type TemplateVariable, TimeoutError, type TransferCreditsOptions, type TransferCreditsResult, type UpdateAutoTopUpOptions, type UpdateCampaignRequest, type UpdateContactListRequest, type UpdateContactRequest, type UpdateConversationRequest, type UpdateDraftRequest, type UpdateOptInPageOptions, type UpdateQuotaOptions, type UpdateTemplateRequest, type UpdateWebhookOptions, type ValidateSessionTokenRequest, type ValidateSessionTokenResponse, ValidationError, type Verification, type VerificationDeliveryStatus, type VerificationListResponse, type VerificationStatus, type VerifySession, type VerifySessionStatus, type Webhook, type WebhookCreatedResponse, type WebhookDelivery, type WebhookEvent, type WebhookEventType, type WebhookMessageData, type WebhookMessageStatus, type WebhookSecretRotation, WebhookSignatureError, type WebhookTestResult, Webhooks, type WorkspaceBillingItem, type WorkspaceCredits, type WorkspaceWebhook, calculateSegments, Sendly as default, generateWebhookSignature, getCountryFromPhone, isCountrySupported, parseWebhookEvent, validateMessageText, validatePhoneNumber, validateSenderId, verifyWebhookSignature };

package/dist/index.d.ts

@@ -877,7 +877,12 @@ declare const ALL_SUPPORTED_COUNTRIES: string[];
 /**
  * Webhook event types
  */
-type WebhookEventType = "message.sent" | "message.delivered" | "message.failed" | "message.bounced" | "message.retrying" | "message.queued" | "message.received" | "message.opt_out" | "message.opt_in" | "verification.created" | "verification.delivered" | "verification.verified" | "verification.expired" | "verification.failed" | "verification.resent" | "verification.delivery_failed";
+type WebhookEventType = "message.sent" | "message.delivered" | "message.failed" | "message.bounced" | "message.retrying" | "message.queued" | "message.received" | "message.opt_out" | "message.opt_in" | "verification.created" | "verification.delivered" | "verification.verified" | "verification.expired" | "verification.failed" | "verification.resent" | "verification.delivery_failed" | "contact.auto_flagged" | "contact.marked_valid" | "contacts.lookup_completed" | "contacts.bulk_marked_valid";
+/**
+ * Source of a list-health event. Frozen enum — new values will be
+ * added in minor SDK versions, never removed.
+ */
+type ListHealthEventSource = "send_failure" | "carrier_lookup" | "user_action" | "bulk_mark_valid";
 /**
  * Webhook mode - filters which events are delivered
  * - "all": Receives all events (sandbox + production)
@@ -1527,6 +1532,39 @@ interface Contact {
      * Whether the contact has opted out
      */
     optedOut?: boolean;
+    /**
+     * Carrier-reported line type for this number. One of: `mobile`, `voip`,
+     * `toll free`, `fixed line`, `fixed line or mobile`, `pager`, `voicemail`,
+     * `shared cost`, `premium rate`, `uan`, `personal number`, `unknown`.
+     * Populated after a carrier lookup (either automatic or via checkNumbers).
+     */
+    lineType?: string | null;
+    /**
+     * Carrier name reported by the lookup (e.g., "AT&T", "Verizon").
+     */
+    carrierName?: string | null;
+    /**
+     * When the carrier lookup last ran for this contact.
+     */
+    lineTypeCheckedAt?: string | null;
+    /**
+     * Reason this contact is excluded from future campaigns. One of:
+     * `landline`, `invalid_number`, `non_sms_capable`. Set automatically
+     * after terminal send failures or by a carrier lookup. Clear it with
+     * `contacts.markValid(id)`.
+     */
+    invalidReason?: string | null;
+    /**
+     * When the invalid flag was set.
+     */
+    invalidatedAt?: string | null;
+    /**
+     * When a user manually cleared an auto-flag on this contact. Carrier
+     * re-checks that would re-flag the contact as invalid respect this
+     * timestamp and leave the contact clean, so your manual decisions
+     * survive future lookups.
+     */
+    userMarkedValidAt?: string | null;
     /**
      * When the contact was created
      */
@@ -1543,6 +1581,38 @@ interface Contact {
         name: string;
     }>;
 }
+/**
+ * Response from triggering a bulk carrier lookup via `contacts.checkNumbers()`.
+ */
+interface CheckNumbersResponse {
+    success: boolean;
+    /**
+     * True if a carrier lookup for this scope was already running when you
+     * called this. The dashboard renders an "already in progress" toast when
+     * it sees this flag; server-side integrators can treat it as a soft
+     * no-op and wait for `contacts.lookup_completed` webhook.
+     */
+    alreadyRunning?: boolean;
+    message?: string;
+}
+/**
+ * Scope for `contacts.bulkMarkValid()`. Pass either an explicit id array
+ * (up to 10,000 per call) OR a `listId` — not both. Foreign ids silently
+ * no-op via the per-org filter.
+ */
+interface BulkMarkValidOptions {
+    /** Explicit contact ids to clear (max 10,000). */
+    ids?: string[];
+    /** Clear every flagged member of this list. */
+    listId?: string;
+}
+/**
+ * Response from `contacts.bulkMarkValid()`.
+ */
+interface BulkMarkValidResponse {
+    /** Number of contacts whose invalid flag was actually cleared. */
+    cleared: number;
+}
 /**
  * Request to create a contact
  */
@@ -3459,6 +3529,77 @@ declare class ContactsResource {
      */
     delete(id: string): Promise<void>;
     import(request: ImportContactsRequest): Promise<ImportContactsResponse>;
+    /**
+     * Clear the invalid flag on a contact so future campaigns include it again.
+     *
+     * Contacts get auto-flagged as invalid when a send fails with a terminal
+     * bad-number error (landline, invalid number) or when a carrier lookup
+     * reports they can't receive SMS. Use this when you disagree with the
+     * auto-flag — e.g. the recipient ported from a landline to mobile.
+     *
+     * @param id - Contact ID
+     * @returns The contact with the flag cleared
+     *
+     * @example
+     * ```typescript
+     * const contact = await sendly.contacts.markValid('cnt_xxx');
+     * console.log(contact.invalidReason); // null
+     * ```
+     */
+    markValid(id: string): Promise<Contact>;
+    /**
+     * Clear the invalid flag on many contacts at once — the escape hatch
+     * for when auto-flag misclassifies at scale. Pass either an explicit
+     * id array (up to 10,000 per call) OR a `listId`, not both. Foreign
+     * ids silently no-op via the per-organization filter.
+     *
+     * @param options - `{ ids }` or `{ listId }`
+     * @returns `{ cleared }` — number of contacts whose flag was actually
+     *          cleared. Already-clean contacts and foreign ids don't count.
+     *
+     * @example
+     * ```typescript
+     * // Clear a specific set of ids
+     * const { cleared } = await sendly.contacts.bulkMarkValid({
+     *   ids: ['cnt_abc', 'cnt_def', 'cnt_ghi'],
+     * });
+     *
+     * // Clear every flagged member of a list
+     * await sendly.contacts.bulkMarkValid({ listId: 'lst_xxx' });
+     * ```
+     */
+    bulkMarkValid(options: BulkMarkValidOptions): Promise<BulkMarkValidResponse>;
+    /**
+     * Trigger a background carrier lookup across your contacts. Landlines and
+     * other non-SMS-capable numbers are auto-excluded from future campaigns.
+     *
+     * The lookup runs asynchronously and takes 1–5 minutes depending on list
+     * size. Results populate the `lineType`, `carrierName`, and `invalidReason`
+     * fields on affected contacts — fetch the contact again after a few minutes
+     * to see updated state.
+     *
+     * Idempotent: re-triggering while a lookup is already running for the same
+     * scope is a no-op.
+     *
+     * @param options - Optional: scope to a single list, or force re-check
+     * @returns Acknowledgement
+     *
+     * @example
+     * ```typescript
+     * // Check all un-checked contacts
+     * await sendly.contacts.checkNumbers();
+     *
+     * // Check a specific list only
+     * await sendly.contacts.checkNumbers({ listId: 'lst_xxx' });
+     *
+     * // Re-check contacts even if previously looked up
+     * await sendly.contacts.checkNumbers({ force: true });
+     * ```
+     */
+    checkNumbers(options?: {
+        listId?: string;
+        force?: boolean;
+    }): Promise<CheckNumbersResponse>;
     private transformContact;
 }
 /**
@@ -4480,4 +4621,4 @@ declare class Webhooks {
  */
 type WebhookMessageData = WebhookMessageObject;
 
-export { ALL_SUPPORTED_COUNTRIES, type Account, type AddLabelsRequest, type AnalyticsOverview, type AnalyticsPeriod, type ApiErrorResponse, type ApiKey, AuthenticationError, type AutoTopUpSettings, type BatchListResponse, type BatchMessageItem, type BatchMessageRequest, type BatchMessageResponse, type BatchMessageResult, type BatchStatus, type BillingBreakdown, type BillingBreakdownOptions, type BulkProvisionResult, type BulkProvisionResultItem, type BulkProvisionWorkspace, CREDITS_PER_SMS, type Campaign, type CampaignListResponse, type CampaignPreview, type CampaignStatus, type CancelledMessageResponse, type CheckVerificationRequest, type CheckVerificationResponse, type CircuitState, type Contact, type ContactList, type ContactListResponse, type ContactListsResponse, type Conversation, type ConversationListResponse, type ConversationStatus, type ConversationWithMessages, type CreateCampaignRequest, type CreateContactListRequest, type CreateContactRequest, type CreateDraftRequest, type CreateKeyOptions, type CreateLabelRequest, type CreateOptInPageOptions, type CreateOptInPageResult, type CreateTemplateRequest, type CreateVerifySessionRequest, type CreateWebhookOptions, type CreateWorkspaceOptions, type CreatedApiKey, type CreditAnalytics, type CreditAnalyticsDataPoint, type CreditTransaction, type Credits, type DeliveryAnalyticsItem, type DeliveryStatus, type DnsRecord, type DraftListResponse, type DraftStatus, type EnterpriseAccount, type EnterpriseWebhook, type EnterpriseWebhookTestResult, type EnterpriseWorkspace, type EnterpriseWorkspaceDetail, type EnterpriseWorkspaceSummary, type GenerateBusinessPageOptions, type GenerateBusinessPageResponse, type GetConversationOptions, type ImportContactItem, type ImportContactsError, type ImportContactsRequest, type ImportContactsResponse, InsufficientCreditsError, type Invitation, type Label, type LabelListResponse, type ListBatchesOptions, type ListCampaignsOptions, type ListContactsOptions, type ListConversationsOptions, type ListDraftsOptions, type ListMessagesOptions, type ListScheduledMessagesOptions, type ListVerificationsOptions, type MediaFile, type MediaUploadOptions, type Message, type MessageAnalytics, type MessageAnalyticsDataPoint, type MessageDraft, type MessageListResponse, type MessageStatus, type MessageType, NetworkError, NotFoundError, type OptInPage, type PricingTier, type ProvisionWorkspaceOptions, type ProvisionWorkspaceResult, type QuotaSettings, RateLimitError, type RateLimitInfo, type ReplyToConversationRequest, type ResumeWorkspaceResult, SANDBOX_TEST_NUMBERS, SUPPORTED_COUNTRIES, type ScheduleCampaignRequest, type ScheduleMessageRequest, type ScheduledMessage, type ScheduledMessageListResponse, type ScheduledMessageStatus, type SendInvitationOptions, type SendMessageRequest, type SendVerificationRequest, type SendVerificationResponse, type SenderType, Sendly, type SendlyConfig, SendlyError, type SendlyErrorCode, type SetCustomDomainResult, type SetWorkspaceWebhookOptions, type SetWorkspaceWebhookResult, type SuggestRepliesResponse, type SuggestedReply, type SuspendWorkspaceOptions, type SuspendWorkspaceResult, type Template, type TemplateListResponse, type TemplatePreview, type TemplateStatus, type TemplateVariable, TimeoutError, type TransferCreditsOptions, type TransferCreditsResult, type UpdateAutoTopUpOptions, type UpdateCampaignRequest, type UpdateContactListRequest, type UpdateContactRequest, type UpdateConversationRequest, type UpdateDraftRequest, type UpdateOptInPageOptions, type UpdateQuotaOptions, type UpdateTemplateRequest, type UpdateWebhookOptions, type ValidateSessionTokenRequest, type ValidateSessionTokenResponse, ValidationError, type Verification, type VerificationDeliveryStatus, type VerificationListResponse, type VerificationStatus, type VerifySession, type VerifySessionStatus, type Webhook, type WebhookCreatedResponse, type WebhookDelivery, type WebhookEvent, type WebhookEventType, type WebhookMessageData, type WebhookMessageStatus, type WebhookSecretRotation, WebhookSignatureError, type WebhookTestResult, Webhooks, type WorkspaceBillingItem, type WorkspaceCredits, type WorkspaceWebhook, calculateSegments, Sendly as default, generateWebhookSignature, getCountryFromPhone, isCountrySupported, parseWebhookEvent, validateMessageText, validatePhoneNumber, validateSenderId, verifyWebhookSignature };
+export { ALL_SUPPORTED_COUNTRIES, type Account, type AddLabelsRequest, type AnalyticsOverview, type AnalyticsPeriod, type ApiErrorResponse, type ApiKey, AuthenticationError, type AutoTopUpSettings, type BatchListResponse, type BatchMessageItem, type BatchMessageRequest, type BatchMessageResponse, type BatchMessageResult, type BatchStatus, type BillingBreakdown, type BillingBreakdownOptions, type BulkMarkValidOptions, type BulkMarkValidResponse, type BulkProvisionResult, type BulkProvisionResultItem, type BulkProvisionWorkspace, CREDITS_PER_SMS, type Campaign, type CampaignListResponse, type CampaignPreview, type CampaignStatus, type CancelledMessageResponse, type CheckNumbersResponse, type CheckVerificationRequest, type CheckVerificationResponse, type CircuitState, type Contact, type ContactList, type ContactListResponse, type ContactListsResponse, type Conversation, type ConversationListResponse, type ConversationStatus, type ConversationWithMessages, type CreateCampaignRequest, type CreateContactListRequest, type CreateContactRequest, type CreateDraftRequest, type CreateKeyOptions, type CreateLabelRequest, type CreateOptInPageOptions, type CreateOptInPageResult, type CreateTemplateRequest, type CreateVerifySessionRequest, type CreateWebhookOptions, type CreateWorkspaceOptions, type CreatedApiKey, type CreditAnalytics, type CreditAnalyticsDataPoint, type CreditTransaction, type Credits, type DeliveryAnalyticsItem, type DeliveryStatus, type DnsRecord, type DraftListResponse, type DraftStatus, type EnterpriseAccount, type EnterpriseWebhook, type EnterpriseWebhookTestResult, type EnterpriseWorkspace, type EnterpriseWorkspaceDetail, type EnterpriseWorkspaceSummary, type GenerateBusinessPageOptions, type GenerateBusinessPageResponse, type GetConversationOptions, type ImportContactItem, type ImportContactsError, type ImportContactsRequest, type ImportContactsResponse, InsufficientCreditsError, type Invitation, type Label, type LabelListResponse, type ListBatchesOptions, type ListCampaignsOptions, type ListContactsOptions, type ListConversationsOptions, type ListDraftsOptions, type ListHealthEventSource, type ListMessagesOptions, type ListScheduledMessagesOptions, type ListVerificationsOptions, type MediaFile, type MediaUploadOptions, type Message, type MessageAnalytics, type MessageAnalyticsDataPoint, type MessageDraft, type MessageListResponse, type MessageStatus, type MessageType, NetworkError, NotFoundError, type OptInPage, type PricingTier, type ProvisionWorkspaceOptions, type ProvisionWorkspaceResult, type QuotaSettings, RateLimitError, type RateLimitInfo, type ReplyToConversationRequest, type ResumeWorkspaceResult, SANDBOX_TEST_NUMBERS, SUPPORTED_COUNTRIES, type ScheduleCampaignRequest, type ScheduleMessageRequest, type ScheduledMessage, type ScheduledMessageListResponse, type ScheduledMessageStatus, type SendInvitationOptions, type SendMessageRequest, type SendVerificationRequest, type SendVerificationResponse, type SenderType, Sendly, type SendlyConfig, SendlyError, type SendlyErrorCode, type SetCustomDomainResult, type SetWorkspaceWebhookOptions, type SetWorkspaceWebhookResult, type SuggestRepliesResponse, type SuggestedReply, type SuspendWorkspaceOptions, type SuspendWorkspaceResult, type Template, type TemplateListResponse, type TemplatePreview, type TemplateStatus, type TemplateVariable, TimeoutError, type TransferCreditsOptions, type TransferCreditsResult, type UpdateAutoTopUpOptions, type UpdateCampaignRequest, type UpdateContactListRequest, type UpdateContactRequest, type UpdateConversationRequest, type UpdateDraftRequest, type UpdateOptInPageOptions, type UpdateQuotaOptions, type UpdateTemplateRequest, type UpdateWebhookOptions, type ValidateSessionTokenRequest, type ValidateSessionTokenResponse, ValidationError, type Verification, type VerificationDeliveryStatus, type VerificationListResponse, type VerificationStatus, type VerifySession, type VerifySessionStatus, type Webhook, type WebhookCreatedResponse, type WebhookDelivery, type WebhookEvent, type WebhookEventType, type WebhookMessageData, type WebhookMessageStatus, type WebhookSecretRotation, WebhookSignatureError, type WebhookTestResult, Webhooks, type WorkspaceBillingItem, type WorkspaceCredits, type WorkspaceWebhook, calculateSegments, Sendly as default, generateWebhookSignature, getCountryFromPhone, isCountrySupported, parseWebhookEvent, validateMessageText, validatePhoneNumber, validateSenderId, verifyWebhookSignature };

package/dist/index.js

@@ -2610,16 +2610,118 @@ var ContactsResource = class {
       body
     });
   }
+  /**
+   * Clear the invalid flag on a contact so future campaigns include it again.
+   *
+   * Contacts get auto-flagged as invalid when a send fails with a terminal
+   * bad-number error (landline, invalid number) or when a carrier lookup
+   * reports they can't receive SMS. Use this when you disagree with the
+   * auto-flag — e.g. the recipient ported from a landline to mobile.
+   *
+   * @param id - Contact ID
+   * @returns The contact with the flag cleared
+   *
+   * @example
+   * ```typescript
+   * const contact = await sendly.contacts.markValid('cnt_xxx');
+   * console.log(contact.invalidReason); // null
+   * ```
+   */
+  async markValid(id) {
+    const response = await this.http.request({
+      method: "POST",
+      path: `/contacts/${id}/mark-valid`
+    });
+    return this.transformContact(response);
+  }
+  /**
+   * Clear the invalid flag on many contacts at once — the escape hatch
+   * for when auto-flag misclassifies at scale. Pass either an explicit
+   * id array (up to 10,000 per call) OR a `listId`, not both. Foreign
+   * ids silently no-op via the per-organization filter.
+   *
+   * @param options - `{ ids }` or `{ listId }`
+   * @returns `{ cleared }` — number of contacts whose flag was actually
+   *          cleared. Already-clean contacts and foreign ids don't count.
+   *
+   * @example
+   * ```typescript
+   * // Clear a specific set of ids
+   * const { cleared } = await sendly.contacts.bulkMarkValid({
+   *   ids: ['cnt_abc', 'cnt_def', 'cnt_ghi'],
+   * });
+   *
+   * // Clear every flagged member of a list
+   * await sendly.contacts.bulkMarkValid({ listId: 'lst_xxx' });
+   * ```
+   */
+  async bulkMarkValid(options) {
+    if (!options.ids && !options.listId) {
+      throw new Error("bulkMarkValid requires either 'ids' or 'listId'");
+    }
+    if (options.ids && options.listId) {
+      throw new Error("bulkMarkValid accepts 'ids' OR 'listId', not both");
+    }
+    return this.http.request({
+      method: "POST",
+      path: "/contacts/bulk-mark-valid",
+      body: options.ids ? { ids: options.ids } : { listId: options.listId }
+    });
+  }
+  /**
+   * Trigger a background carrier lookup across your contacts. Landlines and
+   * other non-SMS-capable numbers are auto-excluded from future campaigns.
+   *
+   * The lookup runs asynchronously and takes 1–5 minutes depending on list
+   * size. Results populate the `lineType`, `carrierName`, and `invalidReason`
+   * fields on affected contacts — fetch the contact again after a few minutes
+   * to see updated state.
+   *
+   * Idempotent: re-triggering while a lookup is already running for the same
+   * scope is a no-op.
+   *
+   * @param options - Optional: scope to a single list, or force re-check
+   * @returns Acknowledgement
+   *
+   * @example
+   * ```typescript
+   * // Check all un-checked contacts
+   * await sendly.contacts.checkNumbers();
+   *
+   * // Check a specific list only
+   * await sendly.contacts.checkNumbers({ listId: 'lst_xxx' });
+   *
+   * // Re-check contacts even if previously looked up
+   * await sendly.contacts.checkNumbers({ force: true });
+   * ```
+   */
+  async checkNumbers(options = {}) {
+    return this.http.request({
+      method: "POST",
+      path: "/contacts/lookup",
+      body: {
+        listId: options.listId ?? null,
+        force: options.force ?? false
+      }
+    });
+  }
   transformContact(raw) {
+    const r = raw;
     return {
       id: raw.id,
-      phoneNumber: raw.phone_number,
+      phoneNumber: raw.phone_number ?? r.phoneNumber,
       name: raw.name,
       email: raw.email,
       metadata: raw.metadata,
-      optedOut: raw.opted_out,
-      createdAt: raw.created_at,
-      updatedAt: raw.updated_at,
+      optedOut: raw.opted_out ?? r.optedOut,
+      lineType: raw.line_type ?? r.lineType ?? null,
+      carrierName: raw.carrier_name ?? r.carrierName ?? null,
+      lineTypeCheckedAt: raw.line_type_checked_at ?? r.lineTypeCheckedAt ?? null,
+      invalidReason: raw.invalid_reason ?? r.invalidReason ?? null,
+      invalidatedAt: raw.invalidated_at ?? r.invalidatedAt ?? null,
+      userMarkedValidAt: raw.user_marked_valid_at ?? r.userMarkedValidAt ?? null,
+      createdAt: raw.created_at ?? r.createdAt,
+      updatedAt: raw.updated_at ?? r.updatedAt,
       lists: raw.lists?.map((l) => ({ id: l.id, name: l.name }))
     };
   }

package/dist/index.mjs

@@ -2550,16 +2550,118 @@ var ContactsResource = class {
       body
     });
   }
+  /**
+   * Clear the invalid flag on a contact so future campaigns include it again.
+   *
+   * Contacts get auto-flagged as invalid when a send fails with a terminal
+   * bad-number error (landline, invalid number) or when a carrier lookup
+   * reports they can't receive SMS. Use this when you disagree with the
+   * auto-flag — e.g. the recipient ported from a landline to mobile.
+   *
+   * @param id - Contact ID
+   * @returns The contact with the flag cleared
+   *
+   * @example
+   * ```typescript
+   * const contact = await sendly.contacts.markValid('cnt_xxx');
+   * console.log(contact.invalidReason); // null
+   * ```
+   */
+  async markValid(id) {
+    const response = await this.http.request({
+      method: "POST",
+      path: `/contacts/${id}/mark-valid`
+    });
+    return this.transformContact(response);
+  }
+  /**
+   * Clear the invalid flag on many contacts at once — the escape hatch
+   * for when auto-flag misclassifies at scale. Pass either an explicit
+   * id array (up to 10,000 per call) OR a `listId`, not both. Foreign
+   * ids silently no-op via the per-organization filter.
+   *
+   * @param options - `{ ids }` or `{ listId }`
+   * @returns `{ cleared }` — number of contacts whose flag was actually
+   *          cleared. Already-clean contacts and foreign ids don't count.
+   *
+   * @example
+   * ```typescript
+   * // Clear a specific set of ids
+   * const { cleared } = await sendly.contacts.bulkMarkValid({
+   *   ids: ['cnt_abc', 'cnt_def', 'cnt_ghi'],
+   * });
+   *
+   * // Clear every flagged member of a list
+   * await sendly.contacts.bulkMarkValid({ listId: 'lst_xxx' });
+   * ```
+   */
+  async bulkMarkValid(options) {
+    if (!options.ids && !options.listId) {
+      throw new Error("bulkMarkValid requires either 'ids' or 'listId'");
+    }
+    if (options.ids && options.listId) {
+      throw new Error("bulkMarkValid accepts 'ids' OR 'listId', not both");
+    }
+    return this.http.request({
+      method: "POST",
+      path: "/contacts/bulk-mark-valid",
+      body: options.ids ? { ids: options.ids } : { listId: options.listId }
+    });
+  }
+  /**
+   * Trigger a background carrier lookup across your contacts. Landlines and
+   * other non-SMS-capable numbers are auto-excluded from future campaigns.
+   *
+   * The lookup runs asynchronously and takes 1–5 minutes depending on list
+   * size. Results populate the `lineType`, `carrierName`, and `invalidReason`
+   * fields on affected contacts — fetch the contact again after a few minutes
+   * to see updated state.
+   *
+   * Idempotent: re-triggering while a lookup is already running for the same
+   * scope is a no-op.
+   *
+   * @param options - Optional: scope to a single list, or force re-check
+   * @returns Acknowledgement
+   *
+   * @example
+   * ```typescript
+   * // Check all un-checked contacts
+   * await sendly.contacts.checkNumbers();
+   *
+   * // Check a specific list only
+   * await sendly.contacts.checkNumbers({ listId: 'lst_xxx' });
+   *
+   * // Re-check contacts even if previously looked up
+   * await sendly.contacts.checkNumbers({ force: true });
+   * ```
+   */
+  async checkNumbers(options = {}) {
+    return this.http.request({
+      method: "POST",
+      path: "/contacts/lookup",
+      body: {
+        listId: options.listId ?? null,
+        force: options.force ?? false
+      }
+    });
+  }
   transformContact(raw) {
+    const r = raw;
     return {
       id: raw.id,
-      phoneNumber: raw.phone_number,
+      phoneNumber: raw.phone_number ?? r.phoneNumber,
       name: raw.name,
       email: raw.email,
       metadata: raw.metadata,
-      optedOut: raw.opted_out,
-      createdAt: raw.created_at,
-      updatedAt: raw.updated_at,
+      optedOut: raw.opted_out ?? r.optedOut,
+      lineType: raw.line_type ?? r.lineType ?? null,
+      carrierName: raw.carrier_name ?? r.carrierName ?? null,
+      lineTypeCheckedAt: raw.line_type_checked_at ?? r.lineTypeCheckedAt ?? null,
+      invalidReason: raw.invalid_reason ?? r.invalidReason ?? null,
+      invalidatedAt: raw.invalidated_at ?? r.invalidatedAt ?? null,
+      userMarkedValidAt: raw.user_marked_valid_at ?? r.userMarkedValidAt ?? null,
+      createdAt: raw.created_at ?? r.createdAt,
+      updatedAt: raw.updated_at ?? r.updatedAt,
       lists: raw.lists?.map((l) => ({ id: l.id, name: l.name }))
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendly/node",
-  "version": "3.27.1",
+  "version": "3.29.0",
   "description": "Official Sendly Node.js SDK for SMS messaging",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",