tuski.ai

Tuski validates email lists by sending real probe messages and detecting bounces, and finds companies matching a profile via AI web search. Authenticate with OAuth Connect, or `Authorization: Bearer tsk_live_...`. Scopes/permissions: `validate` (validate_emails, pause_job, resume_job, cancel_job), `export` (get_results, get_results_csv), `discovery` (all company-search tools). get_credits, list_jobs, get_job_status and wait_for_job need no permission. Email flow: get_credits -> validate_emails -> wait_for_job (respect its poll_after_seconds) -> get_results or get_results_csv. Charging: validate_emails deducts 1 credit per address accepted for testing (passes syntax/domain checks) at intake, from the organization wallet that also pays for phone, discovery and contacts. No-MX addresses and our own send failures are refunded when the job closes; a real bounce is a paid result. Timing: a job closes after its 15-minute bounce window and a bounce check of each mailbox that sent it: a little over send time plus 15 minutes for a short list, hours for thousands of addresses. A late check holds it at most 6 hours more (reason `valid (bounce check delayed)`). After `done` a verdict changes only on a rare late bounce or a dashboard recheck. Result row statuses: `valid`: deliverable mailbox; `invalid`: permanent address failure; `unknown`: send attempted, outcome unclear; `unreachable`: domain has no mail server, refunded; `mailbox_full`: recipient inbox is full; `blocked`: rejected by recipient's policy; `soft_temp`: temporary bounce, may resolve later; `routing_error`: mail could not be routed; `other_bounce`: other permanent bounce; `pending`: not sent (in a finished job: rejected at upload, not charged); `queued`: charged, waiting to send; `sending`: in flight now; `sent`: delivered, awaiting the bounce check; `cancelled`: job or lead was cancelled. Results: get_results pages 100 rows by default (1000 at most); has_more (and next_offset for company search) says if another page exists. get_results_csv and export_companies embed up to 500 CSV rows; a larger export returns a download_url valid for 10 minutes, no API key needed. Idempotency: the same idempotency_key returns the same job and never charges twice; without one, a key is derived from your account, organization and request, so an identical call within 10 minutes is recognized too. After a timeout or transport error, repeat the identical call; changed input starts a new job and a new charge. Large lists: upload a file via REST POST /api/v1/email-validation/jobs instead of one huge validate_emails call. Company search: estimate_company_search (free quote) -> start_company_search (reserves credits) -> wait_for_company_search -> get_companies or export_companies; get_company_search reads its status and cancel_company_search stops it early. A search lists and charges only companies it verified on the web (an older search with `verified_results` false lists every candidate) and refunds the rest of its reservation. Result rows may carry an email you can pass to validate_emails. Contacts: find_contacts -> get_contacts -> estimate_contact_unlock -> unlock_contacts -> wait_for_contacts -> get_contacts. Needs the `contacts` permission, separate from `discovery`. unlock_contacts charges per requested field up front and refunds any field the provider could not deliver. Errors: every failure reads `code: message (next: what to do next)`. Read next to choose your next call.