Tool catalog

Search 27 supported tools across five focused areas by name, purpose, or input, or narrow the results by category and behavior. Each tool explains its inputs, bounds, account impact, and documented output. Every tool name is a permanent link you can bookmark or share, and every example uses placeholder values rather than credentials or account data.

“Destructive” identifies writes that can interrupt mail delivery as well as irreversible deletion. Permanent delete tools also require explicit confirmation. “Idempotent” means repeating a call has the same intended effect; check the first result before retrying a tool marked “Not idempotent.”

This page stays aligned with the server by reading tool names, descriptions, schemas, annotations, and bounds from the project’s canonical catalog and registered definitions. Tests compare that catalog with the actual tool registration rather than maintaining a second hand-written reference.

Aliases

Find, create, tune, audit, pause, and safely remove aliases.

Example prompt: “List my disabled aliases and include their notes. Do not make any changes.”

10 tools

• alias_list#

  Read onlyIdempotent

  List aliases with optional state and text filters.

  Usage and constraints: List the user's SimpleLogin email aliases, 20 per page. Use page_id for pagination (starts at 0). Optionally filter to only enabled, only disabled, or only pinned aliases, and/or search by a free-text query matching the alias email, note, or name.

  Inputs3 optional

  page_idOptional field

  Zero-based page number; 20 aliases per page. Defaults to 0.

  filterOptional field

  Return only aliases in this state. Mutually exclusive.

  queryOptional field

  Free-text search over alias email, note, and name.

  Bounds

  page_id, 20 aliases per page

  Output

  { aliases }

• alias_get#

  Read onlyIdempotent

  Get full details for one alias by id.

  Usage and constraints: Get full details of a single SimpleLogin alias by its numeric id, including note, mailboxes, enabled/pinned state, PGP status, and activity counters.

  Inputs1 required

  alias_idRequired field

  Numeric id of the alias to fetch.

  Bounds

  single alias

  Output

  alias object

• alias_activity_list#

  Read onlyIdempotent

  List forward, reply, block, and bounce activity for one alias.

  Usage and constraints: List the forward/reply/block activity history for a single SimpleLogin alias, 20 entries per page (most recent first). Each entry has an action (forward, reply, block, or bounced), the from/to addresses, a Unix timestamp, and the reverse-alias address for replies. Use page_id for pagination (starts at 0); the per-page cap keeps responses bounded, so page through rather than expecting the full history in one call.

  Inputs1 required, 1 optional

  alias_idRequired field

  Numeric id of the alias whose activity to list.

  page_idOptional field

  Zero-based page number; 20 entries per page. Defaults to 0.

  Bounds

  page_id, 20 activity entries per page

  Output

  { activities }

• alias_create_random#

  Writes dataNot idempotent

  Create a random alias using uuid, word, or account-default style.

  Usage and constraints: Create a new random SimpleLogin alias with a system-generated address. mode "uuid" produces a random-string address; "word" produces a word-based one; omit to use the account default. Optionally attach a note and the website hostname the alias is for.

  Inputs3 optional

  modeOptional field

  Address style: "uuid" or "word". Defaults to the account setting.

  noteOptional field

  Optional note stored on the alias.

  hostnameOptional field

  Website hostname this alias is created for (context only).

  Bounds

  single alias mutation

  Output

  created alias object

• alias_create_custom#

  Writes dataNot idempotent

  Create a custom alias from a prefix, signed suffix, and mailboxes.

  Usage and constraints: Create a custom SimpleLogin alias with a chosen prefix and suffix. First call alias_options_get to obtain a valid signed_suffix and confirm can_create is true, then pass that exact signed_suffix here with the desired alias_prefix and the mailbox_ids (from mailbox_list) that should receive mail. note and name are optional.

  Inputs3 required, 3 optional

  alias_prefixRequired field

  The local part chosen by the user (text before the suffix).

  signed_suffixRequired field

  A signed_suffix value returned verbatim by alias_options_get.

  mailbox_idsRequired field

  Ids of mailboxes that will own and receive mail for this alias.

  noteOptional field

  Optional note stored on the alias.

  nameOptional field

  Optional display name for the alias.

  hostnameOptional field

  Website hostname this alias is created for (context only).

  Bounds

  single alias mutation

  Output

  created alias object

