Class: Optail

Constructors

Constructor

new Optail(config: OptailConfig): Optail;

Defined in: sdk/src/client.ts:155

Parameters

Parameter	Type
`config`	`OptailConfig`

Returns

Optail

Methods

send()

send(params: SendEmailParams): Promise<SendEmailResponse>;

Defined in: sdk/src/client.ts:171

Send a single email. Returns immediately with a provider message ID — the email is queued for async delivery and delivery events flow through webhooks.

Parameters

Parameter	Type
`params`	`SendEmailParams`

Returns

Promise<SendEmailResponse>

listTemplates()

listTemplates(params?: ListTemplatesParams): Promise<PaginatedResponse<TemplateResponse>>;

Defined in: sdk/src/client.ts:182

List templates with pagination. Supports name (substring, case-insensitive), nameExact (exact match — used by migration tooling), and providerTemplateId (resolve a legacy upstream id like SendGrid d-...).

Parameters

Parameter	Type
`params?`	`ListTemplatesParams`

Returns

Promise<PaginatedResponse<TemplateResponse>>

getTemplate()

getTemplate(templateId: string): Promise<TemplateWithVersionResponse>;

Defined in: sdk/src/client.ts:190

Get a template by id, including its current published version.

Parameters

Parameter	Type
`templateId`	`string`

Returns

Promise<TemplateWithVersionResponse>

createTemplate()

createTemplate(params: CreateTemplateParams): Promise<TemplateResponse>;

Defined in: sdk/src/client.ts:198

Create a template. Returns the row immediately — add a version separately via createTemplateVersion().

Parameters

Parameter	Type
`params`	`CreateTemplateParams`

Returns

Promise<TemplateResponse>

updateTemplate()

updateTemplate(templateId: string, params: UpdateTemplateParams): Promise<TemplateResponse>;

Defined in: sdk/src/client.ts:205

Update template metadata (name, description, tags). Does not change the current version.

Parameters

Parameter	Type
`templateId`	`string`
`params`	`UpdateTemplateParams`

Returns

Promise<TemplateResponse>

deleteTemplate()

deleteTemplate(templateId: string): Promise<SuccessResponse>;

Defined in: sdk/src/client.ts:215

Delete a template and all its versions. Irreversible.

Parameters

Parameter	Type
`templateId`	`string`

Returns

Promise<SuccessResponse>

createTemplateVersion()

createTemplateVersion(templateId: string, params: CreateTemplateVersionParams): Promise<TemplateVersionResponse>;

Defined in: sdk/src/client.ts:223

Add a new version to an existing template. Pass MJML or HTML; MJML is rendered server-side. The new version becomes the current version automatically.

Parameters

Parameter	Type
`templateId`	`string`
`params`	`CreateTemplateVersionParams`

Returns

Promise<TemplateVersionResponse>

listTemplateVersions()

listTemplateVersions(templateId: string): Promise<TemplateVersionListResponse>;

Defined in: sdk/src/client.ts:237

List all versions of a template, newest first.

Parameters

Parameter	Type
`templateId`	`string`

Returns

Promise<TemplateVersionListResponse>

getTemplateVersion()

getTemplateVersion(templateId: string, versionId: string): Promise<TemplateVersionResponse>;

Defined in: sdk/src/client.ts:247

Get a specific version of a template by id.

Parameters

Parameter	Type
`templateId`	`string`
`versionId`	`string`

Returns

Promise<TemplateVersionResponse>

previewTemplate()

previewTemplate(templateId: string, params?: PreviewTemplateParams): Promise<PreviewTemplateResponse>;

Defined in: sdk/src/client.ts:261

Render the template with sample variables and return the resolved HTML/text. Useful for editor preview.

Parameters

Parameter	Type
`templateId`	`string`
`params?`	`PreviewTemplateParams`

Returns

Promise<PreviewTemplateResponse>

rollbackTemplate()

rollbackTemplate(templateId: string, versionId: string): Promise<RollbackTemplateResponse>;

Defined in: sdk/src/client.ts:276

Set a previous version as the current version. The old current version is preserved in history.

Parameters

Parameter	Type
`templateId`	`string`
`versionId`	`string`

Returns

Promise<RollbackTemplateResponse>

listProviders()

listProviders(): Promise<ProviderResponse[]>;

Defined in: sdk/src/client.ts:289

List provider accounts connected to your organization (SendGrid, Postmark, Mailgun, SES).

Returns

Promise<ProviderResponse[]>

getProvider()

getProvider(providerId: string): Promise<ProviderResponse>;

Defined in: sdk/src/client.ts:296

Get a single provider account with its credentials masked.

Parameters

Parameter	Type
`providerId`	`string`

Returns

Promise<ProviderResponse>

createProvider()

createProvider(params: CreateProviderParams): Promise<ProviderResponse>;

Defined in: sdk/src/client.ts:305

Connect a new provider. Triggers async webhook registration, template import, and unsubscribe-group sync — failures surface in the response without rolling back the connection.

Parameters

Parameter	Type
`params`	`CreateProviderParams`

Returns

Promise<ProviderResponse>

updateProvider()

updateProvider(providerId: string, params: UpdateProviderParams): Promise<ProviderResponse>;

Defined in: sdk/src/client.ts:313

Update a provider (display name, isActive). Credential rotation requires creating a new provider account.

Parameters

Parameter	Type
`providerId`	`string`
`params`	`UpdateProviderParams`

Returns

Promise<ProviderResponse>

deleteProvider()

deleteProvider(providerId: string): Promise<SuccessResponse>;

Defined in: sdk/src/client.ts:324

Disconnect a provider. Existing sends already routed to it complete; new sends fail unless another provider covers the routing.

Parameters

Parameter	Type
`providerId`	`string`

Returns

