Great messages.
Made to move.

What is live — and what is still being built.

LeadMASTER is the service at https://leadmaster.jelvan.pro. Production includes administrator sign-in, a protected email workspace, a dedicated receiving address, queued sending, AWS SES delivery updates, activity history and AI-assisted reply suggestions.

A message marked Sent means the sending service accepted it. Delivered means the recipient's mail service confirmed receipt. Neither guarantees inbox placement or reading.

Administrator sign-in flow.

1. GET /api/auth/config provides public configuration required by the human administrator sign-in page.
2. The human administrator sign-in page completes its required security verification.
3. POST /api/auth/login enforces same-origin, server-side security verification, the configured primary administrator identity and password. The primary administrator is not subject to IP- or email-based login throttles.
4. A successful password check creates a six-digit OTP, stores an HMAC hash in application database, and sends the OTP through LeadMASTER's configured email service. The code expires after 10 minutes and is single-use.
5. POST /api/auth/verify enforces OTP expiry, single use and a maximum of five incorrect attempts (without an IP-based verification throttle for the primary administrator), then creates a random 32-byte opaque session token.
6. Only the SHA-256 session-token hash is stored in application database. The browser receives an eight-hour HttpOnly; Secure; SameSite=Strict cookie.
7. GET /api/auth/session checks the application database session record. POST /api/auth/logout revokes the session and expires the cookie.

Security implementation notes. PBKDF2 password hashes are supported, but the current verifier still accepts the legacy secret-value format; do not claim PBKDF2-only enforcement. The session is opaque and database-backed, not a JWT. The application service binding named email providerSION_SECRET currently maps to the legacy secure configuration storage entry named ADMIN_JWT_TOKEN; the entry name does not mean the session is a JWT. The current login flow verifies the login human sign-in security verification action; an unused challenge-cookie helper in source is not a second active gateway challenge.

Human sign-in verification is not an agent authentication method. AI agents must not automate the human login flow or handle its challenge, password or OTP. Never place passwords, OTPs, API keys or webhook secrets in source control, browser storage or issue comments.

Send messages from your own account.

Create API keys from the protected App connections page after administrator sign-in. Keys are displayed once and stored as hashes. Use a separate key per application and environment.

• email:send — add one email to the sending list.
• email:read — read status for requests submitted with the same key.
• webhook:manage — manage connected services and inspect their delivery attempts.

Submit: POST /api/v1/accounts/{account_id}/emails with Authorization: Bearer lm_live_…, JSON content type and a stable Idempotency-Key (16–128 allowed characters). Body fields: to, subject, text, optional html and optional sender_name. One recipient is supported per API request. The sending address is generated from the account holder's full name under leadmaster.jelvan.pro; replies go to the registered account email.

curl -X POST https://leadmaster.jelvan.pro/api/v1/accounts/{account_id}/emails \
  -H "Authorization: Bearer $LEADMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-184-confirmation" \
  --data '{"to":"recipient@example.com","subject":"Order confirmation","text":"Your order has been received.","sender_name":"Jane Smith"}'

Read status: GET /api/v1/accounts/{account_id}/emails/{id} requires email:read and is scoped to the same API key.

• sending — waiting in the sending list or being processed.
• accepted — AWS SES accepted the SMTP submission; not proof of inbox delivery.
• failed — the message could not be sent.
• unknown — the final result could not be confirmed; reconcile before retrying.

Delivery updates may also include sent, delivered, bounced, complaint, delayed or rejected. The API supports one recipient per request and 30 requests per minute per API key. Dashboard bulk sending is a separate superadmin feature. Attachments, CC/BCC and multiple recipients are not part of this API contract.

Signed event callbacks.

Webhook management requires webhook:manage. Supported events are email.accepted, email.failed and email.unknown.

• POST /api/v1/accounts/{account_id}/webhooks — register an HTTPS callback and event list.
• GET /api/v1/accounts/{account_id}/webhooks — list subscriptions belonging to the API key.
• DELETE /api/v1/accounts/{account_id}/webhooks/{id} — revoke a subscription.
• GET /api/v1/accounts/{account_id}/webhooks/{id}/deliveries — inspect the latest 50 delivery attempts.

The create response reveals the whsec_… signing secret once. Store it server-side. Requests include LeadMASTER-Id, LeadMASTER-Timestamp and LeadMASTER-Signature: v1=<hex>. Verify HMAC-SHA256 over the exact bytes timestamp + "." + rawBody before parsing JSON; compare signatures in constant time, reject timestamps older than five minutes, and deduplicate by event ID.

Delivery limitations: one synchronous attempt per matching event, seven-second timeout, redirects disabled, and latest 50 attempts logged. Automatic retries, replay, dead-letter recovery, bounce/complaint events and guaranteed delivery are not implemented. URL checks do not pin DNS answers or fully prevent DNS rebinding; register only callback hosts you control and ensure they cannot resolve to private/internal addresses.

LeadMASTER service and maintenance.

Security configuration: credentials and signing keys are held server-side and are never exposed in this public guide. Do not rotate signing or encryption keys without a planned migration strategy.

Static assets: public/ is the canonical UI source. The production Worker serves its generated src/static-assets.mjs bundle. After changing public HTML, CSS, JavaScript or images, run npm run build:assets, review the generated bundle, test, then deploy the Worker. A Pages/preview copy is not the production source of truth.

Local checks: npm ci --ignore-scripts then npm test. Tests use mocked boundaries; they do not prove live sign-in, email inbox delivery, webhook callback receipt or inbox placement.

