Mailboxes

Connect, test and tune the mailboxes you send from. 8 endpoints, each also a tool for your AI through MCP. Authentication and errors are on the overview.

List mailboxes

GET/api/v1/mailboxes

Connected sending mailboxes with today's limit, ramp-up and the DNS health of their domain.

MCP tool list_mailboxesRead-only

Returns

mailboxesrequiredobject[]
microsoftEnabledrequiredboolean
slotsLeftrequirednumber | null

cURL

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

Suggest connection settings for an email address

GET/api/v1/mailboxes/detect

Read-only

Parameters

emailrequiredquery · string

Returns

domainrequiredstring
providerrequired"google" | "microsoft" | "other" | "none"
providerLabelrequiredstring
smtprequiredobject | null
imaprequiredobject | null
passwordHintrequiredobject | null: Where to make an app password, for providers that refuse the normal one

cURL

curl https://ballast.to/api/v1/mailboxes/detect?email=<email> \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Test SMTP and IMAP login without saving

POST/api/v1/mailboxes/test

Owners and admins

Returns

okrequiredboolean
smtprequiredobject
imaprequiredobject

cURL

curl -X POST https://ballast.to/api/v1/mailboxes/test \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Connect a mailbox

POST/api/v1/mailboxes

Tests SMTP and IMAP login first and saves only when both pass. Google needs an app password. Microsoft 365 connects with OAuth from the dashboard.

MCP tool add_mailboxOwners and admins

Returns

mailboxrequiredobject | null
testrequiredobject
waitingrequiredboolean: Saved, but no sending IP has room yet: it is tested and starts once one does, usually within a day

cURL

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

Import SMTP/IMAP mailboxes in bulk

POST/api/v1/mailboxes/import

Up to 200 mailboxes per call. Each one is tested and saved only if SMTP and IMAP login pass.

MCP tool import_mailboxesOwners and adminsMCP asks to confirm

Parameters

rowsrequiredobject[]

Returns

addedrequirednumber
resultsrequiredobject[]

cURL

curl -X POST https://ballast.to/api/v1/mailboxes/import \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":[]}'

Change a mailbox's limits, signature or status

PATCH/api/v1/mailboxes/{id}

MCP tool update_mailboxOwners and admins

Parameters

idrequiredpath · string
displayNamestring | null
signaturestring | null
timezonestring
status"active" | "paused": Pause or resume sending from this mailbox
limitsobject
restartRampboolean: Start the ramp again from day 1
inboxPollboolean: Read the inbox every 60 s instead of keeping a connection open (fewer simultaneous connections; offered for Google)
credentialsobject: New password (and optionally servers). Tested before saving.

Returns

mailboxrequiredobject
testrequiredobject | null

cURL

curl -X PATCH https://ballast.to/api/v1/mailboxes/<id> \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"displayName":{},"signature":{}}'

Test a connected mailbox again

POST/api/v1/mailboxes/{id}/test

MCP tool test_mailboxOwners and admins

Parameters

idrequiredpath · string

Returns

okrequiredboolean
errorrequiredstring | null

cURL

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

Disconnect a mailbox

DELETE/api/v1/mailboxes/{id}

MCP tool delete_mailboxOwners and adminsMCP asks to confirm

Parameters

idrequiredpath · string

Returns

okrequiredtrue

cURL

curl -X DELETE https://ballast.to/api/v1/mailboxes/<id> \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Suggest connection settings for an email address

GET/api/v1/mailboxes/detect

Read-only

Parameters

emailrequiredquery · string

Returns

domainrequiredstring
providerrequired"google" | "microsoft" | "other" | "none"
providerLabelrequiredstring
smtprequiredobject | null
imaprequiredobject | null
passwordHintrequiredobject | null: Where to make an app password, for providers that refuse the normal one

Connect a mailbox

POST/api/v1/mailboxes

Tests SMTP and IMAP login first and saves only when both pass. Google needs an app password. Microsoft 365 connects with OAuth from the dashboard.

MCP tool add_mailboxOwners and admins

Returns

mailboxrequiredobject | null
testrequiredobject
waitingrequiredboolean: Saved, but no sending IP has room yet: it is tested and starts once one does, usually within a day

Change a mailbox's limits, signature or status

PATCH/api/v1/mailboxes/{id}

MCP tool update_mailboxOwners and admins

Parameters

idrequiredpath · string
displayNamestring | null
signaturestring | null
timezonestring
status"active" | "paused": Pause or resume sending from this mailbox
limitsobject
restartRampboolean: Start the ramp again from day 1
inboxPollboolean: Read the inbox every 60 s instead of keeping a connection open (fewer simultaneous connections; offered for Google)
credentialsobject: New password (and optionally servers). Tested before saving.

Returns

mailboxrequiredobject
testrequiredobject | null