Promise<SuccessResponse>

validateProvider()

validateProvider(providerId: string): Promise<ValidateProviderResponse>;

Defined in: sdk/src/client.ts:331

Verify the stored credentials still work by hitting the provider’s validate endpoint.

Parameters

Parameter	Type
`providerId`	`string`

Returns

Promise<ValidateProviderResponse>

listProviderDomains()

listProviderDomains(providerId: string): Promise<ProviderDomainResponse[]>;

Defined in: sdk/src/client.ts:341

List sending domains attached to a provider account.

Parameters

Parameter	Type
`providerId`	`string`

Returns

Promise<ProviderDomainResponse[]>

getMetrics()

getMetrics(params?: MetricsQueryParams): Promise<MetricsResponse>;

Defined in: sdk/src/client.ts:354

Time-series email metrics (sent, delivered, opened, etc.) over a date range, grouped by granularity.

Parameters

Parameter	Type
`params?`	`MetricsQueryParams`

Returns

Promise<MetricsResponse>

getMetricsBreakdown()

getMetricsBreakdown(params?: MetricsBreakdownParams): Promise<MetricsBreakdownResponse>;

Defined in: sdk/src/client.ts:362

Aggregated metrics grouped by a dimension (provider, domain, template, tag).

Parameters

Parameter	Type
`params?`	`MetricsBreakdownParams`

Returns

Promise<MetricsBreakdownResponse>

getMetricsSummary()

getMetricsSummary(params?: MetricsSummaryParams): Promise<MetricsSummaryResponse>;

Defined in: sdk/src/client.ts:371

Single-snapshot totals for the period (no time-series). Faster than getMetrics() for dashboard headlines.

Parameters

Parameter	Type
`params?`	`MetricsSummaryParams`

Returns

Promise<MetricsSummaryResponse>

listMessages()

listMessages(params?: ListMessagesParams): Promise<PaginatedResponse<MessageListItem>>;

Defined in: sdk/src/client.ts:383

List sent messages with rich filtering: status, provider, template, tag, date range, bounceType, and unsubscribe groupId. Each row includes lastEvent (most recent webhook event for the message) without N+1 queries.

Parameters

Parameter	Type
`params?`	`ListMessagesParams`

Returns

Promise<PaginatedResponse<MessageListItem>>

getMessage()

getMessage(messageId: string): Promise<MessageDetailResponse>;

Defined in: sdk/src/client.ts:391

Get a single message with its full event timeline.

Parameters

Parameter	Type
`messageId`	`string`

Returns

Promise<MessageDetailResponse>

listRoutingRules()

listRoutingRules(): Promise<RoutingRuleResponse[]>;

Defined in: sdk/src/client.ts:401

List all routing rules. Rules pick a provider for outbound sends based on domain + tag matching.

Returns

Promise<RoutingRuleResponse[]>

createRoutingRule()

createRoutingRule(params: CreateRoutingRuleParams): Promise<RoutingRuleResponse>;

Defined in: sdk/src/client.ts:409

Create a routing rule. Modes: PRIORITY (try in order), ROUND_ROBIN (alternate), COST_OPTIMIZED, DELIVERY_OPTIMIZED, BALANCED.

Parameters

Parameter	Type
`params`	`CreateRoutingRuleParams`

Returns

Promise<RoutingRuleResponse>

updateRoutingRule()

updateRoutingRule(ruleId: string, params: UpdateRoutingRuleParams): Promise<RoutingRuleResponse>;

Defined in: sdk/src/client.ts:417

Update a routing rule. Mode and weights can change without recreating; provider list cannot reduce to empty.

Parameters

Parameter	Type
`ruleId`	`string`
`params`	`UpdateRoutingRuleParams`

Returns

Promise<RoutingRuleResponse>

deleteRoutingRule()

deleteRoutingRule(ruleId: string): Promise<SuccessResponse>;

Defined in: sdk/src/client.ts:427

Delete a routing rule. Any rule remaining catch-all becomes the new fallback.

Parameters

Parameter	Type
`ruleId`	`string`

Returns

Promise<SuccessResponse>

resolveRouting()

resolveRouting(params: ResolveRoutingParams): Promise<ResolveRoutingResponse>;

Defined in: sdk/src/client.ts:435

Dry-run: which provider would be picked for a given domain + tag set? Returns the chosen provider plus the rule that matched.

Parameters

Parameter	Type
`params`	`ResolveRoutingParams`

Returns

Promise<ResolveRoutingResponse>

listDomains()

listDomains(): Promise<DomainListItem[]>;

Defined in: sdk/src/client.ts:445

List sending domains across all connected providers, with verification status (SPF / DKIM / DMARC).

Returns

Promise<DomainListItem[]>

getDomain()

getDomain(domain: string): Promise<DomainDetailResponse>;

Defined in: sdk/src/client.ts:452

Get a single domain with full DNS-record expected values vs current state.

Parameters

Parameter	Type
`domain`	`string`

Returns

Promise<DomainDetailResponse>

refreshDomain()

refreshDomain(domain: string): Promise<RefreshDomainResponse>;

Defined in: sdk/src/client.ts:459

Re-check SPF/DKIM/DMARC against authoritative DNS now. Use after updating DNS records.

Parameters

Parameter	Type
`domain`	`string`

Returns

Promise<RefreshDomainResponse>

listUnsubscribeGroups()

listUnsubscribeGroups(): Promise<UnsubscribeGroupResponse[]>;

Defined in: sdk/src/client.ts:469

List unsubscribe groups for your organization. Each group can map to multiple provider-side concepts (SendGrid ASM groups, etc.) via listProviderMappings().

Returns

Promise<UnsubscribeGroupResponse[]>

createUnsubscribeGroup()

