Workspace
Who you are, the workspace and its sending settings. 5 endpoints, each also a tool for your AI through MCP. Authentication and errors are on the overview.
curl https://ballast.to/api/v1/ping \
-H "Authorization: Bearer $BALLAST_API_KEY"Who am I: the user, workspace and plan behind this key or session
GET/api/v1/me
MCP tool whoamiRead-only
Returns
userrequiredobjectworkspacerequiredobjectrolerequired"owner" | "admin" | "member"authrequired"session" | "api_key" | "oauth"billingrequiredobject
curl https://ballast.to/api/v1/me \
-H "Authorization: Bearer $BALLAST_API_KEY"Members of this workspace, and pending invites for owners and admins
GET/api/v1/members
MCP tool list_membersRead-only
Returns
membersrequiredobject[]invitationsrequiredobject[]
curl https://ballast.to/api/v1/members \
-H "Authorization: Bearer $BALLAST_API_KEY"Workspace sending and reply settings shared by every campaign
GET/api/v1/settings/sending
MCP tool get_sending_settingsRead-only
Returns
unsubscribeModerequired"link" | "reply_text"- What {{unsubscribe}} becomes in every campaign: a one-click link, or a line asking to reply "stop"
aiLabelsrequiredboolean- Label replies with AI (OpenAI, Google Gemini as fallback, or the workspace's own key from Integrations). Off: only out-of-office, auto-replies and unsubscribe requests are labeled, by rules.
ownAiKeyrequired"openai" | "google" | null- The workspace's own AI key (Integrations): reply labels run on it, so reply text goes to that account, not Ballast's
curl https://ballast.to/api/v1/settings/sending \
-H "Authorization: Bearer $BALLAST_API_KEY"Change the workspace sending and reply settings
PATCH/api/v1/settings/sending
MCP tool update_sending_settingsOwners and admins
Parameters
unsubscribeMode"link" | "reply_text"- What {{unsubscribe}} becomes in every campaign: a one-click link, or a line asking to reply "stop"
aiLabelsboolean- Label replies with AI (OpenAI, Google Gemini as fallback, or the workspace's own key from Integrations). Off: only out-of-office, auto-replies and unsubscribe requests are labeled, by rules.
Returns
unsubscribeModerequired"link" | "reply_text"- What {{unsubscribe}} becomes in every campaign: a one-click link, or a line asking to reply "stop"
aiLabelsrequiredboolean- Label replies with AI (OpenAI, Google Gemini as fallback, or the workspace's own key from Integrations). Off: only out-of-office, auto-replies and unsubscribe requests are labeled, by rules.
ownAiKeyrequired"openai" | "google" | null- The workspace's own AI key (Integrations): reply labels run on it, so reply text goes to that account, not Ballast's
curl -X PATCH https://ballast.to/api/v1/settings/sending \
-H "Authorization: Bearer $BALLAST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"unsubscribeMode":"link","aiLabels":true}'