canonical: https://jentic.com/apis/kawaa.com/kawaa

# Kawaa API

The Kawaa API verifies email addresses one at a time or in lists, finds a person's work address from their name and company domain, and checks how a domain is set up to send mail. A single verification returns a verdict such as valid, risky, catch_all, or unknown, while batch and file jobs (CSV, TSV, or TXT up to 50 MB) run asynchronously with progress, paged results, CSV or JSON downloads, and cancellation with a credit refund. It also returns engagement history recorded by your own Kawaa tracking, runs domain email authentication checks, and exposes credits, usage, API keys, plans, signed webhooks with delivery logs and retries, and export schedules. Every paid call is metered in credits, from 0.25 per address for batch activity lookups to 10 for a fresh domain check.

## For AI agents

Verify one email address or a whole list, find a person's work address from name and domain, check a domain's mail authentication, and track jobs, credits, and webhooks on a Kawaa account.

## Scope

Does not send email campaigns, host mailboxes, or manage CRM contacts. Use for verifying and finding email addresses and checking domain mail authentication only.

## Capabilities

- Verify a single email address and get a verdict such as valid, risky, catch_all, or unknown, with a job_id to poll if it runs past the request window
- Submit a batch of addresses up to the plan's batch size, follow it with GET `/v1/jobs/{id}`, and cancel a running batch for a refund of unprocessed credits
- Verify a CSV, TSV, or TXT file through a presigned upload URL and a process step
- Find a person's work address from first_name, last_name, and domain, trusting only results marked verified true
- Check a domain's email authentication with an optional sending_ip, and read past checks for free
- Look up opens and clicks your own Kawaa tracking recorded for an address or a list of addresses
- Register signed webhooks for job and verification events, read delivery logs, retry a delivery, and rotate the signing secret

## Use cases

### List Hygiene Through Jentic

An AI agent cleaning a signup list submits the addresses as one Kawaa batch, polls the job with include_results set to false until it completes, then downloads only the invalid rows to remove them. Through Jentic the agent finds these operations by intent and calls them with your key, and you choose whether it may also start paid lookups like the email finder.

Example prompt: Submit POST `/v1/verify/batch` with the list of emails, poll GET `/v1/jobs/{id}` with include_results false until the job is completed, then call the download endpoint with format 'csv' and a filter for invalid results

### Point-of-Entry Address Checks

A signup form or CRM import checks each address as it arrives. POST `/v1/verify` returns the verdict inline for 1 credit, or 0.5 when served from cache, and returns status pending with a job_id when verification needs longer, so the caller polls rather than treating the address as bad.

Example prompt: Verify the address 'user@example.com' with POST `/v1/verify` and, if status is 'pending', poll the returned job_id until a verdict arrives

### Finding a Contact's Work Address

A sales researcher knows a prospect's name and company domain but not their email. The email finder works out candidate addresses and checks them with the domain's mail server for 5 credits, and only a result with verified true is a confirmed address. The bulk form handles several people at one domain and needs the Starter plan or higher.

Example prompt: Call POST `/v1/find` with first_name 'Jane', last_name 'Doe', and domain 'acme.com', and report the email only if verified is true

### Sending Domain Health Check

Before a campaign, a marketer wants to know whether their domain's email authentication is in order. The agent runs a deliverability check for the domain, sending an Idempotency-Key so a timed-out retry does not pay twice, and a repeat check within 24 hours is served from cache for free.