createUnsubscribeGroup(params: CreateUnsubscribeGroupParams): Promise<UnsubscribeGroupResponse>;

Defined in: sdk/src/client.ts:477

Create an unsubscribe group. tags enables tag-based send-time routing — sends matching the tags use this group’s opt-outs.

Parameters

Parameter	Type
`params`	`CreateUnsubscribeGroupParams`

Returns

Promise<UnsubscribeGroupResponse>

updateUnsubscribeGroup()

updateUnsubscribeGroup(groupId: string, params: UpdateUnsubscribeGroupParams): Promise<UnsubscribeGroupResponse>;

Defined in: sdk/src/client.ts:487

Update group metadata (name, description, isDefault, tags). Provider mappings are managed separately.

Parameters

Parameter	Type
`groupId`	`string`
`params`	`UpdateUnsubscribeGroupParams`

Returns

Promise<UnsubscribeGroupResponse>

deleteUnsubscribeGroup()

deleteUnsubscribeGroup(groupId: string): Promise<SuccessResponse>;

Defined in: sdk/src/client.ts:502

Delete an unsubscribe group. All suppressions scoped to this group are deleted (cascade).

Parameters

Parameter	Type
`groupId`	`string`

Returns

Promise<SuccessResponse>

listProviderMappings()

listProviderMappings(unsubscribeGroupId: string): Promise<ProviderMappingResponse[]>;

Defined in: sdk/src/client.ts:510

List provider-side mappings for an unsubscribe group (which SendGrid ASM groups, Postmark MessageStreams, etc. resolve to this Optail group).

Parameters

Parameter	Type
`unsubscribeGroupId`	`string`

Returns

Promise<ProviderMappingResponse[]>

createProviderMapping()

createProviderMapping(unsubscribeGroupId: string, params: CreateProviderMappingParams): Promise<ProviderMappingResponse>;

Defined in: sdk/src/client.ts:521

Manually attach a provider-side group identifier to an Optail group. Auto-sync handles the common case; this is the manual fallback.

Parameters

Parameter	Type
`unsubscribeGroupId`	`string`
`params`	`CreateProviderMappingParams`

Returns

Promise<ProviderMappingResponse>

deleteProviderMapping()

deleteProviderMapping(unsubscribeGroupId: string, mappingId: string): Promise<SuccessResponse>;

Defined in: sdk/src/client.ts:536

Remove a provider mapping. The Optail group itself stays — only the provider linkage is severed.

Parameters

Parameter	Type
`unsubscribeGroupId`	`string`
`mappingId`	`string`

Returns

Promise<SuccessResponse>

syncProviderUnsubscribeGroups()

syncProviderUnsubscribeGroups(providerAccountId: string): Promise<SyncProviderUnsubscribeGroupsResponse>;

Defined in: sdk/src/client.ts:550

Re-sync provider-side unsubscribe groups on demand. Idempotent — upserts existing mappings, creates new ones. Use after adding ASM groups in SendGrid, etc.

Parameters

Parameter	Type
`providerAccountId`	`string`

Returns

Promise<SyncProviderUnsubscribeGroupsResponse>

importProviderTemplates()

importProviderTemplates(providerAccountId: string): Promise<ImportProviderTemplatesResponse>;

Defined in: sdk/src/client.ts:563

Pull all templates from a provider account and upsert into Optail. Idempotent. Used to backfill providers connected before template import existed.

Parameters

Parameter	Type
`providerAccountId`	`string`

Returns

Promise<ImportProviderTemplatesResponse>

listSuppressions()

listSuppressions(params?: ListSuppressionsParams): Promise<PaginatedResponse<SuppressionResponse>>;

Defined in: sdk/src/client.ts:577

List suppression rows (bounced, unsubscribed, complained recipients). Filter by source.

Parameters

Parameter	Type
`params?`	`ListSuppressionsParams`

Returns

Promise<PaginatedResponse<SuppressionResponse>>

createSuppression()

createSuppression(params: CreateSuppressionParams): Promise<SuppressionResponse>;

Defined in: sdk/src/client.ts:590

Manually suppress a recipient. Source defaults to MANUAL; pass IMPORT for bulk lists.

Parameters

Parameter	Type
`params`	`CreateSuppressionParams`

Returns

Promise<SuppressionResponse>

deleteSuppression()

deleteSuppression(suppressionId: string): Promise<SuccessResponse>;

Defined in: sdk/src/client.ts:597

Remove a suppression. Use carefully — restores deliverability to that recipient.

Parameters

Parameter	Type
`suppressionId`	`string`

Returns

Promise<SuccessResponse>

importSuppressions()

importSuppressions(params: ImportSuppressionsParams): Promise<ImportSuppressionsResponse>;

Defined in: sdk/src/client.ts:605

Bulk-import suppressions from a list of emails. Idempotent — duplicates are skipped, returns counts.

Parameters

Parameter	Type
`params`	`ImportSuppressionsParams`

Returns

Promise<ImportSuppressionsResponse>

checkSuppression()

checkSuppression(email: string): Promise<SuppressionCheckResponse>;

Defined in: sdk/src/client.ts:612

Check whether an email is suppressed. Returns the matching suppression rows and groups.

Parameters

Parameter	Type
`email`	`string`

Returns

Promise<SuppressionCheckResponse>

listWebhookEndpoints()

listWebhookEndpoints(): Promise<WebhookEndpointResponse[]>;

Defined in: sdk/src/client.ts:624

List configured webhook destinations where Optail forwards email events.

Returns

Promise<WebhookEndpointResponse[]>

createWebhookEndpoint()

createWebhookEndpoint(params: CreateWebhookEndpointParams): Promise<WebhookEndpointCreateResponse>;

Defined in: sdk/src/client.ts:632

