Developer documentation
MCP
Use the Model Context Protocol to inspect your migrations, preview batches, queue approved syncs and cancel transfers that have not started.
This reference is public. Every tool call requires a verified MailSync account and a valid access token, and can access only that account’s mailboxes and credits.
Connect your client
Configure a Streamable HTTP MCP connection to this endpoint:
https://mailsync.tsihosting.com/mcp/mailsync
Use a client that supports a configured bearer token. OAuth sign-in and automatic OAuth discovery are not currently provided. Generate your own token in Account → MCP tokens after verifying your email address. Choose a client name, permissions and an expiry of 1–90 days, then confirm your account password. Read-only access is the default; choose write access to permit queueing and cancellation.
Copy the token when it is displayed: it is shown only once. You can review and revoke your tokens at any time on the MCP tokens page. Revoking access does not stop transfers already queued or running.
Store the token in your client’s secret settings and send it in the authorization header. Do not place it in a prompt, URL or shared configuration.
Authorization: Bearer <your-access-token>
Browser login cookies are not accepted for MCP authentication. Use HTTPS for production connections. The operator must enable MCP access on the installation; a disabled endpoint returns HTTP 404. The documentation remains available.
Scopes
mcp:use: connect to the MailSync MCP server.migrations:read: inspect migrations, run history and batch eligibility.credits:read: inspect credit balances and batch credit requirements.migrations:write: queue selected syncs and cancel a specified queued run.
Protocol example
Your MCP client handles initialization and tool discovery. The following is a tool-call body after initialization; include the negotiated protocol headers required by your client.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_migrations",
"arguments": {"status": "failed", "per_page": 20}
}
}
Successful tool results provide parseable data in result.structuredContent and a JSON text copy in result.content. Use tools/list to discover the current input and output schemas.
Preview, approve, then queue
- Save mailboxes and passwords through MailSync’s normal interface, then use
list_migrationsandget_migrationto inspect them. - Call
preview_sync_batchwith the exact migration IDs. Show the user the selected mailboxes, blockers and credits required. A preview makes no changes and reserves nothing. - After user approval, call
queue_sync_batchwith those IDs and a new UUIDrequest_key. The server rechecks eligibility and queues the entire batch or none of it. - Read run history to follow the returned run IDs. Transfers execute in the background; no detailed message-level progress counters are available.
Each credit is permanently assigned to one mailbox pair and allows six successful runs. Queueing reserves one run allowance per mailbox. Failure, timeout or cancellation before execution restores the allowance once; the credit stays assigned. Team membership does not share credits or credentials.
Retrying a lost response
Retry a queue request using the same UUID and the same selection. It returns the original run IDs even after those runs finish, without spending another allowance. Order of IDs does not matter. A key used with a different selection is rejected. Use a new key only when the user deliberately requests another sync.
Successful request keys are retained for the account’s lifetime. Replayed results contain their original queued status; read run history for current status. Failed transactions do not retain a result. Cancellation takes both a migration ID and run ID so a delayed call cannot cancel a newer transfer.
Tool reference
The schemas below are generated from the server’s tool definitions. IDs are positive integers. Pagination starts at page 1; lists default to 50 results and run history to 20. Both accept up to 100 results per page and return next_page: null when no further page exists.
list_migrations
List owned migrations with bounded pagination and optional latest-status filtering.
Required scopes: mcp:use, migrations:read
Read-only operation.
Input schema
{
"properties": {
"page": {
"minimum": 1,
"maximum": 1000000,
"type": "integer"
},
"per_page": {
"minimum": 1,
"maximum": 100,
"type": "integer"
},
"status": {
"enum": [
"ready",
"queued",
"running",
"completed",
"failed",
"cancelled"
],
"type": "string"
}
},
"type": "object"
}
Output schema
{
"properties": {
"migrations": {
"items": {
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
},
"remaining_runs": {
"type": "integer"
},
"has_credentials": {
"type": "boolean"
}
},
"type": "object",
"required": [
"id",
"name",
"status",
"remaining_runs",
"has_credentials"
]
},
"type": "array"
},
"next_page": {
"type": [
"integer",
"null"
]
}
},
"type": "object",
"required": [
"migrations",
"next_page"
]
}
get_migration
Read one owned migration, safe connection settings and paginated run history. Never returns passwords.
Required scopes: mcp:use, migrations:read
Read-only operation.
Input schema
{
"properties": {
"migration_id": {
"minimum": 1,
"type": "integer"
},
"page": {
"minimum": 1,
"maximum": 1000000,
"type": "integer"
},
"per_page": {
"minimum": 1,
"maximum": 100,
"type": "integer"
}
},
"type": "object",
"required": [
"migration_id"
]
}
Output schema
{
"properties": {
"migration": {
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
},
"remaining_runs": {
"type": "integer"
},
"has_credentials": {
"type": "boolean"
},
"source_host": {
"type": "string"
},
"source_port": {
"type": "integer"
},
"source_username": {
"type": "string"
},
"source_encryption": {
"type": "string"
},
"source_verify_certificate": {
"type": "boolean"
},
"destination_host": {
"type": "string"
},
"destination_port": {
"type": "integer"
},
"destination_username": {
"type": "string"
},
"destination_encryption": {
"type": "string"
},
"destination_verify_certificate": {
"type": "boolean"
}
},
"type": "object",
"required": [
"id",
"name",
"status",
"remaining_runs",
"has_credentials",
"source_host",
"source_port",
"source_username",
"source_encryption",
"source_verify_certificate",
"destination_host",
"destination_port",
"destination_username",
"destination_encryption",
"destination_verify_certificate"
]
},
"runs": {
"items": {
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"status": {
"type": "string"
},
"message": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"started_at": {
"type": [
"string",
"null"
]
},
"finished_at": {
"type": [
"string",
"null"
]
}
},
"type": "object",
"required": [
"id",
"status",
"message",
"created_at",
"started_at",
"finished_at"
]
},
"type": "array"
},
"next_page": {
"type": [
"integer",
"null"
]
}
},
"type": "object",
"required": [
"migration",
"runs",
"next_page"
]
}
get_credit_balance
Read unassigned credits and attached allowances for the authenticated user.
Required scopes: mcp:use, credits:read
Read-only operation.
Input schema
{
"type": "object",
"properties": {}
}
Output schema
{
"properties": {
"unassigned_credits": {
"type": "integer"
},
"attached_remaining_runs": {
"type": "integer"
},
"explanation": {
"type": "string"
}
},
"type": "object",
"required": [
"unassigned_credits",
"attached_remaining_runs",
"explanation"
]
}
preview_sync_batch
Preview an exact mailbox selection without reserving allowances. Explain blockers and new credits required before requesting user approval.
Required scopes: mcp:use, migrations:read, credits:read
Read-only operation.
Input schema
{
"properties": {
"migration_ids": {
"minItems": 1,
"maxItems": 250,
"items": {
"minimum": 1,
"type": "integer"
},
"uniqueItems": true,
"type": "array"
}
},
"type": "object",
"required": [
"migration_ids"
]
}
Output schema
{
"properties": {
"migrations": {
"items": {
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
},
"remaining_runs": {
"type": "integer"
},
"has_credentials": {
"type": "boolean"
},
"blocking_reasons": {
"items": {
"type": "string"
},
"type": "array"
},
"needs_new_credit": {
"type": "boolean"
}
},
"type": "object",
"required": [
"id",
"name",
"status",
"remaining_runs",
"has_credentials",
"blocking_reasons",
"needs_new_credit"
]
},
"type": "array"
},
"new_credits_required": {
"type": "integer"
},
"unassigned_credits": {
"type": "integer"
},
"can_queue": {
"type": "boolean"
},
"advisory": {
"type": "string"
}
},
"type": "object",
"required": [
"migrations",
"new_credits_required",
"unassigned_credits",
"can_queue",
"advisory"
]
}
queue_sync_batch
Queue an explicitly approved selection atomically. Reserves one allowance per mailbox and may permanently assign credits. Preview first. Keep the UUID request key unchanged when retrying; results retain original queued statuses, so read migration history for current status.
Required scopes: mcp:use, migrations:write
Changes migration state. Requires explicit user authorization in your client workflow.
Input schema
{
"properties": {
"migration_ids": {
"minItems": 1,
"maxItems": 250,
"items": {
"minimum": 1,
"type": "integer"
},
"uniqueItems": true,
"type": "array"
},
"request_key": {
"description": "UUID for this deliberate queue request. Keep it unchanged on retries.",
"format": "uuid",
"type": "string"
}
},
"type": "object",
"required": [
"migration_ids",
"request_key"
]
}
Output schema
{
"properties": {
"runs": {
"items": {
"additionalProperties": false,
"properties": {
"migration_id": {
"type": "integer"
},
"run_id": {
"type": "integer"
},
"status": {
"type": "string"
}
},
"type": "object",
"required": [
"migration_id",
"run_id",
"status"
]
},
"type": "array"
}
},
"type": "object",
"required": [
"runs"
]
}
cancel_queued_sync
Cancel only the specified queued run and restore its allowance once. Cannot interrupt a running transfer. A false cancelled result means this call changed nothing.
Required scopes: mcp:use, migrations:write
Changes migration state. Requires explicit user authorization in your client workflow.
Input schema
{
"properties": {
"migration_id": {
"minimum": 1,
"type": "integer"
},
"run_id": {
"minimum": 1,
"type": "integer"
}
},
"type": "object",
"required": [
"migration_id",
"run_id"
]
}
Output schema
{
"properties": {
"run_id": {
"type": "integer"
},
"cancelled": {
"type": "boolean"
},
"status": {
"type": "string"
},
"allowance_restored": {
"type": "boolean"
}
},
"type": "object",
"required": [
"run_id",
"cancelled",
"status",
"allowance_restored"
]
}
Limits and errors
- Batch tools accept 1–250 distinct migration IDs. Only one transfer per mailbox can be queued or running.
- The server allows 60 requests and 10 mutation calls per minute per user, shared across that user’s client tokens. Poll conservatively.
- HTTP 401 indicates a missing, invalid, expired or revoked token. HTTP 403 indicates an unverified account or rejected connection origin. HTTP 429 includes
Retry-Afterfor the request limit. - Tool-level failures return
result.isError: truewith a safe explanation inresult.content, including missing scopes, invalid input, unavailable records or ineligible selections. Mutation-limit errors ask you to wait one minute. - Missing and inaccessible records produce the same not-found response. Unknown arguments are rejected. A batch rejection queues no syncs from that request.
- Cancellation restores an allowance only when
allowance_restoredis true. A running transfer cannot be interrupted through this interface.
Passwords and raw engine output are never returned. Credential entry, credit purchases, free-credit grants, worker recovery and DNS changes are outside this interface. To correct connection settings or passwords, use MailSync’s normal interface while the mailbox is idle.
For the wider migration workflow, read the migration guide or the FAQ.