Skip to content
simplelogin-mcp

API coverage

This page is rendered from the repository’s canonical API coverage document. It distinguishes the implemented tool surface from areas that are deferred or intentionally outside the project scope.

This document maps the public simplelogin-mcp tool surface to the upstream SimpleLogin API reference. It is meant for public readers who need the project scope at a glance, and for maintainers deciding whether future milestones should add, defer, or reject endpoint coverage.

Sources checked:

Status Legend

  • Supported: exposed as an MCP tool, backed by a typed client method and response schema, and included in public tool-surface drift checks.
  • Planned: accepted for existing roadmap work but not implemented yet.
  • Deferred: upstream exposes the area, but this project has not accepted support. It needs a product decision, response-size strategy, live verification, or focused tests before a milestone should claim it.
  • Non-goal: intentionally out of scope. Some non-goals are excluded because the upstream API does not expose them; others are excluded even though an API endpoint exists because they are too account-sensitive, billing-related, or outside alias management.

No SimpleLogin API endpoint group currently has a separate implementation issue in Planned status. Future coverage proposals should use this matrix to distinguish accepted work from deferred areas and non-goals.

Coverage Matrix

SimpleLogin API area / endpoint group Status MCP tools Relevant local files Roadmap Rationale / caveat
Account auth, registration, MFA, API-key creation, cookie-token exchange, and logout: POST /api/auth/login, POST /api/auth/mfa, deprecated social auth, register/activate/reactivate/forgot-password, POST /api/api_key, GET /api/user/cookie_token, GET /api/logout Non-goal None README.md, SECURITY.md None The server uses a pre-created SL_API_KEY. It does not collect passwords, MFA codes, browser cookies, or create SimpleLogin API keys.
Account read: GET /api/user_info, GET /api/stats Supported account_get_info, account_get_stats src/constants.ts, src/client/simplelogin.ts, src/tools/account.ts, src/schemas/account.ts Supported since v0.1/v0.5 Read-only account utilities. account_get_info also serves as an API-key sanity check.
Account profile update: PATCH /api/user_info Deferred None None No existing issue Upstream documents profile picture/name updates, but they are outside the current alias, mailbox, domain, notification, and settings workflow. Needs a user-facing reason and focused tests before support.
Sudo mode and account deletion: PATCH /api/sudo, DELETE /api/user Non-goal None README.md, SECURITY.md, src/tools/account.ts None The API exposes these endpoints, but the project intentionally excludes password re-authentication, sudo-mode account-sensitive flows, and account deletion.
Alias lifecycle, creation options, and activity: GET /api/v5/alias/options, POST /api/v3/alias/custom/new, POST /api/alias/random/new, GET/POST /api/v2/aliases, GET/PATCH/DELETE /api/aliases/:alias_id, POST /api/aliases/:alias_id/toggle, GET /api/aliases/:alias_id/activities Supported alias_options_get, alias_create_custom, alias_create_random, alias_list, alias_get, alias_update, alias_delete, alias_set_enabled, alias_activity_list src/constants.ts, src/client/simplelogin.ts, src/tools/aliases.ts, src/schemas/alias.ts, src/tools/catalog.ts Supported since v0.1/v0.3/v0.6 Core project scope. Reads are bounded to 20-item pages. alias_set_enabled wraps the upstream toggle with a read-first idempotent tool. Permanent alias deletion requires confirm: true.
Alias creation domains: GET /api/v2/setting/domains Supported alias_domains_list src/constants.ts, src/client/simplelogin.ts, src/tools/aliases.ts, src/schemas/domain.ts Supported since v0.1/v0.5 Supports listing domains usable for random aliases and validating settings_update guidance. It does not create or verify domains.
Alias contacts and reverse aliases: GET /api/aliases/:alias_id/contacts, POST /api/aliases/:alias_id/contacts, POST /api/contacts/:contact_id/toggle, DELETE /api/contacts/:contact_id Supported contact_list, contact_create, contact_set_blocked, contact_delete src/constants.ts, src/client/simplelogin.ts, src/tools/contacts.ts, src/schemas/contact.ts Supported since v0.3 Supports reverse-alias creation and forwarding block/unblock. contact_set_blocked wraps the upstream toggle with a read-first idempotent tool. Contact creation can require a premium SimpleLogin plan.
Mailboxes: GET /api/v2/mailboxes, POST /api/mailboxes, PUT /api/mailboxes/:mailbox_id, DELETE /api/mailboxes/:mailbox_id Supported mailbox_list, mailbox_create, mailbox_update, mailbox_delete src/constants.ts, src/client/simplelogin.ts, src/tools/mailboxes.ts, src/schemas/mailbox.ts Supported since v0.4 Supports mailbox list/create/update/delete with local guardrails. Deletion requires confirm: true and an explicit alias transfer/delete decision; the default mailbox cannot be deleted.
Custom-domain exposed settings and trash: GET /api/custom_domains, PATCH /api/custom_domains/:custom_domain_id, GET /api/custom_domains/:custom_domain_id/trash Supported custom_domain_list, custom_domain_update, custom_domain_trash_list src/constants.ts, src/client/simplelogin.ts, src/tools/domains.ts, src/schemas/domain.ts Supported since v0.5/v0.6 Supports listing domains, updating catch-all/random-prefix/display-name/mailbox routing, and reading trash. Trash is locally paged because the upstream endpoint is not server-paginated.
Custom-domain create/delete and DNS/MX verification Non-goal None README.md, src/tools/domains.ts None The upstream API reference does not expose endpoints for these operations. Use the SimpleLogin web UI for domain creation, deletion, and DNS verification.
Notifications: GET /api/notifications, POST /api/notifications/:notification_id in the API reference Supported notification_list, notification_mark_read src/constants.ts, src/client/simplelogin.ts, src/tools/account.ts, src/schemas/account.ts Supported since v0.5 Supports listing notifications and marking one read. The upstream reference lists POST /api/notifications/:notification_id; the client uses the source-registered /read suffix. Treat this as an endpoint-path caveat, not additional coverage. Notifications cannot be marked unread or deleted through the API.
Account alias settings: GET /api/setting, PATCH /api/setting Supported settings_get, settings_update src/constants.ts, src/client/simplelogin.ts, src/tools/account.ts, src/schemas/account.ts Supported since v0.5 settings_update is deliberately limited to the five documented alias-behavior fields: alias_generator, notification, random_alias_default_domain, sender_format, and random_alias_suffix.
Import and export: GET /api/export/data, GET /api/export/aliases Deferred None None No existing issue Upstream exposes data and CSV exports, but this project has not designed large-output handling, redaction expectations, or MCP response bounds for exported account data.
Apple payment receipt processing: POST /api/apple/process_payment Non-goal None README.md, src/tools/account.ts None Payment and subscription management are intentionally excluded even though the upstream API exposes an Apple receipt endpoint. Use SimpleLogin billing flows instead.
Phone reservation messages: GET /api/phone/reservations/:reservation_id Deferred None None No existing issue This is outside the current email-alias, mailbox, custom-domain, and account-utility scope. It needs product-scope validation and sample payload tests before support.