Create a webhook endpoint. Optail signs every delivery with HMAC — verify on receipt using verifyWebhookSignature.

Parameters

Parameter	Type
`params`	`CreateWebhookEndpointParams`

Returns

Promise<WebhookEndpointCreateResponse>

updateWebhookEndpoint()

updateWebhookEndpoint(endpointId: string, params: UpdateWebhookEndpointParams): Promise<WebhookEndpointResponse>;

Defined in: sdk/src/client.ts:642

Update a webhook endpoint (URL, event filter, isActive). Secret cannot be rotated without recreating the endpoint.

Parameters

Parameter	Type
`endpointId`	`string`
`params`	`UpdateWebhookEndpointParams`

Returns

Promise<WebhookEndpointResponse>

deleteWebhookEndpoint()

deleteWebhookEndpoint(endpointId: string): Promise<SuccessResponse>;

Defined in: sdk/src/client.ts:656

Delete a webhook endpoint. In-flight deliveries already enqueued may still fire.

Parameters

Parameter	Type
`endpointId`	`string`

Returns

Promise<SuccessResponse>

testWebhookEndpoint()

testWebhookEndpoint(endpointId: string): Promise<WebhookTestResponse>;

Defined in: sdk/src/client.ts:664

Send a synthetic test event to the endpoint to verify your receiver works. Logs the delivery in the dashboard.

Parameters

Parameter	Type
`endpointId`	`string`

Returns

Promise<WebhookTestResponse>

getOrganization()

getOrganization(): Promise<OrganizationResponse>;

Defined in: sdk/src/client.ts:676

Get the current organization (name, plan, slug, Stripe customer id).

Returns

Promise<OrganizationResponse>

updateOrganization()

updateOrganization(params: UpdateOrganizationParams): Promise<OrganizationResponse>;

Defined in: sdk/src/client.ts:683

Update organization metadata (name, slug).

Parameters

Parameter	Type
`params`	`UpdateOrganizationParams`

Returns

Promise<OrganizationResponse>

listOrganizationMembers()

listOrganizationMembers(): Promise<OrganizationMemberResponse[]>;

Defined in: sdk/src/client.ts:690

List members of the current organization with their roles.

Returns

Promise<OrganizationMemberResponse[]>

getUsage()

getUsage(): Promise<UsageResponse>;

Defined in: sdk/src/client.ts:697

Current month usage against your plan limits.

Returns

Promise<UsageResponse>

listApiKeys()

listApiKeys(): Promise<ApiKeyResponse[]>;

Defined in: sdk/src/client.ts:707

List API keys with their permissions and last-used timestamps. Key material itself is never returned after creation.

Returns

Promise<ApiKeyResponse[]>

createApiKey()

createApiKey(params: CreateApiKeyParams): Promise<ApiKeyCreateResponse>;

Defined in: sdk/src/client.ts:715

Mint a new API key. The full key is returned ONCE — store it immediately; subsequent reads only return the prefix.

Parameters

Parameter	Type
`params`	`CreateApiKeyParams`

Returns

Promise<ApiKeyCreateResponse>

revokeApiKey()

revokeApiKey(apiKeyId: string): Promise<ApiKeyRevokeResponse>;

Defined in: sdk/src/client.ts:723

Revoke an API key. Subsequent requests using it return 401. Revocation is immediate and irreversible.

Parameters

Parameter	Type
`apiKeyId`	`string`

Returns

Promise<ApiKeyRevokeResponse>

getStatus()

getStatus(): Promise<StatusResponse>;

Defined in: sdk/src/client.ts:736

Public service status (no auth required). Returns overall health, per-service status, and active incidents.

Returns

Promise<StatusResponse>

getStatusHistory()

getStatusHistory(): Promise<StatusIncident[]>;

Defined in: sdk/src/client.ts:743

Historical incidents on the public status page.

Returns

Promise<StatusIncident[]>

listPlans()

listPlans(): Promise<PlanDefinition[]>;

Defined in: sdk/src/client.ts:752

List available subscription plans.

Returns

Promise<PlanDefinition[]>

createCheckout()

createCheckout(params: CheckoutParams): Promise<CheckoutResponse>;

Defined in: sdk/src/client.ts:760

Create a Stripe Checkout Session for upgrading the plan. Returns the hosted Checkout URL.

Parameters

Parameter	Type
`params`	`CheckoutParams`

Returns

Promise<CheckoutResponse>

createBillingPortal()

createBillingPortal(): Promise<PortalResponse>;

Defined in: sdk/src/client.ts:767

Create a Stripe Billing Portal session for managing payment methods / canceling.

Returns

Promise<PortalResponse>

getSubscription()

getSubscription(): Promise<SubscriptionResponse>;

Defined in: sdk/src/client.ts:774

Active subscription with billing cycle dates.

Returns

Promise<SubscriptionResponse>

listContacts()

listContacts(params?: ListContactsParams): Promise<PaginatedResponse<ContactResponse>>;

Defined in: sdk/src/client.ts:784

List contacts with pagination. Filter by status (active / unsubscribed / bounced / complained) or free-text search.

Parameters

Parameter	Type
`params?`	`ListContactsParams`

Returns

Promise<PaginatedResponse<ContactResponse>>

getContact()

getContact(contactId: string): Promise<ContactDetailResponse>;

Defined in: sdk/src/client.ts:792

Get a contact with their list memberships.

Parameters

Parameter	Type
`contactId`	`string`

Returns

Promise<ContactDetailResponse>

createContact()

createContact(params: CreateContactParams): Promise<ContactResponse>;

Defined in: sdk/src/client.ts:800

Create a contact. Race-safe: returns the existing row if email already exists (no error).

Parameters

Parameter	Type
`params`	`CreateContactParams`

Returns

Promise<ContactResponse>

updateContact()