• alias_update#

  Writes dataIdempotentDestructive

  Update alias note, name, mailboxes, PGP, or pinned state.

  Usage and constraints: Update an existing alias. Provide at least one field to change: note, display name, the owning mailbox (mailbox_id) or full mailbox set (mailbox_ids), whether PGP is disabled, and whether the alias is pinned. Only the provided fields change. mailbox_id and mailbox_ids are mutually exclusive, and a call that changes nothing is rejected without contacting SimpleLogin. Replacing mailboxes can stop future mail from landing in removed mailboxes.

  Inputs1 required, 6 optional

  alias_idRequired field

  Numeric id of the alias to update.

  noteOptional field

  Replace the alias note.

  nameOptional field

  Replace the alias display name.

  mailbox_idOptional field

  Set a single owning mailbox by id, replacing current alias mailbox routing.

  mailbox_idsOptional field

  Replace the full set of owning mailboxes by id.

  disable_pgpOptional field

  Disable PGP on this alias even if a mailbox supports it.

  pinnedOptional field

  Pin or unpin the alias.

  Bounds

  single alias mutation

  Output

  { ok: true }

• alias_delete#

  Writes dataNot idempotentDestructive

  Permanently delete an alias after confirm=true.

  Usage and constraints: Permanently delete a SimpleLogin alias by id. This cannot be undone; mail sent to the address afterwards is rejected. Prefer alias_set_enabled with enabled=false to merely disable an alias. Requires confirm=true as an explicit acknowledgement of the deletion.

  Inputs2 required

  alias_idRequired field

  Numeric id of the alias to delete.

  confirmRequired field

  Must be set to true to confirm this permanent, irreversible deletion.

  Bounds

  single irreversible deletion

  Output

  { deleted }

• alias_set_enabled#

  Writes dataIdempotentDestructive

  Set an alias enabled or disabled without deleting it.

  Usage and constraints: Set a SimpleLogin alias to a specific enabled state. Pass enabled=true to enable or enabled=false to disable. A disabled alias silently blocks incoming mail without being deleted. Idempotent: setting the state it is already in changes nothing. Returns the resulting enabled state.

  Inputs2 required

  alias_idRequired field

  Numeric id of the alias to update.

  enabledRequired field

  Desired state: true to enable the alias, false to disable it.

  Bounds

  single alias state mutation

  Output

  { enabled }

• alias_options_get#

  Read onlyIdempotent

  Get custom-alias creation options and signed suffixes.

  Usage and constraints: Fetch the options needed to create a custom alias: whether the user can create more aliases (can_create), a prefix suggestion, and the list of available suffixes — each with the signed_suffix required by alias_create_custom. Pass the target website hostname to tailor the suggestion.

  Inputs1 optional

  hostnameOptional field

  Website hostname to tailor the prefix suggestion.

  Bounds

  small account option set

  Output

  { can_create, prefix_suggestion, suffixes, recommendation? }

• alias_domains_list#

  Read onlyIdempotent

  List domains usable for alias creation.

  Usage and constraints: List the email domains available for creating aliases on this account, each flagged is_custom (a user-owned domain) or not (a SimpleLogin public domain).

  Inputsnone

  This tool takes no input arguments.

  Bounds

  small account domain set

  Output

  domain array

Contacts

Create reverse aliases and control who can forward mail.

Example prompt: “For alias ID 42, list its contacts and show which ones are blocked.”

4 tools

• contact_list#

  Read onlyIdempotent

  List contacts and reverse aliases for one alias.

  Usage and constraints: List the contacts (reverse aliases) for a single SimpleLogin alias, 20 per page. Each contact is an address the alias can correspond with: it carries the contact email, a reverse_alias_address the user sends to in order to reach that contact from the alias, whether forwarding from it is blocked (block_forward), and when it was last emailed. Use page_id for pagination (starts at 0).

  Inputs1 required, 1 optional

  alias_idRequired field

  Numeric id of the alias whose contacts to list.

  page_idOptional field

  Zero-based page number; 20 contacts per page. Defaults to 0.

  Bounds

  page_id, 20 contacts per page

  Output

  { contacts }