Example prompt: Call POST `/v1/deliverability/check` for domain 'acme.com' with an Idempotency-Key header, then list past deliverability checks to compare with the last result

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/verify` | Verify one address |
| POST | `/v1/verify/batch` | Verify a list of addresses |
| GET | `/v1/jobs/{id}` | Get job progress and results |
| GET | `/v1/jobs/{id}/download` | Download a job's results |
| POST | `/v1/find` | Find a business address |
| POST | `/v1/deliverability/check` | Check a domain's email authentication |
| POST | `/v1/webhooks` | Register a webhook endpoint |

## Key resources

- **Verification** — Single, batch, and file verification of email addresses.
- **Jobs** — Asynchronous verification jobs: list, progress and results, download, and cancel.
- **Finder and domain lookup** — Work address finder for one or several people, and domain address lookup.
- **Deliverability** — Domain email authentication checks and their stored history.
- **Account, usage, and billing** — Account profile, credits, usage, credit transactions, API keys, plans, and credit packs.
- **Webhooks and exports** — Signed webhook endpoints with logs, retries, tests, and secret rotation, plus export schedules.

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 63 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 54 / 100
  - Developer Experience & Jentic Compatibility: 66 / 100
  - AI-Readiness & Agent Experience: 55 / 100
  - Agent Usability: 94 / 100
  - Security: 67 / 100
  - AI Discoverability: 56 / 100
- **View full report:** https://jentic.com/apis/kawaa.com/kawaa/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Kawaa by hand means choosing between the X-Api-Key, bearer, and OAuth2 paths, matching key scopes to each operation, sending Idempotency-Key headers so retries do not pay twice, and polling asynchronous jobs. Through Jentic you install once, import the Kawaa API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Kawaa puts the job id, domain, and webhook id in the URL path (`/v1/jobs/{id}`, `/v1/domain/{domain}`), so a rule can pin your agent to one job's results, while verification takes the address in the request body, so there rules bound which operations it may call. You choose those operations, so paid or sensitive ones like the email finder or API key revocation are not included unless you add them.
- **Credential handling:** Your Kawaa API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'verify an email address' or 'find a work email', and Jentic returns the matching Kawaa operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ZeroBounce** — ZeroBounce verifies single addresses and bulk files with its own credit model.
- **NeverBounce** — NeverBounce offers single and bulk email verification jobs.
- **Hunter API** — Hunter focuses on finding professional email addresses by domain and name.
- **Mailchimp** — Mailchimp sends the campaigns that a Kawaa-cleaned list feeds.

## FAQ

### What authentication does the Kawaa API use?

Per its OpenAPI spec, the Kawaa API accepts an API key in ev_ format either in the X-Api-Key header (apiKey scheme) or as Authorization: Bearer (bearer scheme), and an OAuth2 access token in evo_ format for apps acting for a person, which is always scoped and accepted only by operations that list it. Keys can be limited to scopes such as verification:write or webhooks:read. Only GET /health needs no credential. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time.

### Is there a Kawaa MCP server?

Yes - Kawaa offers an official MCP server at api.kawaa.com/mcp. You can also connect the REST API directly through Jentic: your agent gets the full 37-endpoint surface from the spec without loading another server's tool definitions into its context, your key is injected at call time by your self-hosted instance instead of living in an MCP config, and your rules decide which operations the agent may call.

### Can I limit what my agent is allowed to do with the Kawaa API?

Yes. Write a rule that allows only single verification, batch submission, job reads, and result downloads, so a list-cleaning agent spends credits on verification alone and cannot run the 5-credit finder, the 10-credit domain lookup, or touch API keys and webhooks. Every call it makes is logged, and GET `/v1/usage/credits/transactions` shows what it spent.

### How many credits does a Kawaa verification cost?

Per the spec, a single verification charges 1 credit, or 0.5 when served from cache, and unknown, risky, or catch_all results always cost 1. Batches charge about 1 credit per address when the job is accepted, the email finder charges 5, a fresh deliverability check or uncached domain lookup charges 10, and cancelling a batch refunds the unprocessed addresses.

### How large can a Kawaa batch be?

Per the spec, POST `/v1/verify/batch` accepts up to the plan's batch size in unique, well-formed addresses: Free 100, Starter 1,000, Professional and Business 5,000, and Enterprise 10,000. Larger lists go through POST `/v1/verify/file`, which takes CSV, TSV, or TXT files up to 50 MB.

### What are the rate limits for the Kawaa API?

The OpenAPI spec does not publish fixed numbers. GET `/v1/usage` reports the per-minute limit applied to your credential in its rate_limit field, so your agent can read its own ceiling; see https://kawaa.com/docs/ for plan details.

### How do I verify an email list with the Kawaa API through Jentic?

Search Jentic for an intent like 'verify a list of email addresses', import the Kawaa API from the API Directory, and store your API key. Your agent calls POST `/v1/verify/batch` with the emails, optionally a webhook_url, then polls GET `/v1/jobs/{id}` and downloads results with GET `/v1/jobs/{id}/download.` To run it on your own infrastructure, install Jentic One from its GitHub repo.