Newsletter

Newsletter sign-up forms for Mailchimp or MailerLite, with a box on contact forms and a log of every sign-up — Mailchimp for WordPress's forms and settings are read as they are.

kitloom/newsletter · admins: kitloom/newsletter-filament, kitloom/newsletter-nova

Video lessons

Recorded in the Filament admin; the Nova admin works the same way.

• Connect Mailchimp
• Add a sign-up form

Newsletter sign-up forms: a visitor leaves an address and it goes to your mailing list at Mailchimp or MailerLite, with a confirmation email from the provider when you want one (double opt-in). A form goes into a post, a page or any sidebar — the newsletter zone a theme has — and a Contact Form 7 form can carry a "subscribe me" box. Every sign-up is in a log, with the provider's own words when one was refused. The data is Mailchimp for WordPress's (MC4WP): a site that signed people up with it under WordPress keeps its forms, its API key and its settings. The admin is kitloom/newsletter-filament or kitloom/newsletter-nova.

Setting up the provider

Connect Mailchimp

1. Newsletter → Settings → Provider: Mailchimp or MailerLite.
2. The key:
   • Mailchimp: Profile → Extras → API keys → Create A Key. It ends in its data center (…-us21).
   • MailerLite: Integrations → MailerLite API → Generate new token (the current MailerLite; a key of MailerLite Classic does not open it).
3. Save, then Test connection (at the top of the settings page in Filament; an action of Sign-ups in Nova). It says whether the provider let the site in and names your lists.

The key is encrypted with the application key before it is saved and never shown again; leave its field empty to keep it. If the application key changes, enter the key again. Each provider keeps its own key, so switching between them and back loses nothing. A form's lists are the provider's: after a switch, pick the lists of the new provider in each form.

A sign-up form

Add a sign-up form

Newsletter → Sign-up Forms → Add New Form. A new form has an email field and a button; three tabs:

• Fields — the form's HTML, without the <form> tag. Each input is named after the list's field: EMAIL (required), FNAME, LNAME, PHONE — Mailchimp's merge tags; for MailerLite, FNAME is name, LNAME is last_name, the rest are its field keys in capitals. A field the list does not have is left out. An input marked required must be filled.
• Settings — the lists the form signs up to; double opt-in (on: the provider emails a link to confirm, and the address is on the list only after it; off: at once — say on the form what the visitor agrees to); update existing subscribers (an address already on the list gets the new fields; off: it is left as it is and the visitor reads "already subscribed"); tags (Mailchimp; MailerLite has none); more required fields; a redirect after a sign-up; hiding the form after one.
• Messages — what the visitor reads after sending: signed up, updated, already subscribed, a wrong address, a missing field, spam, any other error. Empty — the default, in the page's language.

To let the visitor choose lists, add checkboxes named _mc4wp_lists[] with the lists' ids as values: only the form's own lists are taken.

Where the form goes

• In a post, a page or a Custom HTML widget: the form's shortcode, [mc4wp_form id="12"] (shown on the forms list; in the editor, «Shortcode» → Newsletter sign-up form). [mc4wp_form] without an id is the first form.
• In a sidebar: Appearance → Widgets → Newsletter sign-up form — a title and the form. In a theme with a newsletter zone (Parsec's "Parsec newsletter"), that is the place.
• In blocks: MC4WP's mailchimp-for-wp/form block, as WordPress saved it.

The form is MC4WP's markup — form.mc4wp-form, .mc4wp-form-fields, .mc4wp-response — so a theme that styled the plugin's forms fits. It is sent in the background and the answer appears in the form; a browser without JavaScript gets a page with the answer and a link back. The site's spam protection (kitloom/forms' honeypot and Cloudflare Turnstile, when set up) protects it like the site's other forms. One address may send 10 forms a minute (KITLOOM_NEWSLETTER_THROTTLE).

The box on contact forms

With kitloom/forms, a Contact Form 7 form signs its sender up when its "subscribe me" box is ticked. Put this into the form's template:

[acceptance mc4wp-subscribe optional]Sign me up for the newsletter[/acceptance]

A theme draws it as it draws any acceptance box of Contact Form 7 — Blade, Marketplace, Journal, Bureau, Pantry and Quire do; a theme that draws only text fields shows no box. MC4WP's own [mc4wp_checkbox] works too where the theme prints the form's markup (its label and "ticked at first" are on the settings page). The lists, the double opt-in and updating existing subscribers are on Newsletter → Settings → Box on contact forms. The address is the form's email field; a name field (your-name) fills the list's first and last name, and a field named mc4wp-FNAME (any merge tag after mc4wp-) fills that field. The sign-up is queued: the form does not wait for the provider. Nothing happens when the box is not ticked, or when the form failed to send.

MC4WP's boxes on the comment form and WooCommerce's checkout are kept as they were saved, not drawn yet.

The sign-up log

Newsletter → Sign-ups: every address sent to a list — the date, the list, where it came from (a sign-up form, a contact form) and how it ended:

• Subscribed — on the list.
• Asked to confirm — the provider emailed the confirmation link (double opt-in).
• Updated — was on the list and got the new fields.
• Already subscribed — was on the list and was left as it was.
• Failed — the provider refused it or could not be reached; the error is its answer (a fake-looking address, a list of another account, a wrong key). The visitor read the form's error message.

Entries are deleted after Keep entries, days (90 unless set; 0 keeps them all), once a day by the scheduler; php artisan newsletter:prune --days=30 does it by hand. The log is the site's own record: the list itself is at the provider.

Moving from Mailchimp for WordPress

The module reads the plugin's data where it is: the mc4wp option (the API key), the mc4wp-form posts (the fields as their content, _mc4wp_settings, the text_* messages), the mc4wp_integrations option (the Contact Form 7 box), the [mc4wp_form] shortcodes in posts, the Newsletter widgets and the blocks. Forms sign up at once. What MC4WP Premium kept (its log, styles builder, e-commerce) is not read; interest groups and the plugin's form styles are kept in the settings and not used.

Who may

Manage the newsletter opens the forms, the sign-up log and the settings: whoever holds the list's key can see who signed up anyway. The mc4wp option is protected — only the settings page writes it, never an agent or the general settings screens.

For AI agents

With kitloom/ai: newsletter_status (the provider, whether the key works, the lists with their ids — never the key), newsletter_forms (the forms with their shortcodes; one whole), newsletter_form_save (makes or changes a form) and newsletter_signups (the log, filtered by status, source or address). No tool signs anyone up: that is the visitor's own doing. All need Manage the newsletter; kitloom-newsletter.ai.register turns them off.

Webhooks

With kitloom/webhooks, the newsletter.subscribed topic sends each sign-up the provider took — the address, the provider, the list, the status and where it came from.

Personal data

With kitloom/privacy, Export Personal Data lists an address's entries of the sign-up log, and Erase Personal Data deletes them. The address stays on the provider's lists: the person unsubscribes with the link in any newsletter, or you remove them in the provider's account — the erasure says so.

Configuration

config/kitloom-newsletter.php (publish with php artisan vendor:publish --tag=kitloom-newsletter-config): the provider's timeout, and a switch for each part — shortcodes, widgets, routes (with throttle), integrations.contact_form_7, schedule, privacy, ai, webhooks, filament, nova.

For developers: Providers\Providers::current() is the provider with the saved key, Signups::subscribe() sends an address to lists and logs it, Events\Subscribed announces each sign-up the provider took; kitloom/forms' Kitloom\Forms\Events\SubmissionSent is what the contact form box listens to.