kawaa-com Jobs API

openapi: 3.2.0
info:
  title: Kawaa Jobs API
  version: 1.0.0
  summary: Email verification, list hygiene and deliverability, over HTTP.
  description: 'The core Kawaa REST API: verify an address or a list, follow the job, read the results, and check how a domain is set up to send mail. This document describes the endpoints a customer integration uses. It is not the whole surface: profile and security settings (password, two-factor, sessions), billing and subscription changes and team management are reachable but not modelled here, because a specification is only worth having if every line of it is kept true, and they have no page at https://kawaa.com/docs/ yet either. Some operations that do have a page there are not modelled here either, and that page is their only reference: the white-label API (`POST /v1/white-label/sub-accounts`, `GET /v1/white-label/sub-accounts`, `GET /v1/white-label/sub-accounts/{subAccountId}`, `PUT /v1/white-label/sub-accounts/{subAccountId}`, `DELETE /v1/white-label/sub-accounts/{subAccountId}`, `POST /v1/white-label/sub-accounts/{subAccountId}/allocate`, `POST /v1/white-label/sub-accounts/{subAccountId}/reset-key`, `GET /v1/white-label/usage`, `GET /v1/white-label/usage/{subAccountId}`, `GET /v1/white-label/custom-domain`, `POST /v1/white-label/custom-domain`, `POST /v1/white-label/custom-domain/verify` and `DELETE /v1/white-label/custom-domain`) at https://kawaa.com/docs/api/white-label/, the domain activity lookup (`GET /v1/activity/domain/{domain}`) at https://kawaa.com/docs/api/activity/#domain-activity, and the tracking links (`POST /v1/tracking/links` and `PUT /v1/tracking/links/{id}`), whose limits are at https://kawaa.com/docs/api/activity/#tracking-link-limits. The HubSpot, Salesforce and Mailchimp integrations are not available yet: their authorize routes answer 503 `INTEGRATION_NOT_CONFIGURED`, so no account can connect one. The guides at https://kawaa.com/docs/ cover verification, batch jobs, account and API keys, webhooks, activity, deliverability and the white-label API; the email finder (`POST /v1/find`, `POST /v1/find/bulk`), the domain lookup (`GET /v1/domain/{domain}`) and the billing catalogue (`GET /v1/billing/plans`, `GET /v1/billing/credit-packages`) are described only in this document. **API key scopes.** A key can be limited to a list of scopes. Each operation below carries `x-kawaa-scopes` naming every scope it requires (more than one where a route genuinely touches two areas). `x-kawaa-unscoped-only: true` marks an operation a scoped key may not use at all, whatever it holds: it mints a credential, or it acts across every tenant. An operation with neither extension needs no credential. An unrestricted key (which is what every key is unless it was created with scopes) reaches everything. An OAuth access token is always scoped: an operation it can call lists the `OAuth2` scheme in its `security`, with the scopes it requires, and an authenticated operation that does not list it refuses one whatever scopes it holds. **Rate-limit headers.** Once a request''s credential is accepted and its rate limit measured, every response to it, success or error, carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Window` and `X-RateLimit-Policy` (described under `components/headers`). They are declared on the success and `429` responses below rather than repeated on every status. **Answers that do not come from Kawaa.** A few failures are answered by the gateway in front of the API rather than by Kawaa, and carry no error envelope, so there is no `error.code` to branch on: read the status. A request still running when its route''s time limit at the gateway runs out (about 29 to 30 seconds on most routes, every route that charges credits included; 15 seconds on `GET /v1/account`, the `/v1/api-keys` routes, `GET /v1/jobs`, `GET /v1/jobs/{id}` and `POST /v1/jobs/{id}/cancel`; 5 seconds on `GET /health`), or one the gateway could not hand over, is a `503` whose whole body is `{"message":"Service Unavailable"}`; the request may still have run, so repeat a charging call only with the same `Idempotency-Key`.'
  termsOfService: https://kawaa.com/terms/
  contact:
    name: Kawaa support
    url: https://kawaa.com/support/
    email: support@kawaa.com
  license:
    name: Proprietary
    identifier: LicenseRef-Kawaa-Terms
servers:
- url: https://api.kawaa.com
  description: Production
security:
- ApiKeyHeader: []
- BearerToken: []
tags:


# --- truncated at 32 KB (85 KB total) ---
# Full source: https://artifacts.apis.io/kawaa-com/openapi/kawaa-com-jobs-api-openapi.yml