• contact_create#

  Writes dataNot idempotent

  Create or reuse a reverse alias for a recipient.

  Usage and constraints: Create a contact (reverse alias) on an alias so the user can send mail from the alias to that contact while keeping their real mailbox hidden. Pass the recipient as a bare address ("[email protected]") or an RFC-5322 display form ("First Last <[email protected]>"). The response includes the reverse_alias_address to send to; existed=true means the contact already existed and nothing was created. Creating reverse aliases may require a premium SimpleLogin plan.

  Inputs2 required

  alias_idRequired field

  Numeric id of the alias to create the contact on.

  contactRequired field

  Recipient address, optionally with a display name: "Name <[email protected]>".

  Bounds

  single contact mutation

  Output

  contact object or { existed: true }

• contact_set_blocked#

  Writes dataIdempotentDestructive

  Set whether forwarding from a contact is blocked.

  Usage and constraints: Set whether forwarding from a contact to its alias is blocked. Pass blocked=true to stop mail from that contact reaching the user, or blocked=false to allow it again. Requires the alias_id (the contact belongs to it) so the current state can be read first: setting the state it is already in is a no-op. Returns the resulting block_forward state.

  Inputs3 required

  alias_idRequired field

  Numeric id of the alias the contact belongs to.

  contact_idRequired field

  Numeric id of the contact to block or unblock.

  blockedRequired field

  Desired state: true to block forwarding from the contact, false to allow it.

  Bounds

  single contact state mutation

  Output

  { block_forward }

• contact_delete#

  Writes dataNot idempotentDestructive

  Permanently delete a contact after confirm=true.

  Usage and constraints: Permanently delete a contact (reverse alias) by its numeric id. This cannot be undone; the reverse-alias address stops working and the correspondence history for that contact is removed. To merely stop receiving mail from the contact, prefer contact_set_blocked with blocked=true instead. Requires confirm=true as an explicit acknowledgement.

  Inputs2 required

  contact_idRequired field

  Numeric id of the contact to delete.

  confirmRequired field

  Must be set to true to confirm this permanent, irreversible deletion.

  Bounds

  single irreversible deletion

  Output

  { deleted }

Mailboxes

Manage verified destinations, defaults, and explicit transfers.

Example prompt: “List my mailboxes and identify which verified mailbox is the default.”

4 tools

• mailbox_list#

  Read onlyIdempotent

  List account mailboxes and verification/default state.

  Usage and constraints: List the account's mailboxes (verified and unverified), each with its id, email, default flag, alias count, and verification status. Use the returned ids as mailbox_ids when creating or updating aliases.

  Inputsnone

  This tool takes no input arguments.

  Bounds

  account mailbox set

  Output

  { mailboxes }

• mailbox_create#

  Writes dataNot idempotent

  Add a mailbox and send its verification email.

  Usage and constraints: Add a new mailbox (a real email address that receives alias mail) to the account. SimpleLogin sends a verification email to the address; the mailbox starts unverified and cannot own aliases or become the default until the user clicks that link. Check mailbox_list to see when verified turns true. Additional mailboxes may require a premium SimpleLogin plan.

  Inputs1 required

  emailRequired field

  Address of the new mailbox; it receives the verification email.

  Bounds

  single mailbox mutation

  Output

  created mailbox object

• mailbox_update#

  Writes dataNot idempotent

  Set a default mailbox, start an email change, or cancel one.

  Usage and constraints: Update a mailbox. Provide at least one change: set_default=true makes this mailbox the account default (it must be verified); email starts an address change that stays pending until the new address is verified via the email SimpleLogin sends it; cancel_email_change=true aborts such a pending change. set_default and cancel_email_change only accept true (a mailbox stops being default only when another is promoted, and a pending change is cancelled rather than toggled back), email and cancel_email_change are mutually exclusive, and a call that changes nothing is rejected without contacting SimpleLogin.

  Inputs1 required, 3 optional

  mailbox_idRequired field

  Numeric id of the mailbox to update.

  emailOptional field

  New address for the mailbox; the change is pending until verified.

  set_defaultOptional field

  Make this mailbox the account default. The mailbox must be verified.

  cancel_email_changeOptional field

  Cancel a pending email change on this mailbox.

  Bounds

  single mailbox mutation

  Output

  { updated }

