wyre-ai/msp-claude-plugins/customers-and-domains

Mailprotector Customers & Domains

Overview

Customers are the client organizations under the MSP's reseller; domains hang off customers and carry the actual mail routing. Onboarding a client is: create the customer, create the domain, verify it, then point mail flow at it (destinations for inbound delivery, sources for outbound authorization).

Key Concepts

Common Workflows

Customer lifecycle

1. Create: POST /resellers/{reseller_id}/customers with

{"name": "...", "email": "contact@..."} → 201 with the new id (tool: mailprotector_customers_create).

1. Read: mailprotector_customers_list (from the bound reseller) and

mailprotector_customers_get.

1. Edit: PUT /customers/{customer_id} with name/email (via

mailprotector_execute_tool).

1. Delete: DELETE /customers/{customer_id} — **removes all domains and

users under the customer**. Irreversible; confirm explicitly.

Domain creation and verification

1. POST /customers/{customer_id}/domains with {"name": "domain.com"}

(tool: mailprotector_domains_create).

1. The response is 201 with domain_status Pending and a

verification_token. Mail is not filtered for a Pending domain.

1. Surface the verification_token to the operator — ownership is

proven with it before Mailprotector activates the domain. Re-fetch the domain (mailprotector_domains_get) to watch for domain_status id 2 (Active) / verification_token: null.

1. After activation, add email destinations and sources (below), then

repoint MX records.

Domain aliases

POST /domains/{domain_id}/aliases with {"name": "domain-alias.com"}. The alias appears in GET /domains/{domain_id}/aliases with parent set to the primary domain and its own Pending status + token. Every user under the primary domain automatically accepts mail at the alias domain (user email_addresses extend to each alias), so create aliases before bulk-creating users when you want alias addresses generated.

Moving a domain between customers

POST /domains/{domain_id}/move with {"customer_id": 16998} — only within the same reseller. User groups, users, and rules travel with the domain. Use this to fix a domain created under the wrong customer instead of delete + recreate (which would destroy users).

Mail routing

• Destinations: GET/POST /domains/{domain_id}/email_destinations

with {"address": "mail.domain.com"} — address may be a domain, hostname, or IP. priority is assigned in creation order (0 first); lower priority is tried first.

• Sources: GET/POST /domains/{domain_id}/email_sources with

{"address": "192.0.2.1"} — the IPs allowed to relay outbound.

• Both also exist at user-group scope

(/user_groups/{id}/email_destinations and _sources) for groups that deliver somewhere other than the domain default — the MCP tool takes scope: domain|user_group.

Gotchas

• Pending domains silently drop the onboarding. Everything after

domain creation (groups, users, MX cutover) can proceed, but no mail is filtered until the domain is verified. Always report the verification state, and never call an onboarding done while domain_status is Pending.

• Customer delete cascades. Domains and users go with it. Prefer

domain move or user-group edits for restructuring.

• `PUT /domains/{domain_id}` is for flags like

address_discovery_enabled — you cannot rename a domain; create the correct one and move users.

• Customer managers (POST /customers/{customer_id}/managers)

create console logins, but roles cannot be assigned via the API — a new manager has an empty roles array until someone assigns the role in the console. Listing customer managers excludes reseller-level managers.

• Statements (GET /resellers/{id}/statements,

GET /customers/{id}/statements) are billing history (amount, currency, statement_status, billing/due dates) — read them for reconciliation, not for provisioning state.

Related Skills

• users-and-groups — the next onboarding step after the domain is Active
• api-patterns — hierarchy, auth, and error handling