Integrations

Your verifier and your own AI key. 3 endpoints, each also a tool for your AI through MCP. Authentication and errors are on the overview.

List connected integrations

GET/api/v1/integrations

The workspace's email verifier (its own account) with credits left at the last check, and its own AI provider key (OpenAI or Gemini) if connected. Keys are never returned.

MCP tool list_integrationsRead-only

Returns

integrationsrequiredobject[]

cURL

curl https://ballast.to/api/v1/integrations \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Pick the models the workspace's own AI key runs

PUT/api/v1/integrations/ai/models

Only with the workspace's own OpenAI or Gemini key (Ballast's keys always run the cheapest models). Per job: write (Write with AI) and classify (reply labels); null = the default, cheapest model. A new pick is tested with the key first. The default model stays as the fallback. OpenAI: gpt-6-luna, gpt-6.1-sol, gpt-6-astra. Gemini: gemini-3.5-flash-lite, gemini-3.8-flash, gemini-4-argon.

MCP tool set_ai_modelsOwners and admins

Parameters

writestring | null
classifystring | null

cURL

curl -X PUT https://ballast.to/api/v1/integrations/ai/models \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"write":{},"classify":{}}'

Test a connected key again (verifier credits left, or the AI key on its model)

POST/api/v1/integrations/{provider}/check

MCP tool check_integrationOwners and admins

Parameters

providerrequiredpath · "millionverifier" | "zerobounce" | "neverbounce" | "openai" | "google"

Returns

providerrequired"millionverifier" | "zerobounce" | "neverbounce" | "openai" | "google": openai and google (Gemini) are AI providers, the others email verifiers
kindrequired"verifier" | "ai"
statusrequired"connected" | "error"
lastErrorrequiredstring | null
lastCheckedAtrequiredstring | null
creditsrequirednumber | null: Verification credits left at the last check (verifiers only)
modelrequiredstring | null: Model the AI key was tested on (AI providers only)
modelsrequiredobject | null: AI providers only: the model picked for Write with AI and for reply labels; null = the default, cheapest model
keyHintrequiredstring: Last 4 characters of the key
connectedByrequiredstring | null
createdAtrequiredstring

cURL

curl -X POST https://ballast.to/api/v1/integrations/<provider>/check \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Pick the models the workspace's own AI key runs

PUT/api/v1/integrations/ai/models

MCP tool set_ai_modelsOwners and admins

Parameters

writestring | null
classifystring | null

Test a connected key again (verifier credits left, or the AI key on its model)

POST/api/v1/integrations/{provider}/check

MCP tool check_integrationOwners and admins

Parameters

providerrequiredpath · "millionverifier" | "zerobounce" | "neverbounce" | "openai" | "google"

Returns

providerrequired"millionverifier" | "zerobounce" | "neverbounce" | "openai" | "google": openai and google (Gemini) are AI providers, the others email verifiers
kindrequired"verifier" | "ai"
statusrequired"connected" | "error"
lastErrorrequiredstring | null
lastCheckedAtrequiredstring | null
creditsrequirednumber | null: Verification credits left at the last check (verifiers only)
modelrequiredstring | null: Model the AI key was tested on (AI providers only)
modelsrequiredobject | null: AI providers only: the model picked for Write with AI and for reply labels; null = the default, cheapest model
keyHintrequiredstring: Last 4 characters of the key
connectedByrequiredstring | null
createdAtrequiredstring