• mailbox_delete#

  Writes dataNot idempotentDestructive

  Permanently delete a mailbox after explicit alias handling.

  Usage and constraints: Permanently delete a mailbox. The aliases it owns must be dealt with explicitly: pass transfer_aliases_to (the id of a different, verified mailbox from mailbox_list) to move them, or delete_aliases=true to delete them with the mailbox; exactly one of the two is required. The default mailbox cannot be deleted; promote another mailbox first via mailbox_update with set_default=true. This cannot be undone. Requires confirm=true as an explicit acknowledgement of the deletion.

  Inputs2 required, 2 optional

  mailbox_idRequired field

  Numeric id of the mailbox to delete.

  transfer_aliases_toOptional field

  Id of a different verified mailbox that takes over the owned aliases.

  delete_aliasesOptional field

  Explicitly acknowledge that the owned aliases are deleted with the mailbox.

  confirmRequired field

  Must be set to true to confirm this permanent, irreversible deletion.

  Bounds

  single irreversible deletion

  Output

  { deleted }

Custom domains

Inspect domains, update routing, and review deleted-alias trash.

Example prompt: “List my custom domains and summarize their settings. Do not make any changes.”

3 tools

• custom_domain_list#

  Read onlyIdempotent

  List custom domains and their settings.

  Usage and constraints: List the account's custom domains, each with its id, domain name, verification status, alias count, catch-all and random-prefix-generation flags, display name, and the mailboxes that receive its mail. Use the returned ids with custom_domain_update and custom_domain_trash_list.

  Inputsnone

  This tool takes no input arguments.

  Bounds

  account custom-domain set

  Output

  { custom_domains }

• custom_domain_update#

  Writes dataIdempotentDestructive

  Update supported custom-domain routing and display settings.

  Usage and constraints: Update a custom domain. Provide at least one change: catch_all toggles whether mail to any unknown address on the domain auto-creates an alias; random_prefix_generation toggles random prefixes for on-the-fly aliases; name sets the display name used as the From name on the domain (null clears it); mailbox_ids replaces the full set of mailboxes receiving the domain's mail (1 to 20 ids from mailbox_list). Only the provided fields change, a call that changes nothing is rejected without contacting SimpleLogin, and the updated domain is returned. Disabling catch_all or replacing mailbox_ids can stop future delivery for affected domain addresses.

  Inputs1 required, 4 optional

  custom_domain_idRequired field

  Numeric id of the custom domain to update.

  catch_allOptional field

  Auto-create an alias when mail arrives for an unknown address on the domain; false disables that catch-all routing.

  random_prefix_generationOptional field

  Use a random prefix instead of the address when auto-creating aliases.

  nameOptional field

  Display name used as the From name for the domain's aliases; null clears it.

  mailbox_idsOptional field

  Replace the full set of mailboxes that receive the domain's mail, by id.

  Bounds

  single custom-domain mutation

  Output

  { custom_domain }

• custom_domain_trash_list#

  Read onlyIdempotent

  List deleted aliases remembered for one custom domain.

  Usage and constraints: List a custom domain's deleted aliases (its trash), each with the alias address and a Unix deletion timestamp. Deleted addresses on a custom domain are remembered so they are not silently recreated by catch-all; use this to audit what was removed or to check whether an address is in the trash before reusing it. SimpleLogin exposes this endpoint without server-side pagination, so the MCP result is locally paged with page_id (starts at 0) and limit (defaults to 100, max 500).

  Inputs1 required, 2 optional

  custom_domain_idRequired field

  Numeric id of the custom domain whose trash to list.

  page_idOptional field

  Zero-based page number; defaults to 0.

  limitOptional field

  Maximum deleted aliases to return; defaults to 100.

  Bounds

  page_id and limit, defaults to page 0 and 100 aliases per page, max 500

  Output

  { aliases, page_id, limit, returned, total, more }