updateContact(contactId: string, params: UpdateContactParams): Promise<ContactResponse>;

Defined in: sdk/src/client.ts:808

Update contact attributes. Cannot change email — create a new contact + delete the old one.

Parameters

Parameter	Type
`contactId`	`string`
`params`	`UpdateContactParams`

Returns

Promise<ContactResponse>

deleteContact()

deleteContact(contactId: string): Promise<SuccessResponse>;

Defined in: sdk/src/client.ts:816

Hard-delete a contact. Suppression history is preserved (suppressions live independently).

Parameters

Parameter	Type
`contactId`	`string`

Returns

Promise<SuccessResponse>

unsubscribeContact()

unsubscribeContact(contactId: string): Promise<ContactResponse>;

Defined in: sdk/src/client.ts:824

Globally unsubscribe a contact (across all lists and groups). Sets the unsubscribedAt flag.

Parameters

Parameter	Type
`contactId`	`string`

Returns

Promise<ContactResponse>

importContacts()

importContacts(params: ImportContactsParams): Promise<ContactImportJobResponse>;

Defined in: sdk/src/client.ts:832

Bulk-import contacts via an async job. Enqueues the work and returns immediately; poll status with getContactImportJob().

Parameters

Parameter	Type
`params`	`ImportContactsParams`

Returns

Promise<ContactImportJobResponse>

getContactImportJob()

getContactImportJob(jobId: string): Promise<ContactImportJobResponse>;

Defined in: sdk/src/client.ts:839

Poll the status of an import job. Returns counts and per-row errors when complete.

Parameters

Parameter	Type
`jobId`	`string`

Returns

Promise<ContactImportJobResponse>

listContactLists()

listContactLists(params?: ListContactListsParams): Promise<PaginatedResponse<ContactListResponse>>;

Defined in: sdk/src/client.ts:848

List contact lists with member counts.

Parameters

Parameter	Type
`params?`	`ListContactListsParams`

Returns

Promise<PaginatedResponse<ContactListResponse>>

getContactList()

getContactList(listId: string): Promise<ContactListResponse>;

Defined in: sdk/src/client.ts:858

Get a single list.

Parameters

Parameter	Type
`listId`	`string`

Returns

Promise<ContactListResponse>

createContactList()

createContactList(params: CreateListParams): Promise<ContactListResponse>;

Defined in: sdk/src/client.ts:865

Create a static contact list. Race-safe: returns existing row if name already exists.

Parameters

Parameter	Type
`params`	`CreateListParams`

Returns

Promise<ContactListResponse>

updateContactList()

updateContactList(listId: string, params: UpdateListParams): Promise<ContactListResponse>;

Defined in: sdk/src/client.ts:872

Update list metadata (name, description).

Parameters

Parameter	Type
`listId`	`string`
`params`	`UpdateListParams`

Returns

Promise<ContactListResponse>

deleteContactList()

deleteContactList(listId: string): Promise<SuccessResponse>;

Defined in: sdk/src/client.ts:879

Delete a list. Member memberships are deleted; the contacts themselves are not.

Parameters

Parameter	Type
`listId`	`string`

Returns

Promise<SuccessResponse>

listContactListMembers()

listContactListMembers(listId: string, params?: ListMembersParams): Promise<PaginatedResponse<ListMemberResponse>>;

Defined in: sdk/src/client.ts:887

List members of a list. Paginated; pass subscribed: false to include unsubscribed members.

Parameters

Parameter	Type
`listId`	`string`
`params?`	`ListMembersParams`

Returns

Promise<PaginatedResponse<ListMemberResponse>>

addContactListMembers()

addContactListMembers(listId: string, params: AddListMembersParams): Promise<AddListMembersResponse>;

Defined in: sdk/src/client.ts:902

Add members by contact id or email. Emails that don’t map to existing contacts auto-create them.

Parameters

Parameter	Type
`listId`	`string`
`params`	`AddListMembersParams`

Returns

Promise<AddListMembersResponse>

removeContactListMember()

removeContactListMember(listId: string, contactId: string): Promise<ListMembershipResponse>;

Defined in: sdk/src/client.ts:913

Remove a contact from a list (soft unsubscribe — keeps the membership row with unsubscribedAt set).

Parameters

Parameter	Type
`listId`	`string`
`contactId`	`string`

Returns

Promise<ListMembershipResponse>

listNotificationChannels()

listNotificationChannels(): Promise<NotificationChannelResponse[]>;

Defined in: sdk/src/client.ts:929

List notification channels (Slack, webhook, email destinations for Optail internal alerts).

Returns

Promise<NotificationChannelResponse[]>

createNotificationChannel()

createNotificationChannel(params: CreateNotificationChannelParams): Promise<NotificationChannelResponse>;

Defined in: sdk/src/client.ts:937

Create a notification channel. The events array selects which Optail events route to this channel.

Parameters

Parameter	Type
`params`	`CreateNotificationChannelParams`

Returns

Promise<NotificationChannelResponse>

updateNotificationChannel()

updateNotificationChannel(channelId: string, params: UpdateNotificationChannelParams): Promise<NotificationChannelResponse>;

Defined in: sdk/src/client.ts:946

Update a notification channel.

Parameters

Parameter	Type
`channelId`	`string`
`params`	`UpdateNotificationChannelParams`

Returns

Promise<NotificationChannelResponse>

deleteNotificationChannel()

deleteNotificationChannel(channelId: string): Promise<SuccessResponse>;

Defined in: sdk/src/client.ts:960

Delete a notification channel.

Parameters

Parameter	Type
`channelId`	`string`

Returns

Promise<SuccessResponse>

testNotificationChannel()

testNotificationChannel(channelId: string): Promise<NotificationChannelTestResponse>;

Defined in: sdk/src/client.ts:970