Deployment: confirm the intended production account, inspect the diff, run asset generation and tests, deploy with npx wrangler deploy, then verify the production URL, login config, protected routes and Worker version. Never deploy with missing bindings or placeholder secrets. See root HANDOVER.md for the complete release and rollback procedure.

Messages are received and sent through dedicated LeadMASTER services.

Incoming: send mail to inbound@inbound.leadmaster.jelvan.pro. A separate receiving Worker stores the original email and its message details for the superadmin Inbox. This exact address has its own MX records and routing rule. Existing personal and Operava forwarding rules are unchanged. Attachments remain in the downloadable original email; individual attachment extraction is not yet available.

Outgoing: dashboard messages and account API messages enter a dedicated sending queue. The queue processes messages automatically; delivery timing may vary. The dashboard accepts up to 500 unique recipients in one bulk request; the account API remains one recipient per request. Login codes and security notices use the same LeadMASTER-branded AWS SES SMTP sender directly so sign-in is not delayed by bulk sending.

Delivery updates: a separate AWS SES configuration set sends signed status events to LeadMASTER. The dashboard can show Sent, Delivered, Delayed, Could not deliver, Marked as unwanted and Not sent. Sent means AWS SES accepted the message; Delivered means the recipient's mail service confirmed receipt. Neither guarantees inbox placement or reading.

Reply suggestions: select Suggest a reply on an incoming message. The reply assistant checks related sent and received messages when available, then prepares an editable draft. A person must review and send it; suggestions are never sent automatically.

Notifications: new messages and delivery updates appear while the dashboard is open. Separate LeadMASTER sounds play for incoming, sent, deleted and confirmed actions. Device notifications can be enabled in the dashboard; background push while it is closed is not configured.

Experimental, read-only MCP prototype.

The repository contains an experimental MCP server with get_email_capabilities and validate_email. It is not mounted by the production LeadMASTER service and has no public endpoint, client registration, OAuth flow or email-send tool. Do not tell users to connect to /mcp. Any future MCP release requires independent authorization, token lifecycle, rate limits, runtime compatibility and security review. MCP must not bypass the developer email API or its safeguards.

Every integration belongs to an account.

Agents must use the signed-in user's own LeadMASTER account context. An authorized user creates an API key inside their account; that key is bound to that account and cannot access another account's API requests, webhooks, delivery history or configuration. Never use a platform-wide, operator, developer or another user's credential.

Discover the account: the signed-in workspace session and API Keys page show the account's current identifier and generated API base URL. A newly generated key response also returns the account's own email and webhook endpoints. Agents must use that returned account information; never guess, enumerate or substitute an account ID.

Account information: GET /api/v1/accounts/{account_id} with that account's Bearer API key returns the account's current name, identifier and owned endpoint paths. A key from another account is rejected.

Machine-readable instructions: Open llms.txt · Open robots.txt. These instructions describe supported features, account-specific REST routes, webhook verification, security boundaries and MCP status.

Send email: POST /api/v1/accounts/{account_id}/emails. Use email:send, a server-side API key, JSON and a stable idempotency key. GET /api/v1/accounts/{account_id}/emails/{id} requires email:read and returns only requests created by the same key and account.

curl -X POST "https://leadmaster.jelvan.pro/api/v1/accounts/$LEADMASTER_ACCOUNT_ID/emails" \
  -H "Authorization: Bearer $LEADMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-184-confirmation" \
  --data '{"to":"recipient@example.com","subject":"Order confirmation","text":"Your order has been received."}'

Webhooks: create, list, revoke and inspect only within /api/v1/accounts/{account_id}/webhooks using webhook:manage. Each webhook is owned by the account and API key that created it. Store its one-time signing secret server-side. Verify the HMAC signature, timestamp and event ID before processing.

Human sign-in security: human login verification, passwords and email OTP are never agent credentials. Agents must not access, scrape, solve, bypass or request challenge tokens from the human login page.

MCP: no MCP service is available in production. Do not connect to /mcp or claim it is active. Any future MCP connection must be authenticated and scoped to the same user's account, with no platform-wide access or cross-account tools.

Authorization: obtain explicit user approval before sending, validate recipient authorization, keep credentials in a secure server-side store, redact logs, use least privilege, and report provider acceptance separately from inbox delivery.

Non-negotiable handling rules.

• Never commit secrets, access tokens, OTP values, API keys, webhook signing secrets or personal email contents.
• Keep API keys and webhook signing secrets in server-side secret storage; redact authorization and signature headers from logs.
• Use least-privilege API scopes and separate keys by environment.
• Keep authentication fail-closed. Do not bypass human sign-in security verification, password checks, OTP expiry, attempt caps, origin checks or session validation to make a test pass.
• Do not log full recipient content or expose application database records outside the authorized operator surface.
• Document data retention, privacy and legal review requirements before expanding campaigns or audience features.

What must happen before calling the product complete.

• Run a real administrator login and OTP receipt test in a browser.
• Confirm human sign-in security verification Siteverify succeeds with the production widget/secret pair; never expose the secret in logs.
• Run a controlled email provider email test to an approved mailbox and record the submission outcome separately from inbox delivery.
• Create and revoke a scoped API key; verify least-privilege enforcement.
• Send a controlled API email with idempotency and inspect its application database status.
• Register a controlled HTTPS webhook, validate HMAC, inspect delivery history, and test invalid/stale/duplicate signatures.
• Complete dashboard data, email activity, templates, audiences, campaigns, queue recovery and operational monitoring before marking those product features complete.
• Review privacy, terms, retention, suppression and consent requirements before campaign release.