Quickstart
From zero to your first verified address in under five minutes. You need a SalchiMail account and a terminal.
1. Create an API key
Sign in to the dashboard at app.salchimail.com and create an API key. The key is shown once: copy it now.
sk_live_…keys run real verifications and use credits.sk_test_…keys return simulated results and never use credits. See Test mode.
Keep the key in an environment variable. It is a secret: use it from your server, never from a browser or a mobile app.
export SALCHIMAIL_API_KEY="sk_live_your_key"2. Verify an address
Replace ana@example.com with an address you know and run the request. mode is mailbox here, so the mail server is asked whether the mailbox exists. No email is sent.
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"}'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);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
$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";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)
}A mailbox check talks to the recipient's mail server and can take up to 30 seconds, so give your HTTP client a timeout above that.
3. Read the result
The answer is a verification object:
{
"id": "ver_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
"object": "verification",
"livemode": true,
"email": "ana@example.com",
"mode": "mailbox",
"verdict": "valid",
"reason_code": "mailbox_exists",
"reason": "The mail server accepts this recipient and rejects a random one.",
"flags": {
"disposable": false,
"free": false,
"catch_all": false
},
"checks": [
{
"name": "syntax",
"status": "ok"
},
{
"name": "dns",
"status": "mx"
},
{
"name": "smtp",
"status": "accepted"
},
{
"name": "catch_all",
"status": "missing"
}
],
"mx": [
{
"host": "mx1.example.com",
"preference": 10
}
],
"smtp": {
"mx": "mx1.example.com",
"code": 250,
"enhanced_code": null,
"tls": true
},
"cached": false,
"credits_charged": 1,
"checked_at": "2026-11-17T09:50:04Z",
"retry_at": null
}Start with verdict, then read reason_code for the why:
verdict |
What it means | What to do |
|---|---|---|
valid |
The server accepts this recipient and rejects a random one | Send |
invalid |
Bad syntax, a domain that cannot receive mail, or a clear "no such recipient" | Do not send |
risky |
Accept-all server, disposable domain, full or disabled mailbox, and similar | Decide by reason_code |
unknown |
The check could not finish or was not done | Do not treat it as invalid. Retry after retry_at when present |
credits_charged tells you what this call cost. In mailbox mode an unknown result is free. The full list is in Verdicts and reason codes.
4. Pick the mode for your case
- A sign-up form: use
"mode": "basic". It checks syntax, domain lists and DNS in well under a second. See Verify at sign-up. - A list: send it as a batch instead of one request per address. See Clean a list in batches.
Next steps
- Authentication: key types, rotation and what a
401means. - Idempotency: retry a
POSTsafely. - Limits and errors: rate limits and every error code.
- API reference: every endpoint, field and example.