Map your Flodesk audience and clean up overlapping segments

Build me an app for auditing my whole Flodesk audience by segment on one screen, instead of clicking through segments one at a time inside Flodesk. I own the email list and I run this audit every month or so. I want the entire structure of my audience visible in a single view before I start changing anything.

The app should work from a cached full pull of my account rather than refetching on every interaction. On a refresh, load every segment with Flodesk List All Segments, then load my subscribers with Flodesk List All Subscribers, walking the pagination envelope until meta.total_pages is reached and using the maximum per_page of 100. Flodesk is rate limited to 100 requests per minute, so pace the pull, show progress while it runs, and store the result as a timestamped snapshot. Give me a Refresh button and a visible last refreshed label. Every view and every count in the app reads from that snapshot. Pull Flodesk List All Custom Fields once as well, so custom field values can be shown on subscriber rows and used for filtering.

The main view is a segment matrix. Each row is a segment showing its name, total members, how many of those are active versus unsubscribed, and the unsubscribed share as a percentage. The same segments run across the columns, and each cell shows the overlap between the row segment and the column segment: the number of subscribers in both, and that count as a percentage of the row segment. Shade the cells by overlap strength so heavy duplication is obvious at a glance, and let me set the threshold above which an overlap is flagged as heavy. Let me sort rows by size, by unsubscribed share, or by how much total overlap the segment carries. Clicking any overlap cell opens the list of subscribers sitting in both segments. Clicking a row opens that segment's members, filterable by active or unsubscribed status and searchable by email or name.

Next to the matrix, keep a separate orphan bucket: every subscriber in my audience who belongs to no segment at all. Show the count prominently, list those people with their email, name, status, signup date and any custom field values, and let me select and act on them exactly like anywhere else in the app. These are the people who never show up when I browse segment by segment, so they need their own home.

From any overlap cell, any segment's member list, or the orphan bucket, I can select subscribers and take three actions: Flodesk Add Subscriber to Segments, Flodesk Remove Subscriber from Segments, and Flodesk Unsubscribe Subscriber. Every action goes through a preview step before anything happens. The preview names the affected subscribers, names the segments, gives the count, and shows what each segment's size will be afterwards. Call out the destructive cases explicitly: unsubscribes, and removals that would leave someone in no segment at all and drop them into the orphan bucket. Nothing calls Flodesk until I confirm. Apply changes one subscriber at a time within the rate limit, show progress, and report individual failures rather than silently dropping them. Update the snapshot in place after a confirmed change so the matrix and counts reflect what I just did without a full refetch.

Add a Draft a cleanup plan button that kicks off a background agent. The agent reads every segment and its membership from the snapshot and proposes a restructure: which segments to merge because they overlap so heavily they are effectively the same audience, which to retire because they are tiny, stale, or almost entirely unsubscribed, which to rename because the name does not describe who is actually in it, and which subscribers to re-tag, including orphans that clearly belong somewhere. Every proposal needs a plain-English reason and the numbers behind it, such as the overlap percentage or the unsubscribed share that justifies it.

The agent writes its plan back into the app as an approve-row-by-row checklist. Each row shows the proposed change, the reasoning, the exact segments and subscribers affected, and Approve or Dismiss buttons. Nothing is applied when the agent finishes. Approving a row runs it through the same preview and confirm path as a manual action. I can approve rows in any order, or select several and approve them together. Keep past plans so I can see what I decided last time and what I ignored.

Be honest in the plan about what the app can and cannot apply. A merge is executed as membership changes, adding everyone from the retired segment into the surviving one and then removing them from the old one, and Flodesk Create Segment is available if the merge target should be a brand new segment. Flodesk has no operation to rename or delete a segment, so a rename suggestion and the deletion of the empty shell left behind by a merge should be presented as a short manual step for me to finish in Flodesk, with the exact segment name to change, and marked done in the checklist once I have done it. Never imply the app renamed or deleted something it did not.

Keep a change log inside the app covering every membership change it makes: timestamp, the action, the subscriber, the segments involved, whether it came from a manual selection or an approved plan row, and whether it succeeded. The log is its own view that I can filter by date, segment and action, and search by email. Segment adds and removals can be reversed straight from the log in one click, going through the same preview and confirm path. Unsubscribes are recorded in the log but never reversed automatically, because putting someone back on a list is a consent decision rather than a data fix, so show those rows as permanent with a note explaining why.