Explicit Non-Goals

Non-goal API exposure Reason
Auth/session/token lifecycle beyond using SL_API_KEY API exposes login, MFA, registration, activation, reset initiation, API-key creation, cookie token, and logout endpoints. The MCP server should not handle SimpleLogin passwords, MFA tokens, browser-session cookies, or API-key lifecycle. Users provide SL_API_KEY from SimpleLogin.
Payment/subscription management API exposes POST /api/apple/process_payment. Billing is high-impact account management and is not part of alias operations.
Sudo-mode/account-sensitive flows API exposes PATCH /api/sudo. Sudo mode requires password re-authentication and unlocks more sensitive account operations than this project should broker.
Account deletion API exposes DELETE /api/user. Permanent account destruction is intentionally excluded.
Password or account-email ownership changes outside supported mailbox settings The current API reference only documents auth/reset initiation and profile updates, not a general account email/password ownership API. Account ownership changes stay in the SimpleLogin web UI. mailbox_update only manages forwarding mailboxes.
Custom-domain create/delete and DNS verification The current API reference does not expose create, delete, DNS, MX, or verification endpoints. This is an upstream API limitation, not an MCP feature gap. Use the SimpleLogin web UI.

Deferred Areas To Revisit

  • PATCH /api/user_info: profile updates are documented but have no current alias-management need.
  • GET /api/export/data and GET /api/export/aliases: exported data can be large or sensitive, so support would need explicit response bounds and redaction expectations.
  • GET /api/phone/reservations/:reservation_id: phone reservations are outside the current email-alias workflows and need scope validation.
  • Notification mark-read endpoint path: current support uses the source-registered /read suffix while the upstream API reference lists the unsuffixed path.