# SalchiMail Docs

> SalchiMail is an email verification API that never sends email: mailbox checks stop at `RCPT TO`. Verify one address per request or clean lists in batches. Every result has a verdict (`valid`, `invalid`, `risky`, `unknown`) and a stable `reason_code`.

- Base URL: `https://api.salchimail.com/v1`. JSON over HTTPS.
- Authentication: `Authorization: Bearer sk_live_…` (or `sk_test_…` for test mode). Keys are server-side secrets.
- Two modes: `basic` (syntax, domain lists, DNS) and `mailbox` (adds the SMTP `RCPT TO` probe). Each has its own credit balance.
- Never treat `unknown` as `invalid`.

## Guides

- [Quickstart · Verify your first email in under 5 minutes](https://docs.salchimail.com/quickstart.md): Create an API key, verify your first email address with curl, JavaScript, Python, PHP or Go, and learn how to read the verdict. Under five minutes.
- [Authentication · API keys](https://docs.salchimail.com/authentication.md): How SalchiMail API keys work, live and test keys, how to send the Bearer header, how to rotate a key and what each 401 and 403 error means.
- [Test mode · sk_test_ keys](https://docs.salchimail.com/test-mode.md): Use sk_test_ keys to build and test your SalchiMail integration with predictable verdicts, without real verifications and without using credits.
- [Verify emails at sign-up · Recommended pattern and timings](https://docs.salchimail.com/signup-verification.md): The recommended way to verify emails in a sign-up form with the SalchiMail API: which mode to use, timeouts and what to do with each verdict.
- [Clean an email list in batches · JSON and CSV](https://docs.salchimail.com/batches.md): Verify a whole email list with the SalchiMail batch API: upload JSON or CSV, follow progress and download the results. Deadlines and limits included.
- [Verdicts and reason codes · What each one means and what to do](https://docs.salchimail.com/verdicts.md): The four SalchiMail verdicts (valid, invalid, risky, unknown) and every reason_code, with its meaning, whether it is charged and what to do with the address.
- [Webhooks · Events and signature verification](https://docs.salchimail.com/webhooks.md): Receive SalchiMail events such as batch.completed and credits.low. Verify the SalchiMail-Signature HMAC header, with examples, retries and deduplication.
- [Idempotency · Retry POST requests safely](https://docs.salchimail.com/idempotency.md): Use the Idempotency-Key header to retry SalchiMail POST requests without verifying or charging twice. How keys work, how long they last and the 409 conflicts.
- [Credits and billing · What each verification costs](https://docs.salchimail.com/credits.md): How SalchiMail credits work. Basic and mailbox balances, what is charged and what is free, reservations in batches, the usage endpoint and what happens at zero.
- [Limits and errors · Rate limits, error codes and retries](https://docs.salchimail.com/limits-and-errors.md): SalchiMail API rate limits and size limits, the single error format, every error code with what to do about it, and which requests are safe to retry.
- [Use SalchiMail from AI agents · llms.txt, Markdown, OpenAPI and MCP](https://docs.salchimail.com/ai-agents.md): How AI agents and coding assistants can use the SalchiMail API: llms.txt, a Markdown version of every page, the OpenAPI contract, MCP and skill.

## API reference

- [API reference in Markdown](https://docs.salchimail.com/reference.md): Every operation, parameter, schema and example of the contract.
- [OpenAPI 3.1 (JSON)](https://docs.salchimail.com/openapi.json)
- [OpenAPI 3.1 (YAML)](https://docs.salchimail.com/openapi.yaml)

## Optional

- [Changelog · SalchiMail API](https://docs.salchimail.com/changelog.md): Changes to the SalchiMail API and how it is versioned. What can change without notice inside v1 and what would require a new version.
- [Everything in one file](https://docs.salchimail.com/llms-full.txt)
- [Documentación en español](https://docs.salchimail.com/es/llms.txt)