Send a synthetic alert to verify the channel works.

Parameters

Parameter	Type
`channelId`	`string`

Returns

Promise<NotificationChannelTestResponse>

createExport()

createExport(params: CreateExportParams): Promise<ExportResponse>;

Defined in: sdk/src/client.ts:983

Create an async export job for email events. Date range capped at 90 days. Formats: csv, jsonl, parquet.

Parameters

Parameter	Type
`params`	`CreateExportParams`

Returns

Promise<ExportResponse>

getExport()

getExport(exportId: string): Promise<ExportResponse>;

Defined in: sdk/src/client.ts:990

Poll the status of an export. Returns progress + download URL when complete.

Parameters

Parameter	Type
`exportId`	`string`

Returns

Promise<ExportResponse>

listExports()

listExports(params?: PaginationParams): Promise<PaginatedResponse<ExportResponse>>;

Defined in: sdk/src/client.ts:997

List recent export jobs.

Parameters

Parameter	Type
`params?`	`PaginationParams`

Returns

Promise<PaginatedResponse<ExportResponse>>

cancelExport()

cancelExport(exportId: string): Promise<SuccessResponse>;

Defined in: sdk/src/client.ts:1005

Cancel a pending export. In-progress exports complete normally.

Parameters

Parameter	Type
`exportId`	`string`

Returns

Promise<SuccessResponse>

getFailoverStatus()

getFailoverStatus(): Promise<FailoverStatusResponse[]>;

Defined in: sdk/src/client.ts:1015

Circuit breaker state for each provider account: closed (healthy), open (failing), half_open (recovering).

Returns

Promise<FailoverStatusResponse[]>

listFailoverEvents()

listFailoverEvents(hours?: number): Promise<FailoverEventResponse[]>;

Defined in: sdk/src/client.ts:1022

Recent failover state transitions. Default window: last 24 hours.

Parameters

Parameter	Type
`hours?`	`number`

Returns

Promise<FailoverEventResponse[]>

resetFailover()

resetFailover(providerAccountId: string): Promise<ResetFailoverResponse>;

Defined in: sdk/src/client.ts:1030

Manually close an open circuit breaker. Use after fixing a known provider issue.

Parameters

Parameter	Type
`providerAccountId`	`string`

Returns

Promise<ResetFailoverResponse>

interpretBounce()

interpretBounce(params: InterpretBounceParams): Promise<InterpretBounceResponse>;

Defined in: sdk/src/client.ts:1043

Classify a raw SMTP bounce code / message / enhanced status into Optail’s normalized taxonomy (hard, soft, block, invalid, mailbox_full, policy, reputation).

Parameters

Parameter	Type
`params`	`InterpretBounceParams`

Returns

Promise<InterpretBounceResponse>

getBounceAnalysis()

getBounceAnalysis(messageId: string): Promise<BounceAnalysisResponse>;

Defined in: sdk/src/client.ts:1050

Get bounce-interpretation results for every bounce event on a specific message.

Parameters

Parameter	Type
`messageId`	`string`

Returns

Promise<BounceAnalysisResponse>

createWarmupPlan()

createWarmupPlan(params: CreateWarmupPlanParams): Promise<WarmupPlanResponse>;

Defined in: sdk/src/client.ts:1062

Create an IP / domain warmup plan with ramped daily volumes.

Parameters

Parameter	Type
`params`	`CreateWarmupPlanParams`

Returns

Promise<WarmupPlanResponse>

listWarmupPlans()

listWarmupPlans(params?: ListWarmupPlansParams): Promise<WarmupPlanResponse[]>;

Defined in: sdk/src/client.ts:1069

List warmup plans. Filter by status (active / paused / completed / cancelled).

Parameters

Parameter	Type
`params?`	`ListWarmupPlansParams`

Returns

Promise<WarmupPlanResponse[]>

getWarmupOrchestration()

getWarmupOrchestration(): Promise<WarmupOrchestrationResponse>;

Defined in: sdk/src/client.ts:1078

Get the orchestration overview: how traffic should split across providers/domains for plans currently active.

Returns

Promise<WarmupOrchestrationResponse>

recalculateWarmupOrchestration()

recalculateWarmupOrchestration(currentVolume?: number): Promise<WarmupOrchestrationResponse>;

Defined in: sdk/src/client.ts:1086

Recalculate traffic distribution. Use after creating/cancelling plans or when current volume changes meaningfully.

Parameters

Parameter	Type
`currentVolume?`	`number`

Returns

Promise<WarmupOrchestrationResponse>

getWarmupPlan()

getWarmupPlan(planId: string): Promise<WarmupPlanDetailResponse>;

Defined in: sdk/src/client.ts:1099

Get a warmup plan with day-by-day progress.

Parameters

Parameter	Type
`planId`	`string`

Returns

Promise<WarmupPlanDetailResponse>

recordWarmupMetrics()

recordWarmupMetrics(planId: string, params: RecordWarmupParams): Promise<WarmupPlanResponse>;

Defined in: sdk/src/client.ts:1107

Record actual sent volume + deferrals + bounces for today. Auto-advances the plan to the next day on success.

Parameters

Parameter	Type
`planId`	`string`
`params`	`RecordWarmupParams`

Returns

Promise<WarmupPlanResponse>

pauseWarmupPlan()

pauseWarmupPlan(planId: string): Promise<WarmupPlanResponse>;

Defined in: sdk/src/client.ts:1117

Pause a warmup plan. The plan’s current day is preserved; resume picks up from there.

Parameters

Parameter	Type
`planId`	`string`

Returns

Promise<WarmupPlanResponse>

resumeWarmupPlan()

resumeWarmupPlan(planId: string): Promise<WarmupPlanResponse>;

Defined in: sdk/src/client.ts:1124

