# SalchiMail API documentation

Verify email addresses without sending them a single message. Check one address in a request, or clean a whole list in a batch.

**curl**

```bash
curl https://api.salchimail.com/v1/verify \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ana@example.com", "mode": "mailbox"}'
```

**JavaScript / TypeScript**

```js
const response = await fetch("https://api.salchimail.com/v1/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SALCHIMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "ana@example.com", mode: "mailbox" }),
});
const result = await response.json();

if (!response.ok) {
  throw new Error(`${result.error.code}: ${result.error.message}`);
}
console.log(result.verdict, result.reason_code);
```

**Python**

```python
import json
import os
import urllib.error
import urllib.request

request = urllib.request.Request(
    "https://api.salchimail.com/v1/verify",
    data=json.dumps({"email": "ana@example.com", "mode": "mailbox"}).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['SALCHIMAIL_API_KEY']}",
        "Content-Type": "application/json",
    },
)
try:
    with urllib.request.urlopen(request, timeout=40) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    problem = json.load(error)["error"]
    raise SystemExit(f"{problem['code']}: {problem['message']}")

print(result["verdict"], result["reason_code"])
```

**PHP**

```php
<?php
$ch = curl_init("https://api.salchimail.com/v1/verify");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 40,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SALCHIMAIL_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["email" => "ana@example.com", "mode" => "mailbox"]),
]);
$body = curl_exec($ch);
if ($body === false) {
    fwrite(STDERR, "Request failed: " . curl_error($ch) . "\n");
    exit(1);
}
$result = json_decode($body, true);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
    fwrite(STDERR, "{$result['error']['code']}: {$result['error']['message']}\n");
    exit(1);
}
echo "{$result['verdict']} {$result['reason_code']}\n";
```

**Go**

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"
)

type verification struct {
	Verdict    string `json:"verdict"`
	ReasonCode string `json:"reason_code"`
	Error      *struct {
		Code    string `json:"code"`
		Message string `json:"message"`
	} `json:"error"`
}

func main() {
	payload, _ := json.Marshal(map[string]string{"email": "ana@example.com", "mode": "mailbox"})
	req, _ := http.NewRequest("POST", "https://api.salchimail.com/v1/verify", bytes.NewReader(payload))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SALCHIMAIL_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{Timeout: 40 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()

	var result verification
	if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}
	if result.Error != nil {
		log.Fatalf("%s: %s", result.Error.Code, result.Error.Message)
	}
	fmt.Println(result.Verdict, result.ReasonCode)
}
```

Every result carries a **verdict** (`valid`, `invalid`, `risky` or `unknown`), a stable `reason_code` that says why, and `credits_charged`, so you always know what a call cost.

| Basics | |
| --- | --- |
| Base URL | `https://api.salchimail.com/v1` |
| Authentication | `Authorization: Bearer sk_live_…` ([details](https://docs.salchimail.com/authentication.md)) |
| Format | JSON over HTTPS. Every error has the same shape ([details](https://docs.salchimail.com/limits-and-errors.md)) |
| Contract | OpenAPI 3.1: [`openapi.yaml`](https://docs.salchimail.com/openapi.yaml) · [`openapi.json`](https://docs.salchimail.com/openapi.json) |

## Two ways to verify

| `mode` | What it checks | Typical use |
| --- | --- | --- |
| `basic` | Syntax, disposable and free-provider lists, DNS and MX records | Sign-up forms: it answers in well under a second |
| `mailbox` | Everything in `basic`, plus an SMTP `RCPT TO` probe and a catch-all control | Cleaning a list before a campaign |

A mailbox check stops at `RCPT TO` and never issues `DATA`: no message is ever sent to the address. Each mode uses its own [credit balance](https://docs.salchimail.com/credits.md).

## Guides

- [Quickstart](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](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](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 at sign-up](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 a list in batches](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](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](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](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](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](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 from AI agents](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](https://docs.salchimail.com/reference.md): Complete reference of the SalchiMail API v1, generated from the OpenAPI 3.1 contract. Verify, batches, usage, account and webhooks, with schemas and examples.
- [Changelog](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.

## For AI agents

Every page has a Markdown twin (add `.md` to its URL) and the site publishes [`llms.txt`](https://docs.salchimail.com/llms.txt) and [`llms-full.txt`](https://docs.salchimail.com/llms-full.txt). See [Use from AI agents](https://docs.salchimail.com/ai-agents.md).