Account

Check account details, stats, notifications, and alias settings.

Example prompt: “Show my lifetime alias, forwarded, replied, and blocked email totals.”

6 tools

• account_get_info#

  Read onlyIdempotent

  Get user info and validate the configured API key.

  Usage and constraints: Return the authenticated SimpleLogin user's info: name, email, premium/trial status, and free-plan alias limit. Useful as a quick check that the configured API key is valid.

  Inputsnone

  This tool takes no input arguments.

  Bounds

  single account object

  Output

  user info object

• account_get_stats#

  Read onlyIdempotent

  Get lifetime account counters.

  Usage and constraints: Return the account's lifetime counters: number of aliases (nb_alias) and number of emails forwarded (nb_forward), replied to (nb_reply), and blocked (nb_block) across all aliases. Use alias_activity_list for the per-alias breakdown behind these totals.

  Inputsnone

  This tool takes no input arguments.

  Bounds

  single stats object

  Output

  stats object

• notification_list#

  Read onlyIdempotent

  List account notifications unread first.

  Usage and constraints: List account notifications from SimpleLogin (announcements, warnings such as a mailbox bouncing, etc.), 20 per page, unread first then newest first. Each entry has an id, nullable title, HTML message, read flag, and a human-readable created_at. Use page_id for pagination (starts at 0); more=true means another page exists. Mark entries handled with notification_mark_read.

  Inputs1 optional

  page_idOptional field

  Zero-based page number; 20 notifications per page. Defaults to 0.

  Bounds

  page_id, 20 notifications per page

  Output

  { more, notifications }

• notification_mark_read#

  Writes dataIdempotent

  Mark one notification as read.

  Usage and constraints: Mark a single account notification as read, by the id from notification_list. Idempotent: marking an already-read notification succeeds and changes nothing. Notifications cannot be marked unread or deleted via the API.

  Inputs1 required

  notification_idRequired field

  Numeric id of the notification to mark as read.

  Bounds

  single notification mutation

  Output

  { done }

• settings_get#

  Read onlyIdempotent

  Get account-wide alias settings.

  Usage and constraints: Return the account-wide alias settings: alias_generator (random-alias address style), notification (email notifications on/off), random_alias_default_domain (domain used for random aliases), sender_format (how the original sender appears in forwarded mail), and random_alias_suffix (suffix style for random and on-the-fly aliases). Change them with settings_update.

  Inputsnone

  This tool takes no input arguments.

  Bounds

  single settings object

  Output

  settings object

• settings_update#

  Writes dataIdempotent

  Update supported account-wide alias settings.

  Usage and constraints: Update the account-wide alias settings; only the provided fields change and the resulting settings are returned. Deliberately limited to the five documented alias-behavior fields: account email, password, payment, and deletion are out of scope and stay in the web UI. random_alias_default_domain must be a domain from alias_domains_list (premium-only domains need a premium account; a custom domain must be yours and verified). A call that changes nothing is rejected without contacting SimpleLogin.

  Inputs5 optional

  alias_generatorOptional field

  Address style for random aliases: "word" (word-based) or "uuid".

  notificationOptional field

  Whether SimpleLogin sends the user email notifications.

  random_alias_default_domainOptional field

  Domain used for random aliases; one of the domains from alias_domains_list.

  sender_formatOptional field

  How the original sender appears in forwarded mail. For [email protected] ("John Wick"): AT = "John Wick - john at wick.com", A = "John Wick - john(a)wick.com", NAME_ONLY = "John Wick", AT_ONLY = "john at wick.com", NO_NAME = no sender shown.

  random_alias_suffixOptional field

  Suffix style for random and on-the-fly aliases: "word" (dictionary word) or "random_string".

  Bounds

  single settings mutation

  Output

  updated settings object