Resume a paused warmup plan.

Parameters

Parameter	Type
`planId`	`string`

Returns

Promise<WarmupPlanResponse>

cancelWarmupPlan()

cancelWarmupPlan(planId: string): Promise<WarmupPlanResponse>;

Defined in: sdk/src/client.ts:1131

Cancel a warmup plan permanently.

Parameters

Parameter	Type
`planId`	`string`

Returns

Promise<WarmupPlanResponse>

createAbTest()

createAbTest(params: CreateAbTestParams): Promise<AbTestResponse>;

Defined in: sdk/src/client.ts:1141

Create an A/B test with weighted template-version variants. Metric: open_rate, click_rate, or conversion_rate.

Parameters

Parameter	Type
`params`	`CreateAbTestParams`

Returns

Promise<AbTestResponse>

listAbTests()

listAbTests(params?: ListAbTestsParams): Promise<AbTestResponse[]>;

Defined in: sdk/src/client.ts:1148

List A/B tests filtered by status (draft / running / completed / cancelled).

Parameters

Parameter	Type
`params?`	`ListAbTestsParams`

Returns

Promise<AbTestResponse[]>

getAbTest()

getAbTest(testId: string): Promise<AbTestResponse>;

Defined in: sdk/src/client.ts:1156

Get an A/B test with variant performance.

Parameters

Parameter	Type
`testId`	`string`

Returns

Promise<AbTestResponse>

startAbTest()

startAbTest(testId: string): Promise<AbTestResponse>;

Defined in: sdk/src/client.ts:1163

Start an A/B test. Variants begin receiving traffic according to their weights.

Parameters

Parameter	Type
`testId`	`string`

Returns

Promise<AbTestResponse>

stopAbTest()

stopAbTest(testId: string, params?: StopAbTestParams): Promise<AbTestResponse>;

Defined in: sdk/src/client.ts:1170

Stop the test and declare a winner. Optionally pass final variant results to record.

Parameters

Parameter	Type
`testId`	`string`
`params?`	`StopAbTestParams`

Returns

Promise<AbTestResponse>

deleteAbTest()

deleteAbTest(testId: string): Promise<{
  deleted: true;
}>;

Defined in: sdk/src/client.ts:1177

Delete an A/B test. Only allowed for tests in draft or cancelled state.

Parameters

Parameter	Type
`testId`	`string`

Returns

Promise<{ deleted: true; }>

recommendSendTime()

recommendSendTime(params: SendTimeRecommendationParams): Promise<SendTimeRecommendationResponse>;

Defined in: sdk/src/client.ts:1187

Recommend the optimal time to send to a recipient domain based on historical engagement, optionally constrained by template and tags.

Parameters

Parameter	Type
`params`	`SendTimeRecommendationParams`

Returns

Promise<SendTimeRecommendationResponse>

scoreSpam()

scoreSpam(params: SpamScoreParams): Promise<SpamScoreResponse>;

Defined in: sdk/src/client.ts:1199

Score an email against the 100-point rubric (subject, content, headers, ISP signals, audience fit). Returns grade + findings + category breakdown.

Parameters

Parameter	Type
`params`	`SpamScoreParams`

Returns

Promise<SpamScoreResponse>

rewriteForSpam()

rewriteForSpam(params: SpamRewriteParams): Promise<SpamRewriteResponse>;

Defined in: sdk/src/client.ts:1207

AI-rewrite the subject + HTML to address spam-score findings. Uses Claude. Preserves intent + tone.

Parameters

Parameter	Type
`params`	`SpamRewriteParams`

Returns

Promise<SpamRewriteResponse>

getMessageSpamScore()

getMessageSpamScore(messageId: string): Promise<SpamScoreResponse>;

Defined in: sdk/src/client.ts:1215

Get the persisted spam score for a sent message (cached from when it was scored). 404 if not yet scored.

Parameters

Parameter	Type
`messageId`	`string`

Returns

Promise<SpamScoreResponse>

getTemplateSpamScore()

getTemplateSpamScore(templateId: string, versionId?: string): Promise<SpamScoreResponse>;

Defined in: sdk/src/client.ts:1222

Get the persisted spam score for a template version. 404 if not yet scored.

Parameters

Parameter	Type
`templateId`	`string`
`versionId?`	`string`

Returns

Promise<SpamScoreResponse>

getDeliverabilityStatus()

getDeliverabilityStatus(): Promise<DeliverabilityStatusResponse>;

Defined in: sdk/src/client.ts:1236

Snapshot of which deliverability signal sources are wired up (PMT, SNDS, sender IPs, inbound DMARC).

Returns

Promise<DeliverabilityStatusResponse>

connectPmt()

connectPmt(params?: PmtConnectParams): Promise<PmtConnectResponse>;

Defined in: sdk/src/client.ts:1244

Start the Gmail Postmaster Tools OAuth flow. Returns an authorizationUrl for the user to visit.

Parameters

Parameter	Type
`params?`	`PmtConnectParams`

Returns

Promise<PmtConnectResponse>

getPmtConnection()

getPmtConnection(): Promise<PmtCredentialsResponse>;

Defined in: sdk/src/client.ts:1255

Get the current Gmail PMT connection status (connected email, scopes, expiry).

Returns

Promise<PmtCredentialsResponse>

disconnectPmt()

disconnectPmt(): Promise<{
  disconnected: true;
}>;

Defined in: sdk/src/client.ts:1262

Revoke the PMT OAuth grant.

Returns

Promise<{ disconnected: true; }>

listSndsKeys()

listSndsKeys(): Promise<SndsKeyResponse[]>;

Defined in: sdk/src/client.ts:1269

List Outlook SNDS access keys configured for inbound reputation signals.

Returns

Promise<SndsKeyResponse[]>

