Newsletter setup

What the platform does and doesn't do: a CRM form has no setting that adds the person to a customer group. A signup lands as a record in the form's collection, and that's all. Moving signups into the subscriber group is a separate step. The AI runs it when asked ("add the new newsletter signups to the group"), or a person does it. Say this plainly to the person. Don't promise that signups join the list by themselves.

A broadcast sends real email to real people, and there is no test mode. This skill stops at a draft. Putting the signup link on a live page and sending are the person's decisions.

Ask first

• The newsletter's name, e.g. "Monthly news". It names the group, the form and the drafts.
• What to ask on the form. Email is required. Name is optional, and only worth asking if the emails will greet people by name.
• From which address? One of the business's email accounts.
• The first issue. What it should say, or the points for the AI to write up.
• Where the link goes on the site. Only so the person knows the next step. The AI doesn't publish pages.

Steps

1. Email Accounts: the sender

Find the email account (email_account) the newsletter should come from. A broadcast can send only from an account that:

• is active (isActive is not false);
• is not taken out of rotation (autoRotate is not false);
• is not a hosted mailbox. A hosted mailbox can't bulk-send, and a send from one is refused.

Hands on: the account's sk. Check: the account exists and qualifies. If there is none, say: "There is no email account that can send newsletters. Add one in Email Accounts (/email-accounts). I can't connect one for you." Then carry on. The draft can still be saved, but it can't be sent until an account is added.

2. Customers & Benefits: the subscriber group

Find the customer group (customer_group) by name. If there isn't one, create it:

Never make it dynamic, because a broadcast does not apply a dynamic group's rules.

Hands on: the group's sk. Check: open it (/customers-benefits?view=groups&groupId=<sk>).

3. Collection builder: where signups land

Create a collection named newsletter_signup (title "Newsletter signup") with these fields:

• email: email, required
• name: short text, only if the person wants it

Save the collection itself (the builder's Save, or a collection record create).

Hands on: the collection's name. Check: open it (/collection-builder with name = newsletter_signup). The fields are there with their types.

4. CRM Forms: the signup form

Create a CRM form (crm_form):

Get the share link with GET site/base-url?feature=forms. The form's link is that url followed by ?form=<form name>. If no url comes back, the business's website doesn't have Forms switched on. The reply says to enable Forms in Site Features on the default site. That changes the live site, so ask before doing it.

Hands on: the form's name and its share link. Check: open the form (/crm-form?uid=<form name>). Setup shows the collection and the share link. Preview it.

5. Customers & Benefits: signups into the group

This runs now for any signups already there, and again whenever the person asks.

Find the records in newsletter_signup (page through all of them, or only those since the last run). For each email:

• if a contact (customer) already has that email, add the contact's sk;
• otherwise, add the email address itself. A group's list may hold plain addresses, and a broadcast sends to them.

Write the group's contacts list as its current entries plus the new ones, with no duplicates, sent as the whole list. This sends nothing to anyone.

Don't create a contact for each signup, because creating a contact emails that person a welcome message. Don't add the group's name to contacts' own groups, because saving a contact emails them that their profile changed.

Hands on: how many were added. Check: POST broadcast/audience/count with { lists: [<group sk>] }. The count is the group's members with a valid email, minus anyone who has unsubscribed, bounced or complained.

6. Broadcast: the first newsletter, as a draft

Create an email_broadcast record, the same write as the composer's Save Draft:

Personal fields: a broadcast fills in {{firstName}}, {{lastName}}, {{name}}, {{email}} and {{phone}}, and any field the composer's Personalize button inserts ({{data.<namespace>.<field>}}), from each contact's own record. A contact without that field gets it empty, never the braces — so write the greeting so it still reads well blank ("Hi {{firstName}}," reads as "Hi ,"; prefer "Hello," when names may be missing).

Never set status to pending or scheduled, and never add a schedule. A sweep every five minutes sends anything pending or due. Never use the list all-contacts. Never call POST broadcast/<id>/send.

A group with no one in it yet is fine for a draft. A send to it would fail with No recipients found.

Hands on: the broadcast's sk and the audience count. Check: read it back. status is draft, selectedLists holds the group's sk, and there is no schedule. Open it (/broadcast?openId=<sk>).

Stop

Each of these goes out to the public or to real people. Each one is the person's decision:

• Putting the link on the website. The person adds the share link to a page (a button or menu item) and publishes the page. Turning on the site's Forms feature also counts.
• Sending the newsletter. They press Send or Schedule in the composer. If they say "send it" in chat, repeat the audience count and the sender, and send only after a clear yes. Bulk email also needs the business's bulk-email agreement. Without it the send fails.

Every email gets an unsubscribe link added automatically, so the AI doesn't add one. Anyone who unsubscribes is left out of every later broadcast, even while still on the group's list.

When it's done

Tell the person:

• the sender, or that one must be added in Email Accounts before anything can be sent;
• the group and its audience count;
• the form and its share link, and that the link still has to be placed on the site;
• that new signups don't join the group by themselves, so they should ask "add the new newsletter signups" before each issue;
• the draft's name and subject, and that nothing has been sent.

Don'ts

• Don't say signups join the list automatically.
• Don't publish a page, turn on a site feature, or send without a yes.
• Don't put facts in the newsletter that the person didn't give you: dates, prices, offers, links. Leave a clearly marked gap (e.g. [link to the event page]).