@awesomate/hosting-mcp 0.54.0 → 0.56.0

package/skill/awesomate-email/references/consent-law.md

@@ -0,0 +1,111 @@
+# Consent law for email: Australia and New Zealand
+
+Read this when deciding who may be emailed, when an owner asks "can I email
+these people?", or before any import. Checked against primary sources on
+1 October 2026. You are not the owner's lawyer: state the practical rule,
+and when a case is genuinely unclear, say so and suggest they check.
+
+## Australia: the Spam Act 2003
+
+Three things for every commercial email (anything that offers, promotes or
+links to goods or services, including an email asking for consent):
+
+1. **Consent.** Express (they agreed, for example by filling in a form) or
+   inferred (see below). The sender must be able to prove it (s 16(5)).
+2. **Identify the sender.** The business's legal name, or the owner's name
+   and ABN, and how to contact them, valid for 30 days after sending (s 17).
+3. **A working unsubscribe.** A link or a reply address; "reply with
+   unsubscribe" is valid. No login, no extra details. It must keep working
+   for 30 days, and the withdrawal takes effect within 5 business days
+   (s 18; Sch 2 cl 6). Build to "at once": Gmail and Yahoo expect two days.
+
+**Asking for consent by email is itself a commercial message.** ACMA: "You
+cannot send an electronic message to ask for consent, because this is a
+marketing message." A message that links to marketing content is commercial
+too.
+
+**Inferred consent is narrow.** The Act allows consent that "can reasonably
+be inferred from the conduct and the business and other relationships" (Sch
+2 cl 2). ACMA reads that as "a provable, ongoing relationship with your
+business, and the marketing is directly related to that relationship". It
+"does not cover sending messages after someone has just bought something",
+and its 2024 statement of expectations says: "Do not infer consent from
+one-off purchases ... including in cases where email addresses are obtained
+to send receipts or tax invoices", and "Do not use consent that is old,
+where a consumer would not expect it to still apply."
+
+In practice:
+
+| Who | Inferred consent? |
+|---|---|
+| A current member, student, retained client, service-plan or maintenance-contract customer | Usually yes, for messages directly related to that relationship |
+| A property manager or business you do repeat work for | Usually yes, for related messages to the person you deal with |
+| Someone who had one job, one purchase or one appointment | No |
+| Someone who asked for a quote and didn't go ahead | Not established; treat as no |
+| An address you hold only because you sent a receipt or invoice | No |
+| A former customer from years ago | No ("old" consent) |
+
+**Conspicuous publication** (Sch 2 cl 4) is a narrow exception for business
+addresses: published for a person or role, publication reasonably assumed to
+be agreed, no "no marketing" statement next to it, and the email relevant to
+their work. The mere fact an address is published is not consent.
+
+**Double opt-in is not required**, but ACMA recommends it. Filling in a form
+is express consent. Keep records of how consent was obtained, the terms, and
+the date and time. ACMA has said nothing specific about people who signed up
+but never clicked the confirmation link; treat them as not emailable.
+
+**Penalties.** For a company with no prior record, up to 100 penalty units
+per contravention, capped at 2,000 units a day; ten times that with a prior
+record (s 25). At $364 a unit from 1 July 2026 that is $36,400 per message
+breach and $728,000 a day. Recent ACMA actions: Commonwealth Bank $7.5m (2024),
+Pizza Hut $2.5m (2024), Ticketek $515,040 (2023), Outdoor Supacentre
+$302,500 (2024, "companies can't outsource their compliance obligations"),
+Lululemon $702,900 and Latitude $3.96m (2026).
+
+## New Zealand: the Unsolicited Electronic Messages Act 2007
+
+Much the same. Consent is express, inferred ("from the conduct and the
+business and other relationships"), or deemed (conspicuous publication, same
+conditions). A message that links to or directs someone to marketing is
+commercial (s 6). The Department of Internal Affairs says consent cannot be
+inferred from a single transaction, "silence should not be taken as consent",
+and emailing an old database to ask people to unsubscribe "cannot establish
+consent". Unsubscribe takes effect within 5 working days and must work by the
+same method the message came by (ss 9, 11). On double opt-in the DIA is
+firmer than Australia: "If this link is not clicked, then electronic
+marketing should not take place." Penalties up to $200,000 for an individual
+and $500,000 for an organisation.
+
+## Privacy Act 1988 (Australia), where it touches email
+
+- **Health information is sensitive information.** Collecting it needs the
+  person's consent (APP 3.3), and using sensitive information for direct
+  marketing needs consent too (APP 7.4). Health service providers are never
+  exempt as small businesses.
+- So: never build a marketing group from conditions or diagnoses. Use an
+  opt-in interest instead.
+- The statutory tort for serious invasions of privacy has applied since
+  10 June 2025. Direct-marketing changes are still only proposed (exposure
+  draft, August 2026).
+
+## The mailbox providers' rules
+
+Not law, but they decide whether email arrives. See `deliverability.md`.
+Google's Workspace policy bans "unsolicited mass email" and can suspend the
+account; Microsoft says businesses that need to send newsletters "should use
+third-party providers". Neither the owner's Gmail nor their Microsoft 365
+mailbox is a bulk sending tool.
+
+## Sources
+
+- Spam Act 2003: https://www.legislation.gov.au/C2004A01214/latest/text
+- ACMA, Avoid sending spam: https://www.acma.gov.au/avoid-sending-spam
+- ACMA, consent expectations (2024): https://www.acma.gov.au/publications/2024-07/guide/consumer-consent-expectations-businesses-conducting-telemarketing-and-e-marketing
+- ACMA enforcement: https://www.acma.gov.au/investigations-spam-and-telemarketing
+- Penalty unit from 1 July 2026: https://www.legislation.gov.au/F2026N00424/asmade/2026-06-16/text/original/pdf
+- UEM Act 2007: https://www.legislation.govt.nz/act/public/2007/0007/latest/whole.html
+- DIA FAQs: https://dia.govt.nz/Spam-Frequently-Asked-Questions and https://www.dia.govt.nz/Spam-Three-Steps
+- Privacy Act 1988: https://www.legislation.gov.au/C2004A03712/latest/text
+- Google Workspace sending limits: https://knowledge.workspace.google.com/admin/gmail/gmail-sending-limits-in-google-workspace
+- Exchange Online limits: https://learn.microsoft.com/en-us/office365/servicedescriptions/exchange-online-service-description/exchange-online-limits