addSndsKey()

addSndsKey(params: AddSndsKeyParams): Promise<SndsKeyResponse>;

Defined in: sdk/src/client.ts:1281

Add an Outlook SNDS access key. Optail polls SNDS daily and surfaces complaint-rate signals.

Parameters

Parameter	Type
`params`	`AddSndsKeyParams`

Returns

Promise<SndsKeyResponse>

deleteSndsKey()

deleteSndsKey(keyId: string): Promise<{
  deleted: true;
}>;

Defined in: sdk/src/client.ts:1288

Delete an SNDS key.

Parameters

Parameter	Type
`keyId`	`string`

Returns

Promise<{ deleted: true; }>

listSenderIps()

listSenderIps(): Promise<SenderIpResponse[]>;

Defined in: sdk/src/client.ts:1295

List sending IP addresses registered for SNDS lookups.

Returns

Promise<SenderIpResponse[]>

addSenderIp()

addSenderIp(params: AddSenderIpParams): Promise<SenderIpResponse>;

Defined in: sdk/src/client.ts:1306

Parameters

Parameter	Type
`params`	`AddSenderIpParams`

Returns

Promise<SenderIpResponse>

deleteSenderIp()

deleteSenderIp(senderIpId: string): Promise<{
  deleted: true;
}>;

Defined in: sdk/src/client.ts:1313

Stop monitoring a sender IP.

Parameters

Parameter	Type
`senderIpId`	`string`

Returns

Promise<{ deleted: true; }>

getDmarcRuaUrl()

getDmarcRuaUrl(): Promise<DmarcRuaResponse>;

Defined in: sdk/src/client.ts:1324

Get the inbound DMARC RUA endpoint URL for your organization. Configure in your DMARC DNS record (rua=mailto:...).

Returns

Promise<DmarcRuaResponse>

listTestInboxes()

listTestInboxes(): Promise<{
  inboxDomain: string;
  tokens: TestInboxTokenResponse[];
}>;

Defined in: sdk/src/client.ts:1331

List authenticated test-inbox tokens — durable addresses for end-to-end inbox tests.

Returns

Promise<{ inboxDomain: string; tokens: TestInboxTokenResponse[]; }>

createTestInbox()

createTestInbox(params: CreateTestInboxParams): Promise<TestInboxTokenResponse>;

Defined in: sdk/src/client.ts:1342

Create a durable test inbox. Returns an address you can send to + a token to poll for received messages.

Parameters

Parameter	Type
`params`	`CreateTestInboxParams`

Returns

Promise<TestInboxTokenResponse>

deleteTestInbox()

deleteTestInbox(tokenId: string): Promise<{
  deleted: true;
}>;

Defined in: sdk/src/client.ts:1353

Delete a test inbox token.

Parameters

Parameter	Type
`tokenId`	`string`

Returns

Promise<{ deleted: true; }>

listInboxRuns()

listInboxRuns(params?: {
  token?: string;
  limit?: number;
}): Promise<{
  runs: InboxRunSummary[];
}>;

Defined in: sdk/src/client.ts:1363

List recently received messages on test inboxes. Filter by token.

Parameters

Parameter	Type
`params?`	{ `token?`: `string`; `limit?`: `number`; }
`params.token?`	`string`
`params.limit?`	`number`

Returns

Promise<{ runs: InboxRunSummary[]; }>

getInboxRun()

getInboxRun(runId: string): Promise<InboxRunDetail>;

Defined in: sdk/src/client.ts:1378

Get full details of a received message: headers, body, TLS, spam score, layer-1 / layer-2 analysis.

Parameters

Parameter	Type
`runId`	`string`

Returns

Promise<InboxRunDetail>

shareInboxRun()

shareInboxRun(runId: string, visible: boolean): Promise<ShareInboxRunResponse>;

Defined in: sdk/src/client.ts:1386

Toggle public-share visibility for an inbox run. Public URL allows sharing the score without auth.

Parameters

Parameter	Type
`runId`	`string`
`visible`	`boolean`

Returns

Promise<ShareInboxRunResponse>

listBrandDomains()

listBrandDomains(): Promise<BrandDomainResponse[]>;

Defined in: sdk/src/client.ts:1397

List brand domains used by the inbox visual-similarity engine.

Returns

Promise<BrandDomainResponse[]>

addBrandDomain()

addBrandDomain(params: AddBrandDomainParams): Promise<BrandDomainResponse>;

Defined in: sdk/src/client.ts:1408

Parameters

Parameter	Type
`params`	`AddBrandDomainParams`

Returns

Promise<BrandDomainResponse>

deleteBrandDomain()

deleteBrandDomain(brandDomainId: string): Promise<{
  deleted: true;
}>;

Defined in: sdk/src/client.ts:1415

Delete a brand domain.

Parameters

Parameter	Type
`brandDomainId`	`string`

Returns

Promise<{ deleted: true; }>

listBrandTemplates()

listBrandTemplates(): Promise<BrandTemplateResponse[]>;

Defined in: sdk/src/client.ts:1425

List brand template fingerprints (visual hashes of your trusted templates).

Returns

Promise<BrandTemplateResponse[]>

addBrandTemplate()

addBrandTemplate(params: AddBrandTemplateParams): Promise<BrandTemplateResponse>;

Defined in: sdk/src/client.ts:1437

Parameters

Parameter	Type
`params`	`AddBrandTemplateParams`

Returns

Promise<BrandTemplateResponse>

deleteBrandTemplate()

deleteBrandTemplate(brandTemplateId: string): Promise<{
  deleted: true;
}>;

Defined in: sdk/src/client.ts:1448

Delete a brand template fingerprint.

Parameters

Parameter	Type
`brandTemplateId`	`string`

Returns

Promise<{ deleted: true; }>