@rapidmx/crm-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,382 @@
+# Mozilla Public License Version 2.0
+
+1. Definitions
+
+---
+
+1.1. "Contributor"
+means each individual or legal entity that creates, contributes to
+the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+means the combination of the Contributions of others (if any) used
+by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+means Source Code Form to which the initial Contributor has attached
+the notice in Exhibit A, the Executable Form of such Source Code
+Form, and Modifications of such Source Code Form, in each case
+including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+means a work that combines Covered Software with other material, in
+a separate file or files, that is not Covered Software.
+
+1.8. "License"
+means this document.
+
+1.9. "Licensable"
+means having the right to grant, to the maximum extent possible,
+whether at the time of the initial grant or subsequently, any and
+all of the rights conveyed by this License.
+
+1.10. "Modifications"
+means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+means any patent claim(s), including without limitation, method,
+process, and apparatus claims, in any patent Licensable by such
+Contributor that would be infringed, but for the grant of the
+License, by the making, using, selling, offering for sale, having
+made, import, or transfer of either its Contributions or its
+Contributor Version.
+
+1.12. "Secondary License"
+means either the GNU General Public License, Version 2.0, the GNU
+Lesser General Public License, Version 2.1, the GNU Affero General
+Public License, Version 3.0, or any later versions of those
+licenses.
+
+1.13. "Source Code Form"
+means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+means an individual or a legal entity exercising rights under this
+License. For legal entities, "You" includes any entity that
+controls, is controlled by, or is under common control with You. For
+purposes of this definition, "control" means (a) the power, direct
+or indirect, to cause the direction or management of such entity,
+whether by contract or otherwise, or (b) ownership of more than
+fifty percent (50%) of the outstanding shares or beneficial
+ownership of such entity.
+
+2. License Grants and Conditions
+
+---
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+Licensable by such Contributor to use, reproduce, make available,
+modify, display, perform, distribute, and otherwise exploit its
+Contributions, either on an unmodified basis, with Modifications, or
+as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+for sale, have made, import, and otherwise transfer either its
+Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+or
+
+(b) for infringements caused by: (i) Your and any other third party's
+modifications of Covered Software, or (ii) the combination of its
+Contributions with other software (except as part of its Contributor
+Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+
+---
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+Form, as described in Section 3.1, and You must inform recipients of
+the Executable Form how they can obtain a copy of such Source Code
+Form by reasonable means in a timely manner, at a charge no more
+than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+License, or sublicense it under different terms, provided that the
+license for the Executable Form does not attempt to limit or alter
+the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+
+---
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+
+---
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+---
+
+-                                                                      *
+-   6. Disclaimer of Warranty \*
+- ------------------------- \*
+-                                                                      *
+- Covered Software is provided under this License on an "as is" \*
+- basis, without warranty of any kind, either expressed, implied, or \*
+- statutory, including, without limitation, warranties that the \*
+- Covered Software is free of defects, merchantable, fit for a \*
+- particular purpose or non-infringing. The entire risk as to the \*
+- quality and performance of the Covered Software is with You. \*
+- Should any Covered Software prove defective in any respect, You \*
+- (not any Contributor) assume the cost of any necessary servicing, \*
+- repair, or correction. This disclaimer of warranty constitutes an \*
+- essential part of this License. No use of any Covered Software is \*
+- authorized under this License except under this disclaimer. \*
+-                                                                      *
+
+---
+
+---
+
+-                                                                      *
+-   7. Limitation of Liability \*
+- -------------------------- \*
+-                                                                      *
+- Under no circumstances and under no legal theory, whether tort \*
+- (including negligence), contract, or otherwise, shall any \*
+- Contributor, or anyone who distributes Covered Software as \*
+- permitted above, be liable to You for any direct, indirect, \*
+- special, incidental, or consequential damages of any character \*
+- including, without limitation, damages for lost profits, loss of \*
+- goodwill, work stoppage, computer failure or malfunction, or any \*
+- and all other commercial damages or losses, even if such party \*
+- shall have been informed of the possibility of such damages. This \*
+- limitation of liability shall not apply to liability for death or \*
+- personal injury resulting from such party's negligence to the \*
+- extent applicable law prohibits such limitation. Some \*
+- jurisdictions do not allow the exclusion or limitation of \*
+- incidental or consequential damages, so this exclusion and \*
+- limitation may not apply to You. \*
+-                                                                      *
+
+---
+
+8. Litigation
+
+---
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+
+---
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+
+---
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+## Exhibit A - Source Code Form License Notice
+
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+## Exhibit B - "Incompatible With Secondary Licenses" Notice
+
+This Source Code Form is "Incompatible With Secondary Licenses", as
+defined by the Mozilla Public License, v. 2.0.

package/README.md

@@ -0,0 +1,210 @@
+# @rapidmx/crm-plugin
+
+A customer relationship management platform for [RapidMX](https://github.com/rapidmx/server), installed as a server plugin.
+
+This first release covers the CRM core:
+
+- **Workspaces** shared by a team, each member an owner, admin, editor or viewer. Members are added by the address of a mailbox
+  they own.
+- **Contacts and companies** with their own fields, tags and **custom properties** (text, number, date, yes/no, dropdown and
+  multiple choice). A new contact is linked to the company whose web domain matches its email address.
+- **Filtered search** across fields, tags and custom properties, with all/any conditions, a quick text search, sorting and paging.
+- **Bulk actions** (tag, untag, set owner, delete) and **CSV export** of anything a search matches.
+- **Notes, tasks and an activity timeline** on every contact and company.
+- **CSV import** of contacts and companies, with a suggested column mapping, imported in the background.
+- **Send-as addresses**: the mailboxes a workspace will send marketing mail from and receive replies in.
+- **Mailing lists and subscriptions**, with the consent behind each (when, how, from what address), and list membership as a
+  filter.
+- **Signup forms** at `/f/<form>`, linkable or embeddable in another site, with optional **double opt-in** by email.
+- **A preference center** at `/subscriptions/<token>` where a subscriber chooses their lists or unsubscribes from all email, and
+  **one-click unsubscribe** links (RFC 8058) - no account needed, the links carry signed tokens.
+- **A suppression list** of addresses never to email.
+- **Email templates** built in a **drag-and-drop designer**. It offers:
+  - sections of up to four columns;
+  - heading, text, image, button, divider, spacer, social, footer and hand-written HTML blocks;
+  - inline text editing and a theme;
+  - merge tags such as `{{ contact.first_name }}` and custom properties;
+  - undo and redo, and reusable saved blocks;
+  - a preview for a sample reader or any contact, at desktop or phone width or as plain text;
+  - test sends.
+
+  Templates are laid out with MJML and filled in with Liquid; merged values are HTML-escaped.
+
+- **Campaigns** to the subscribers of chosen lists, less those of excluded lists. They skip addresses that are suppressed,
+  unsubscribed, bounced or complained. A campaign can be sent now or scheduled, paused, resumed and cancelled. Before sending, a
+  checklist says what's missing: a sender, a list, an email with an unsubscribe link, or your postal address.
+- **A/B tests**: up to four variants, each with its own subject line or template. They are tried on part of the audience, and the
+  variant with the best open, click or reply rate after a set number of hours goes to everyone else.
+- **Deliverability headers** on every campaign message:
+  - `List-Unsubscribe` with RFC 8058 one-click, which Gmail and Yahoo require of bulk senders;
+  - `List-Id`, `Precedence: bulk` and a `Feedback-ID`;
+  - a per-message bounce address (VERP).
+
+  Sending is throttled deployment-wide.
+- **Engagement tracking**:
+  - Opens are tracked with an invisible image, and clicks through signed redirects that can only go where the email's link went.
+  - Replies, bounces and spam complaints are learned from the sender's mailbox.
+  - Opens and clicks by mail scanners are told apart from people's.
+  - A hard bounce or a complaint suppresses the address.
+  - Everything lands on the contact's timeline and in the campaign's report: rates, links by clicks, variants, and a filterable
+    recipients list.
+
+- **Segments**: named groups of contacts defined by a filter.
+  - A dynamic segment keeps up with its filter by itself; a static one is a snapshot, refreshed by hand.
+  - Segments are a contact filter field of their own.
+  - A campaign can go only to the subscribers in some segments, or leave the members of others out.
+- **Lead scoring**: a contact's score is the sum of its workspace's rules.
+  - A property rule gives points to the contacts matching its filter.
+  - An activity rule gives points for each time a contact opened, clicked, replied, bounced, submitted a form, subscribed or
+    unsubscribed, optionally within the last N days and up to a limit.
+  - Scores update in the background, or on demand.
+
+- **Automations**: workflows that react to what contacts do.
+  - **Triggers:** subscribing or unsubscribing, submitting a form, entering or leaving a segment, being created or changed,
+    opening, clicking, replying to or bouncing an email, a deal being created, moved, won or lost, an event your own systems
+    report through the integration API (optionally by name), or being put in by hand. A trigger can also take a contact filter.
+  - **Date triggers:** a contact's date property (a birthday, a renewal) or when they were added or last engaged - on the day or
+    a number of days before or after it, every year or once, from a chosen hour in the workspace's time zone. A "Birthday
+    greeting" starting point sets one up.
+  - **Steps:** waiting a while; waiting for an earlier email to be opened, clicked or replied to (with a timeout, and a branch
+    for each outcome); if/else on a contact filter; random splits; sending an email; setting a field; adding or removing a tag;
+    subscribing or unsubscribing; creating a task; notifying a member; putting the contact into another automation; posting to
+    a webhook; ending.
+  - **Editing:** a branching editor with ready-made starting points ("welcome, then follow up if there's no reply", welcome
+    series, form follow-up, win back). A publish checks the whole flow first.
+  - **Running:** contacts go through the version they entered. A goal takes them out early, and a re-entry rule decides whether
+    they can go through again. Each step shows live numbers, and every contact's run can be looked at or stopped.
+
+- **Sales pipelines and deals**:
+  - Pipelines are made of stages, each with a win probability, a kind (open, won or lost) and optional "rotting" days. A workspace
+    gets a default "Sales" pipeline.
+  - Deals carry an amount, an owner, the contacts and company involved and an expected close date. They move across a kanban board
+    by drag and drop or menu; moving one to a lost stage asks why.
+  - A forecast gives open value and weighted value per stage, win rate and time to win.
+  - Each deal keeps its stage history, notes, tasks and activity. Moves show on the deal's and its contacts' timelines, and deals
+    won, lost or moved can start automations.
+- **Task reminders** notify the assignee when a task comes due.
+- **1:1 email logging** (per sender, opt-in): mail the sender's mailbox exchanges with contacts goes on their timelines.
+- **Reports** over the last 7, 30, 90 or 365 days:
+  - email sent, opened, clicked, replied to, bounced and unsubscribed from, per day and as rates, with the top recipient domains;
+  - new contacts, subscribes and unsubscribes per day, and each list's subscribers;
+  - deals won (and their value), lost and open, and the win rate, for all pipelines or one.
+
+  Charts have a hover card, arrow-key navigation and a table view.
+- **Webhooks**: what happens in a workspace (contacts created or changed, subscriptions, forms, segments, email engagement, deals,
+  custom events, automation steps) posted as signed JSON to `https://` addresses on the public internet. Failed posts are retried
+  with backoff; an endpoint that keeps failing is switched off. Each endpoint shows its recent deliveries and can be pinged.
+- **An integration API** for a workspace's own systems, with **API keys** scoped to adding contacts, changing subscriptions or
+  reporting events.
+- **A CRM page in the admin console** (`/admin/crm`): every workspace with its size, the deployment's sending numbers, and a switch
+  that stops a workspace's campaign and automation email (for abuse) without touching its data.
+
+## Installing
+
+Install it from the admin console's **Plugins** page, or preinstall it by adding `@rapidmx/crm-plugin` to `system:plugins:defaults`.
+The CRM then appears on the web client's app rail, at `/crm`. It requires `@rapidmx/restapi` 0.26 or later.
+Replies, bounces and complaints are learned from restapi's mail event stream, so they need a restapi release that publishes it
+(0.27) and an `events` Redis datastore.
+
+### Settings
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `mail:crm:public_url` | `https://<host>` | The site the public pages are served from; links in CRM emails point here. |
+| `mail:crm:token_secret` | (generated) | The key public links are signed with. Left empty, one is generated and kept in the database. |
+| `mail:crm:workspace_creator_roles` | (empty) | Comma-separated roles allowed to create workspaces. Empty lets every signed-in user. |
+| `mail:crm:max_workspaces_per_user` | `10` | How many workspaces one user may create. |
+| `mail:crm:max_members` | `500` | How many members one workspace may have. |
+| `mail:crm:max_senders` | `50` | How many send-as addresses one workspace may have. |
+| `mail:crm:export:max_rows` | `50000` | How many records one CSV export may hold. |
+| `mail:crm:import:max_bytes` | `20971520` | The largest CSV file an import accepts. |
+| `mail:crm:jobs:import:schedule` | `*/5 * * * * *` | How often queued imports are picked up. |
+| `mail:crm:jobs:import:lease_seconds` | `300` | How long a server may work on an import before another may take it over. |
+| `mail:crm:jobs:import:max_attempts` | `3` | How many times an import is started before it is failed. |
+| `mail:crm:send_rate_per_minute` | `600` | The most campaign messages the whole deployment sends per minute. |
+| `mail:crm:verp` | `true` | Give each campaign message its own bounce address (`<sender>+b-<token>@<domain>`). Needs plus-addressing. |
+| `mail:crm:jobs:send:schedule`, `...:batch`, `...:lease_seconds`, `...:max_attempts` | `*/2 * * * * *`, `200`, `300`, `5` | How the dispatcher runs and retries. |
+| `mail:crm:jobs:campaign:schedule`, `...:lease_seconds`, `...:pages_per_run`, `...:page_size`, `...:stats_seconds` | `*/5 * * * * *`, `120`, `20`, `500`, `60` | How campaigns are prepared and their stats counted. |
+| `mail:crm:jobs:events:schedule` | `*/2 * * * * *` | How often the mail event stream is read. |
+| `mail:crm:jobs:segments:schedule`, `...:refresh_seconds`, `...:batch` | `0 * * * * *`, `300`, `20` | How dynamic segments are kept current. |
+| `mail:crm:jobs:scoring:schedule`, `...:interval_seconds`, `...:batch` | `30 * * * * *`, `3600`, `5` | How lead scores are kept current. |
+| `mail:crm:jobs:triggers:schedule`, `...:batch`, `...:retention_days` | `*/5 * * * * *`, `200`, `30` | How contact events are handed to automations, and how long they are kept. |
+| `mail:crm:jobs:reminders:schedule`, `...:lead_minutes` | `15 * * * * *`, `15` | How task reminders are sent, and how long before a task is due. |
+| `mail:crm:jobs:automations:schedule`, `...:batch`, `...:lease_seconds`, `...:paused_retry_seconds` | `*/5 * * * * *`, `100`, `120`, `60` | How contacts are moved through automations. |
+| `mail:crm:jobs:webhooks:schedule`, `...:max_attempts`, `...:retention_days` | `*/5 * * * * *`, `8`, `14` | How webhooks are posted and retried, and how long deliveries are kept. |
+| `mail:crm:jobs:dates:schedule` | `20 * * * * *` | How often date-triggered automations are checked (each puts contacts in once a day). |
+
+## API
+
+Every route is under `/api/mail/crm` and takes the workspace uid as its first path segment. Reading takes membership of the
+workspace; changing records takes the editor role, and changing settings, members, senders and custom properties the admin role.
+A deployment administrator has no access to a workspace they aren't a member of.
+
+| Resource | Endpoints |
+| --- | --- |
+| `workspaces` | `GET /`, `POST /`, `GET/PUT/DELETE /:workspaceUid`, `GET/POST /:workspaceUid/members`, `PUT/DELETE /:workspaceUid/members/:userUid`, `GET/POST /:workspaceUid/senders`, `PUT/DELETE /:workspaceUid/senders/:senderUid` |
+| `contacts`, `companies` | `GET /:workspaceUid`, `POST /:workspaceUid/search`, `POST /:workspaceUid/bulk`, `POST /:workspaceUid/export`, `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid` |
+| `properties`, `notes`, `tasks` | `GET /:workspaceUid`, `POST /:workspaceUid/search`, `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid` |
+| `timeline` | `GET /:workspaceUid/:subjectType/:subjectUid` |
+| `imports` | `GET /:workspaceUid`, `POST /:workspaceUid?objectType=&fileName=` (raw CSV body), `POST /:workspaceUid/:uid/start`, `GET/DELETE /:workspaceUid/:uid` |
+| `lists`, `suppressions`, `forms` | `GET /:workspaceUid`, `POST /:workspaceUid/search`, `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid` |
+| `subscriptions` | `GET /:workspaceUid?listUid=&contactUid=&status=`, `POST /:workspaceUid` (`{ listUid, contactUids, status }`) |
+| `templates` | `GET /:workspaceUid`, `POST /:workspaceUid/search`, `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid`, `GET /:workspaceUid/merge-tags`, `POST /:workspaceUid/render`, `POST /:workspaceUid/:uid/test`, `POST /:workspaceUid/:uid/duplicate` |
+| `saved-blocks` | `GET /:workspaceUid`, `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid` |
+| `campaigns` | `GET /:workspaceUid`, `POST /:workspaceUid/search`, `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid`, `POST /:workspaceUid/audience`, `GET /:workspaceUid/:uid/checklist`, `POST /:workspaceUid/:uid/schedule` (`{ sendAt? }`), `POST /:workspaceUid/:uid/unschedule\|pause\|resume\|cancel\|duplicate`, `GET /:workspaceUid/:uid/report`, `POST /:workspaceUid/:uid/recipients` |
+| `segments` | `GET /:workspaceUid`, `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid`, `POST /:workspaceUid/preview` (`{ filter }`), `POST /:workspaceUid/:uid/refresh` |
+| `scoring-rules` | `GET /:workspaceUid`, `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid` (admins), `POST /:workspaceUid/recalculate` |
+| `automations` | `GET /:workspaceUid`, `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid`, `POST /:workspaceUid/:uid/publish\|pause\|resume`, `POST /:workspaceUid/:uid/enroll` (`{ contactUids }`), `GET /:workspaceUid/:uid/report`, `POST /:workspaceUid/:uid/enrollments`, `POST /:workspaceUid/:uid/enrollments/:enrollmentUid/exit` |
+| `pipelines` | `GET /:workspaceUid` (makes a default pipeline if there is none), `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid` (admins) |
+| `deals` | `GET /:workspaceUid?pipelineUid=&stageId=&status=&ownerUserUid=&companyUid=&contactUid=`, `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid`, `GET /:workspaceUid/forecast?pipelineUid=&days=` |
+| `analytics` | `GET /:workspaceUid/email?days=`, `GET /:workspaceUid/growth?days=`, `GET /:workspaceUid/sales?days=&pipelineUid=` (`days` 1-365, 30 by default; UTC days) |
+| `webhooks` | `GET /:workspaceUid`, `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid` (admins; answers the `secret` once), `POST /:workspaceUid/:uid/secret` (a new secret), `POST /:workspaceUid/:uid/test` (a `ping`), `GET /:workspaceUid/:uid/deliveries` |
+| `api-keys` | `GET /:workspaceUid`, `GET/PUT/DELETE /:workspaceUid/:uid`, `POST /:workspaceUid` (admins; answers the `key` once) |
+| `integrations` (API key) | `POST /:workspaceUid/contacts`, `POST /:workspaceUid/subscribe`, `POST /:workspaceUid/unsubscribe`, `POST /:workspaceUid/events`, `GET /:workspaceUid/lists` |
+| `admin` (deployment administrators) | `GET /stats`, `GET /workspaces?limit=&page=`, `PUT /workspaces/:workspaceUid` (`{ sendingDisabled }`) |
+| `public` (anonymous) | `GET/POST /forms/:formUid`, `POST /confirm/:token`, `GET/POST /preferences/:token`, `GET/POST /unsubscribe/:token` |
+| `t` (anonymous) | `GET /o/:token` (open image), `GET /c/:token/:index?u=&s=` (tracked link) |
+
+A search takes `{ filter, q, sort: { field, direction }, limit, page }` and answers `{ items, total }`. A filter is a condition
+`{ field, op, value }` or a group `{ and: [...] }` / `{ or: [...] }`. Fields are a record's own fields, `tags`, or
+`properties.<key>`. The comparisons are `eq`, `ne`, `contains`, `notContains`, `startsWith`, `gt`, `gte`, `lt`, `lte`, `between`,
+`in`, `notIn`, `isSet` and `isNotSet`, each allowed on the types it makes sense for.
+
+A template's `design` is `{ theme, sections: [{ columns: [{ blocks: [...] }] }] }`. It is checked and sanitized on every save:
+- Text is limited to what the editor produces.
+- Links must be web, mail, phone or merge-tag links, and images must use `https://`.
+- HTML blocks may only be added or changed by workspace admins. Scripts, frames and forms are removed from them.
+- A design that can't be laid out, or that has a broken merge tag, is refused.
+
+`POST /render` returns `{ subject, html, text }`. A test is sent only to the address of a mailbox the caller can read.
+
+### Webhooks
+
+Each delivery is a `POST` of JSON: `{ id, type, occurredAt, workspaceUid, contact?: { uid, email, firstName, lastName }, data }`.
+`type` is the event (`contact.created`, `deal.won`, `custom`, `automation.webhook`, `ping`...). The `X-RapidMX-Signature` header is
+`t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>" keyed with the endpoint's secret>`; check it, and refuse old timestamps.
+A 2xx answer counts as delivered. Anything else is retried 1, 2, 4... minutes later, up to 8 times; after 20 failures in a row the
+endpoint is switched off. Redirects aren't followed, and the address is resolved and checked for a public IP at every post.
+
+### Integration API
+
+Call `/api/mail/crm/integrations/<workspaceUid>/...` with `Authorization: Bearer crm_...`. A missing, unknown or revoked key is a
+401; a key without the endpoint's scope a 403. Each key may make 600 calls a minute.
+
+| Endpoint | Scope | Body | Answer |
+| --- | --- | --- | --- |
+| `POST /contacts` | `contacts` | `{ email, firstName?, lastName?, phone?, tags?, properties?, ... }` | `{ outcome: "created" \| "updated", uid }` |
+| `POST /subscribe` | `subscriptions` | `{ email, listUid, ...contact fields }` | `{ contactUid, status }` |
+| `POST /unsubscribe` | `subscriptions` | `{ email, listUid? }` - without a list, from every list and all email | `{ contactUid? }` |
+| `POST /events` | `events` | `{ email, name, data? }` - starts automations whose trigger is a custom event (of that name) | `{ contactUid }` |
+| `GET /lists` | any | | `[{ uid, name, publicName }]` |
+
+## Development
+
+```sh
+yarn install
+yarn build        # lint, then compile the server code and the pages
+yarn test:prod    # every test on MongoDB and SQL, with the coverage gates
+```
+
+To try it on a local server, `npm pack` this package and point the server's `system:plugins:sources` at the tarball.

package/apps/admin-crm/_layout.tsx

@@ -0,0 +1,46 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { PropsWithChildren } from "react";
+import { Branding } from "@rapidmx/web-client/lib/branding/brandingApi.js";
+import { CUSTOM_STYLESHEET_LINK_ID } from "@rapidmx/web-client/lib/branding/useBranding.js";
+
+export interface LayoutProps {
+    /**
+     * Supplied by the server's `AdminConsoleRoute` `fetchProps()`, which every `admin` plugin app's route extends. This file is a
+     * copy of `@rapidmx/web-client`'s `apps/admin/_layout.tsx`, since every app directory needs its own layout.
+     * `@rapidrest/react` spreads the same merged page props onto this
+     * layout as onto the page it wraps, so it renders correctly server-side on the very first byte of the
+     * response: no client-side flash from the stock defaults below, and a crawler reading the raw HTML
+     * sees the real branding too. `undefined` only on the framework's unwrapped `_500` fallback path,
+     * which doesn't receive props at all - falling back to the stock defaults there is acceptable.
+     */
+    branding?: Branding;
+}
+
+export default function Layout({ children, branding }: PropsWithChildren<LayoutProps>) {
+    const title = branding?.title || branding?.companyName ? `${branding?.title || branding?.companyName}: CRM administration` : "RapidMX: CRM administration";
+    const iconHref = branding?.iconUrl || branding?.logoUrl || "/images/logo.svg";
+    const stylesheetHref = branding?.stylesheetUrl;
+
+    return (
+        <html lang="en">
+            <head>
+                <meta charSet="utf-8" />
+                <meta name="viewport" content="width=device-width, initial-scale=1" />
+                <title>{title}</title>
+                <link rel="icon" type="image/svg+xml" href={iconHref} />
+                <link rel="alternate icon" href="/favicon.ico" />
+                <link rel="preconnect" href="https://fonts.googleapis.com" />
+                <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+                <link
+                    rel="stylesheet"
+                    href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap"
+                />
+                {stylesheetHref && <link rel="stylesheet" href={stylesheetHref} id={CUSTOM_STYLESHEET_LINK_ID} />}
+            </head>
+            <body>{children}</body>
+        </html>
+    );
+}

package/apps/admin-crm/index.tsx

@@ -0,0 +1,16 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import AdminShell, { AdminShellProps } from "@rapidmx/web-client/shared/components/admin/layout/AdminShell.js";
+import CrmAdmin from "../shared/components/admin/CrmAdmin.js";
+
+/** The CRM's page in the admin console. */
+export default function CrmAdminPage(props: Omit<AdminShellProps, "active">) {
+    return (
+        <AdminShell {...props} active="crm">
+            <CrmAdmin />
+        </AdminShell>
+    );
+}