package/skill/awesomate-email/references/copywriting.md

@@ -0,0 +1,167 @@
+# Writing emails for a small business's customers
+
+Read this before drafting any email. The goal is an email the owner would be
+happy to have written themselves, that a customer reads in twenty seconds and
+acts on.
+
+## The voice
+
+- **The owner, writing to one person.** First person ("I", "we"), signed by
+  a real person. Not "Dear Valued Customer", not a brand talking to a crowd.
+- **Their words, not marketing words.** Reuse how the owner talks about their
+  work. If they say "hot water unit", don't write "water heating solution".
+  If the account has a brand voice on file, follow it.
+- **Australian or New Zealand English.** Organise, colour, centre, licence
+  (noun), program. Mobile, not cell. Postcode, not zip. Autumn, not fall.
+  Dates as 4 October or 4/10. Money in AUD or NZD with the dollar sign.
+- **Southern hemisphere calendar.** December is summer and the Christmas
+  shutdown; storm season in Queensland and New South Wales runs roughly
+  November to March; winter is June to August. EOFY is 30 June in Australia,
+  31 March in New Zealand. School terms and public holidays differ by state
+  and region. Check before sending.
+- **Plain, warm, direct.** "G'day" or "Kia ora" only if the owner talks that
+  way. No hype, no exclamation runs, no ALL CAPS, no emoji, no em-dashes
+  (Awesomate's checks refuse an em-dash in an email).
+
+## Structure of one email
+
+1. **Subject line**: specific and plain, usually under about 50 characters.
+   It should be true of the body.
+2. **Preview text**: the line shown after the subject in the inbox. Add to
+   the subject; never repeat it, and never leave it to "View in browser".
+3. **Opening line**: why this, why now, why you. One sentence.
+4. **Body**: one idea. Two or three short paragraphs, or a short list.
+5. **One button**: a verb and an outcome ("Book a storm-season check", "See
+   the new timetable"). Secondary links are fine as plain text; a second
+   button is a second email.
+6. **Sign-off from a person**, optionally a P.S. (people read them).
+7. **Footer**: why they're getting it ("You asked for seasonal tips"), the
+   business name and ABN or contact details, and unsubscribe. In Awesomate
+   the hub adds the footer and the unsubscribe link; you write only the
+   reason line, in the draft's `reason`.
+
+## Subject lines that work for small businesses
+
+- The question the customer is already asking: "Is your hot water system on
+  borrowed time?"
+- The useful number: "3 things to check before the first storm"
+- The local hook: "Carindale: water restrictions start Monday"
+- The plain announcement: "Saturday classes start 12 October"
+- The owner's voice: "A quick one from Rob"
+
+Avoid: fake "RE:" or "FWD:" (misleading, and it trains people to distrust
+you), clickbait the body doesn't pay off, ALL CAPS, piles of emoji, and
+"Newsletter #14".
+
+## Email types and what each one needs
+
+| Type | Send when | Must include |
+|---|---|---|
+| Welcome | Straight after joining | What they'll get and how often, one useful thing now, who it's from |
+| Tips or newsletter | On the promised cadence | One main idea; link to more |
+| Announcement | Something genuinely new | What changed, who it's for, what to do |
+| Offer | A real offer with a real end | The exact terms, the real end date, how to claim |
+| Service reminder | Something is due | What's due, why it matters, one-click booking |
+| Event invite | 2 to 4 weeks before | Date, time, place, cost, how to book |
+| Win-back | Past customer, gone quiet | A personal note, a reason to come back, no guilt |
+| Still want these? | Quiet for 6 to 12 months | One click to stay, otherwise we stop. Then stop. |
+| Review request | After a finished job | A direct link; ask everyone, not only the happy ones |
+
+## Rules from the law and the industry bodies
+
+- **No invented proof.** No made-up testimonials, reviews, numbers or case
+  studies. Real reviews only with permission and quoted accurately.
+- **Offers must be real.** "Was $X, now $Y" only if $X was the genuine
+  price. "Ends Friday" only if it ends Friday. "Free" means free. (Australian
+  Consumer Law; NZ Fair Trading Act.)
+- **Reviews:** asking only satisfied customers for reviews ("review gating")
+  can mislead under consumer law. Ask everyone.
+- **Registered health practitioners** (physio, chiro, dental, psychology,
+  optometry, osteopathy and others regulated by Ahpra) **cannot use
+  testimonials in advertising** for their regulated services, and must not
+  create unreasonable expectations or encourage unnecessary use. No
+  before-and-after claims, no "cure", no discounts that pressure people into
+  treatment.
+- **Financial services:** if the firm holds an AFSL, broadcast content is
+  general advice at most and carries their warning. Never write personal
+  advice into a broadcast.
+- **Real estate:** don't publish a vendor's sale price or a buyer's details
+  without permission.
+
+## Personalisation
+
+- First name only when the data is reliable; otherwise "Hi there". A wrong
+  name is worse than none. In Awesomate, `{{first_name|there}}` does both.
+- Refer to their history only when it's accurate and expected: "the hot
+  water system we installed in 2019" is helpful from a plumber. "We noticed
+  you looked at our pricing page" is creepy.
+- AI-personalised emails (a different paragraph per person) are fine when
+  every version is drafted from approved content and the owner has seen
+  samples. Show three examples, including the strangest one. Awesomate's
+  emails personalise with first name, last name and email only, so this is
+  for other platforms.
+
+## From a video (Loom, YouTube, Vimeo)
+
+Watch it first (the watch skill) so the email describes what is actually in
+it. Email clients don't play video: use a still from the video with a play
+button drawn on it, linking to the video. Summarise the useful part in the
+email itself, so someone who never clicks still gets value.
+
+## Design and accessibility
+
+Single column. Real text, never text inside an image. Body at least about
+16px. Buttons as real links with descriptive text, never "click here".
+Alt text on every image. Works in dark mode. A plain-text version always.
+No attachments: link to the file instead. In Awesomate the theme handles
+layout, dark mode and the plain-text version; you supply the words, the alt
+text and https links.
+
+## Length
+
+Most small-business emails are best between about 75 and 200 words. A
+newsletter can be longer when it's scannable (short sections with clear
+headings), but if it needs scrolling on a phone, ask whether it's two emails.
+
+## Worked example: trades tips
+
+Subject: 3 things to check before the first storm
+Preview: Two minutes with a bucket can save a flooded laundry.
+
+> G'day Sam,
+>
+> Storm season's nearly here. Before the first big one, it's worth two
+> minutes on these:
+>
+> 1. **Gutters.** Clear leaves before they overflow into the eaves.
+> 2. **Downpipes.** Pour a bucket down each and watch where it goes.
+> 3. **The stormwater pit.** Lift the grate and check it isn't full of silt.
+>
+> If any of them look wrong, we'll sort it before the rain does.
+>
+> [Book a storm-season check]
+>
+> Cheers,
+> Rob
+>
+> P.S. If your hot water system is more than 10 years old, ask us to look at
+> it while we're there.
+
+## Worked example: studio term enrolment (New Zealand)
+
+Subject: Term 4 enrolments open Monday
+Preview: Saturday hip hop is back, and there's a new adult beginners class.
+
+> Kia ora Mere,
+>
+> Term 4 starts on 13 October and enrolments open this Monday at 9am.
+> Saturday hip hop is back by popular demand, and we've added an adult
+> beginners contemporary class on Wednesday nights.
+>
+> Spots in the Saturday classes went in two days last term, so if Aria is
+> keen, Monday morning is the time.
+>
+> [See the Term 4 timetable]
+>
+> Ngā mihi,
+> Jess

package/skill/awesomate-email/references/deliverability.md

@@ -0,0 +1,81 @@
+# Keeping email out of the spam folder
+
+Read this when setting up sending, before a big or unusual send, or when
+the owner says emails are going to spam.
+
+## The set-up that protects the business
+
+- **Send marketing from a subdomain**, for example `news.theirdomain.com.au`,
+  never from the main domain the owner uses for quotes and invoices. If a
+  campaign goes badly, the damage stays on the subdomain.
+- **SPF, DKIM and DMARC all pass**, aligned with the From address. DMARC can
+  start at `p=none` on the subdomain and tighten to quarantine once mail has
+  passed cleanly for a few weeks. Never change the main domain's DMARC to
+  set up marketing.
+- **A branded link domain** (for example `links.news.theirdomain.com.au`)
+  rather than a shared tracking domain. Never use URL shorteners in email.
+- **Never bulk-send from the owner's own Gmail or Microsoft 365 mailbox.**
+  Those accounts have daily limits and outbound spam controls, and a
+  suspension takes the owner's everyday email with it. Small personal
+  batches are a different thing (see `asking-permission.md`).
+
+## Starting a new sending address (warm-up)
+
+New addresses have no reputation. Build it over about two weeks: a small
+first day, growing each day, most engaged people first (recent customers and
+recent clickers). One schedule that works: 150 on day one, 700 by day four,
+2,000 by day seven, then the full list. A sudden big send from a new or
+long-silent address looks like a spammer.
+
+In Awesomate each approved email goes to everyone on its list who may be
+emailed, so warm up by list: the smallest, most engaged list first (often the
+customers list), then the bigger ones over the following weeks.
+
+## List hygiene
+
+Awesomate does the first of these for you: anyone who unsubscribes,
+hard-bounces or marks an email as spam is left out of every later send, and
+every marketing email carries one-click unsubscribe.
+
+- Hard bounces and spam complaints: suppressed immediately, for good.
+- Soft bounces: retry; suppress after several in a row.
+- Quiet for six to twelve months (no click, reply, booking or purchase): one
+  "still want these?" email, then stop sending to anyone who doesn't respond.
+  Old, unread addresses are where spam traps live.
+- Never buy, rent or scrape a list. Never import an event attendee list
+  someone else ran.
+- Watch for typo domains on sign-up forms (gmial.com, hotmial.com).
+
+## What the big inboxes require
+
+Google and Yahoo (since February 2024): every sender needs SPF or DKIM,
+valid DNS and TLS, and a low spam complaint rate. Senders of roughly 5,000
+or more messages a day to them also need SPF, DKIM and aligned DMARC, and
+one-click unsubscribe (the `List-Unsubscribe-Post` header, RFC 8058) on
+marketing mail, honoured within two days. Keep the complaint rate below
+0.1%; at 0.3% Gmail starts filtering or rejecting. Microsoft applies similar
+rules to high-volume senders to Outlook.com addresses. Build to the bulk
+standard even for small lists: it costs nothing and the thresholds are
+measured across everything sent from the domain.
+
+## Content that hurts
+
+Image-only emails, missing plain-text version, link text that doesn't match
+the link, URL shorteners, attachments, a different From name every send,
+and subject lines the body doesn't pay off. "Spam words" matter far less
+than people think; reputation and complaints matter far more.
+
+## Diagnosing "we're going to spam"
+
+1. **Check authentication** on a received copy: the headers should show
+   `spf=pass`, `dkim=pass`, `dmarc=pass` for the sending domain.
+2. **Check complaint rate and reputation**: Google Postmaster Tools for the
+   sending domain; the platform's complaint numbers.
+3. **What changed?** A new import, an old segment, a jump in frequency, a
+   new link domain, a new From address. The cause is almost always one of
+   these.
+4. **Fix the cause, then recover slowly**: send only to the most engaged for
+   a couple of weeks, then widen.
+
+Don't "fix" spam placement by rewording subject lines while the real cause
+(an old list, high complaints) is still there.

package/skill/awesomate-email/references/list-planning.md

@@ -0,0 +1,127 @@
+# Planning the lists: the first conversation
+
+Read this when a business is starting email properly, moving off another
+platform, or asks "what lists should we have?".
+
+## Lists are promises, groups are filters
+
+| | A list | A group |
+|---|---|---|
+| What it is | What someone agreed to receive | A filter over people already on lists |
+| Who creates it | The owner, with wording people see | Anyone, any time |
+| Needs consent? | Yes, its own | No, it inherits from the list |
+| How many | Two to four | As many as are useful |
+| Example | "Tips & seasonal checks" | "On Tips, hot water job over 8 years ago" |
+
+Why so few lists: each one is a separate promise, needs its own sign-up
+wording, and has to be honoured on cadence. Five lists that each send monthly
+is five emails a month to someone on all of them. Most small businesses are
+best served by one main list plus one customers-only list.
+
+## The method
+
+1. **Learn the business.** Read the website (services, seasons, what is
+   booked or bought again and again), the business overview if the account
+   has one, and how they describe themselves. Note the customer's buying
+   cycle: a hot water system every 10 to 15 years, a dental check every 6
+   months, a dance term every 10 weeks, a tax return every year.
+2. **Read the source list.** Groups, interests and tags from the old
+   platform say what people actually signed up for. Sign-up form names and
+   dates tell you which promise each person saw.
+3. **Read the job or sales history if connected.** Customers with an
+   ongoing relationship (members, retained clients, service plans, repeat
+   work) can usually receive messages directly related to it, once the
+   owner confirms the relationship. One-off customers can't, until they
+   sign up (see `consent-law.md` and `asking-permission.md`). Customers are
+   still the most valuable people on any list.
+4. **Propose two to four lists**, each as one sentence the owner can read
+   aloud: name, the promise in the words a subscriber will see, how often,
+   who starts on it and why, and the count. Then three to five starter
+   groups.
+5. **Put imported people only on a list their sign-up covers.** Someone who
+   signed up for "seasonal tips" has not agreed to "offers". When a mapping
+   is a judgement call, put them on the closer, narrower list and tell the
+   owner what you did.
+6. **Let the owner change it in their words.** "Drop News, fold it into
+   Tips" is a complete instruction. Repeat back what will change, then make
+   the change. In Awesomate the owner creates and changes lists in the hub
+   (https://hub.awesomate.ai/contacts, or while importing), so give them each
+   list's name and wording ready to paste, and say which ones are customers
+   lists.
+
+Present the proposal like this (keep it this short):
+
+> I'd start with three lists.
+> **Tips & seasonal checks**, about monthly, more in storm season. Promise:
+> "Seasonal maintenance tips by email. Unsubscribe any time." 1,527 people
+> from your Mailchimp "Newsletter" group start here.
+> **Service reminders**, only when something is due, about work we did for
+> them. 412 repeat customers and property managers, if you confirm you work
+> with them regularly. One-off customers join when they next book.
+> **News & offers**, a few times a year. 1,179 people who ticked "specials"
+> on your old form.
+> And groups for: hot water systems over 8 years old, Carindale and
+> surrounds, clicked but didn't book, quiet for six months.
+> Want any of those changed?
+
+## Starter sets by kind of business
+
+These are starting points to adapt, not templates to copy. Rename everything
+into the owner's own words.
+
+**Trades and field service** (plumbers, electricians, builders, pest,
+cleaning, solar). Lists: Tips & seasonal checks (monthly, heavier before
+storm season, winter or summer depending on the trade); Service reminders
+(customers, when due); News & offers (occasional). Groups: by suburb or
+postcode radius, by job type, by age of the thing installed, landlords vs
+owner-occupiers, commercial vs residential.
+
+**Studios, classes and training** (dance, martial arts, yoga, music,
+tutoring, swim). Lists: Timetable & new classes (per term, plus changes);
+Events & workshops; Members' and families' news (current students, inferred
+from enrolment). Groups: by class or level, parents vs adult students,
+lapsed students (no enrolment this term), trial-class attendees who didn't
+join. Term dates drive cadence: send before enrolments open, not during
+holidays.
+
+**Retail, ecommerce and product.** Lists: New arrivals & restocks; Sales &
+offers; Care & how-to (product care, recipes, guides). Groups: bought in a
+category, repeat buyers, first-time buyers in their first 30 days, haven't
+bought in 6 or 12 months, VIP by spend. Be careful with frequency: offers
+weekly trains people to wait for the discount.
+
+**Health and allied health** (physio, chiro, dental, psych, optometry,
+vets). Lists: Clinic news & general tips (no condition-specific content);
+Appointment and recall reminders (patients, part of their care, kept
+separate from marketing). Groups: only from non-sensitive facts unless the
+patient explicitly consented to that use (location, practitioner seen,
+"interested in Pilates" from an opt-in). Never a group built from diagnoses
+or conditions. Registered health practitioners cannot use testimonials in
+advertising. See `copywriting.md`.
+
+**Real estate and property.** Lists: Suburb market updates; New listings &
+open homes; Landlord updates (landlords only). Groups: by suburb, buyers vs
+sellers vs landlords vs tenants, appraisal requested, price band. Sold
+results need care around vendor privacy.
+
+**Finance, accounting and advisory.** Lists: Tax time & key dates (BAS,
+EOFY, lodgement deadlines); Business tips; Client updates (current clients).
+Groups: sole traders vs companies, BAS quarterly vs monthly, clients with
+upcoming lodgements. If the firm holds an AFSL, broadcast content stays
+general and carries their general advice warning; ask them for it.
+
+**Coaching and consulting.** Lists: Weekly or fortnightly letter (the
+owner's thinking, one idea per email); Programs & events. Groups: past
+clients, workshop attendees, downloaded a guide.
+
+**Hospitality** (cafes, restaurants, venues). Lists: What's on & specials;
+Functions & events. Groups: by venue, booked a function, birthday month
+(only if collected with consent).
+
+## What the owner should leave with
+
+- The lists, each with its promise wording (this becomes the consent wording
+  version 1), cadence and starting count.
+- The starter groups, each as a sentence and a count.
+- What happens to people who fit no list: they stay as contacts and are not
+  emailed until they join something.

package/skill/awesomate-email/references/migration.md

@@ -0,0 +1,101 @@
+# Moving a list off Mailchimp, ActiveCampaign or Ontraport
+
+Read this before importing from another platform. The aim is to bring the
+consent records as well as the addresses, so that on day one everyone's
+status is known and nobody who left is ever emailed again.
+
+## Into Awesomate's Contacts & email
+
+The owner imports, in the hub at https://hub.awesomate.ai/contacts/import
+(Bring your list). It takes a spreadsheet (a CSV with an email column),
+Mailchimp (an API key, which is used once and not kept, or the subscribed,
+unsubscribed and cleaned export files), an ActiveCampaign export (one file per
+status, or one file with a Status column) or an Ontraport export (with the
+Bulk Email Status column). The hub reads each person's status, puts the
+unsubscribed and bounced in first, and sorts everyone by the record of how
+they agreed: a sign-up record, needs the owner's word, or unknown. At review
+the owner picks the lists, gives their word for the people with no record if
+they can, may say that everyone with a given tag is a customer they work with
+regularly (which puts them on a customers list), and commits. They can undo an import until the end of that day.
+
+You can't import or commit, because committing is the owner's statement about
+who agreed. Your part: read the export first, report the counts per status,
+and suggest which list each group or tag belongs on (below).
+
+## Bring these, not just the emails
+
+- Status (subscribed, pending, unsubscribed, bounced, complained).
+- When and how they signed up: time, source or form, IP if recorded,
+  confirmation time if double opt-in.
+- Groups, interests and tags (they map to lists or groups, see below).
+- Custom fields worth keeping (suburb, customer type, last job).
+- The last 12 months of clicks if available, to send to the most engaged
+  first while a new sending address warms up.
+
+## Status maps
+
+| Platform | Status in the source | Becomes |
+|---|---|---|
+| Mailchimp | subscribed, with OPTIN_TIME / CONFIRM_TIME | Can be emailed on the matching list |
+| Mailchimp | subscribed, no sign-up record | Needs the owner's statement before anyone emails them |
+| Mailchimp | pending (never confirmed) | Not emailed. See `asking-permission.md` |
+| Mailchimp | unsubscribed | Suppressed, permanently |
+| Mailchimp | cleaned (hard bounced) | Suppressed, permanently |
+| Mailchimp | transactional, archived | Not on any marketing list |
+| ActiveCampaign | Active (list status 1) | Can be emailed on that list |
+| ActiveCampaign | Unconfirmed (0) | Not emailed |
+| ActiveCampaign | Unsubscribed (2), Bounced (3) | Suppressed |
+| Ontraport | Opted-in, Double opt-in | Can be emailed |
+| Ontraport | Transactional Only | Not on any marketing list |
+| Ontraport | Hard bounce, Under review | Suppressed |
+
+Where to find them: Mailchimp exports an audience as a ZIP with subscribed,
+unsubscribed and cleaned files (Audience, All contacts, Export Audience); the
+API also returns `timestamp_signup`, `timestamp_opt` and `ip_opt`.
+ActiveCampaign's API URL and key are under Settings, Developer. Ontraport's
+API key and App ID are under Administration, Integrations; the email status
+field is `bulk_mail` (Bulk Email Status in an export). For Awesomate, only
+Mailchimp is read by API key; ActiveCampaign and Ontraport come in as export
+files.
+
+Platform field names change; check the export headers rather than trusting
+this table blindly, and say so if a column you expected isn't there.
+
+## Groups and tags: list or group?
+
+- A group or interest someone **chose** on a sign-up form ("Tips", "Specials")
+  is a promise: map it to a list.
+- A tag the business **applied** ("customer", "Carindale", "VIP") is a fact:
+  map it to a field or a group, never to a list.
+- When a source has one big list and no groups, everyone goes on the list
+  closest to what the sign-up form promised. Find the form wording if you
+  can.
+
+## Order of work
+
+1. Read the source and report counts per status before importing anything.
+2. Agree the lists (see `list-planning.md`).
+3. Import, with suppressions first, so a suppressed address can never be
+   re-added as subscribed by a later row. (Awesomate's import does this
+   itself.)
+4. The owner confirms anything that needs their statement.
+5. Decide where new sign-ups go. If the new system takes sign-ups, point the
+   website form and any automations at it. Awesomate's Contacts & email
+   doesn't host a sign-up form, so keep the form in a tool that records what
+   each person agreed to, and import from it.
+6. **Keep the old platform open for 30 days after its last send.**
+   Unsubscribe links in old emails must keep working for that long. At the
+   end, import once more to catch late unsubscribes, then close it.
+7. Leave the old platform's DNS records alone until it is closed.
+
+## Things that go wrong
+
+- Re-importing an old export after unsubscribes have happened, which
+  re-subscribes people. Suppressions always win.
+- Treating "pending" as subscribed. They never confirmed.
+- Importing a "leads" or "event attendees" list with no consent as if it
+  were subscribers.
+- Mapping every tag to a list, so people are "on" ten lists they never
+  chose.
+- Sending to the whole imported list on day one from a new address. Warm up
+  (see `deliverability.md`).

package/skill/awesomate-email/references/reporting.md

@@ -0,0 +1,53 @@
+# Reading results honestly
+
+Read this when reporting on a send, comparing sends, or when the owner asks
+"was that good?".
+
+## What each number means
+
+| Number | What it really tells you | Trust it? |
+|---|---|---|
+| Delivered | Accepted by the receiving server. Not "in the inbox". | Yes |
+| Bounced | Address doesn't exist (hard) or is temporarily full or blocked (soft). | Yes |
+| Clicked (people) | Unique people who clicked, after filtering inbox scanners. | Yes, the main signal |
+| Replied | People who wrote back. Small but strong. | Yes |
+| Booked, bought | Only if bookings or orders are connected and matched to the email. | Yes, when connected |
+| Unsubscribed | People who left. Read with the content and cadence. | Yes |
+| Complaints | People who pressed "Report spam". The one that hurts deliverability most. | Yes |
+| Opened | Apple Mail and many scanners open emails automatically, so this overstates reading by a lot. | Trend only |
+
+Never decide "who is engaged", pick A/B winners, or praise a send on opens.
+
+## Healthy ranges (rules of thumb, not benchmarks)
+
+- Bounces under about 2% of a send. Above that, the list has old or bad
+  addresses; stop and clean before sending again.
+- Complaints well under 0.1%. Gmail treats 0.3% as a hard line.
+- Unsubscribes: a fraction of a percent per send is normal. A spike means
+  the content didn't match the promise, or the cadence went up.
+- Clicks vary enormously by business and list. **Compare a business with its
+  own previous sends**, not with published industry averages, which are
+  built on opens and on businesses unlike this one.
+
+## What to do about what you see
+
+| You see | Likely cause | Do |
+|---|---|---|
+| Bounces jumped | An old or bought list was imported, or a typo-heavy form | Remove hard bounces, check the source, add form validation |
+| Complaints | People don't remember agreeing, or got more than promised | Check where those people came from; slow the cadence; make the reason-for-receiving line clearer |
+| Unsubscribes spiked | Off-promise content, or a sudden frequency jump | Send what the list promised; offer a less-often option |
+| Clicks dropping send on send | Same email every time, or too often | Fewer, more specific emails; send to a narrower group |
+| Gmail delivering to spam | Authentication, complaints, or a burst to cold addresses | See `deliverability.md` |
+
+## How to report to the owner
+
+One-line verdict, three numbers, at most three next steps, each tied to a
+number. Credit honestly: a click is not a booking unless the booking is
+connected.
+
+> Your best send so far. 1,398 people got it, 214 clicked (15.3%, up from
+> 14.7% in September), and nobody complained.
+>
+> Next: 46 people tagged hot water clicked the hot water
+> link. I'd send them a short personal note about the new heat pump option.
+> Want me to draft it?