=== Corantr Postbag ===
Contributors: hyncaconsulting
Tags: newsletter, mailing list, email, subscribe, double opt-in
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 0.11.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Sign-up forms and a block for your Corantr Postbag lists. People confirm on your own site, and your site's email can go out from your own domain.

== Description ==

Corantr Postbag connects your WordPress site to [Corantr Postbag](https://corantr.com/postbag), the mailing-list service. Corantr keeps your lists, records each person's consent and sends the email. This plugin is the part on your website.

**Sign-up forms that suit your theme**

* A **Postbag signup** block for the block editor: choose a list, a title, the button text and whether to ask for a name, with a live preview.
* The `[postbag_subscribe list="your-list"]` shortcode for classic themes and page builders.
* Opt-ins from UiCore Elements contact forms that carry a ticked opt-in box.
* For developers: a REST endpoint (`POST /wp-json/postbag/v1/subscribe`) and `\Postbag\Api::subscribe()` for other plugins.

Forms are lightly styled so they take your theme's look. Every form has a hidden honeypot field and per-visitor and per-address rate limits, so nobody can flood a stranger with confirmation emails.

**Confirming happens on your site**

Double opt-in links take people to a page on your own website, drawn inside your theme, not to a site they don't recognise. Opening the link shows a "Yes, subscribe me" button, so email security scanners that open links can't confirm anyone. You can tailor the wording for each list in Corantr, and in WordPress under **Corantr → Postbag → Settings → Confirmation page** (a heading, an introduction and a page to go to after confirming). A theme can also supply its own `postbag/confirm.php` or `postbag/unsubscribe.php` template. Unsubscribing works the same way.

**Your list is on your website too**

The plugin keeps a read-only copy of your Corantr lists in WordPress, refreshed every 15 minutes, with unsubscribes applied. You can see it under **Lists** and **Subscribers**. WordPress's own personal-data export and erase tools cover it.

**Nothing is lost when Corantr can't be reached**

Sign-ups made while Corantr can't be reached wait on your site and are sent in order on the next try.

**Your site's own email, from your own domain (optional)**

Switch on "Send this site's own email through Corantr" and the email WordPress and your other plugins send (password resets, form notices, order emails) goes out through Corantr from your organisation's verified domain. Several recipients, Cc, Bcc, Reply-To and attachments are all carried. Anything Corantr can't take is sent by WordPress as before. A **Mail log** shows recent emails (never their content), and **Send a test email** checks the route.

You need a Corantr account with Postbag. See [corantr.com/postbag](https://corantr.com/postbag).

== External services ==

This plugin talks to one service: **Corantr Postbag** (https://corantr.com), run by Hynca Consulting Ltd. Terms: https://corantr.com/terms. Privacy: https://corantr.com/privacy.

Nothing is sent until you connect the site with a key from your Corantr account. After that, each call carries the key, the plugin's version and your site's address, and:

* **When you connect, or press "Check connection",** it asks Corantr to confirm the key. Corantr answers with the site, organisation, sending domain and number of lists.
* **When someone signs up** through the block, the shortcode, the REST endpoint, a UiCore form opt-in or another plugin, and "Keep this site's lists in Corantr" is on, it sends the list, the person's email address, their name if given, the page they signed up on, their IP address and their browser's user agent, so Corantr can record consent and send any confirmation email.
* **Every minute, while connected,** it sends any sign-ups that were waiting because Corantr couldn't be reached.
* **Every 15 minutes, while connected,** it asks Corantr for the site's lists and the changes to their members since the last check (email addresses, names, subscription status and when consent was given), to keep the copy on your site.
* **When someone opens a confirm or unsubscribe link from a Corantr email and presses the button,** it sends the link's token, with their IP address and browser's user agent for the consent record, and shows Corantr's answer.
* **Only if "Send this site's own email through Corantr" is on,** each email WordPress sends goes to Corantr to be sent: its recipients, Cc, Bcc, Reply-To, sender, subject, body, attachments and any `List-*` or `X-*` headers.

You can disconnect at any time under **Corantr → Postbag → Settings**.

== Installation ==

1. Install and activate the plugin.
2. In Corantr, open **Postbag → Connect WordPress** and copy the key. One key connects each of your account's sites.
3. In WordPress, open **Corantr → Postbag**, paste the key and press **Connect**. If the Corantr Media Desk plugin is already connected on the site, Postbag uses its key and there is nothing to paste.
4. Switch on **Keep this site's lists in Corantr** (and, if you want it, **Send this site's own email through Corantr**), then press **Save settings**.
5. Add the **Postbag signup** block, or the `[postbag_subscribe list="your-list"]` shortcode, where you want the form.

Behind Cloudflare or another proxy, add `define( 'PB_CLIENT_IP_HEADER', 'HTTP_CF_CONNECTING_IP' );` to `wp-config.php` (with your proxy's header) so rate limits apply to each visitor rather than to the proxy.

== Frequently Asked Questions ==

= Do I need a Corantr account? =

Yes. Corantr keeps the lists and sends the email; this plugin connects your site to it. Without a connection, the forms sign nobody up and say that sign-ups aren't open just now.

= Where do people confirm their subscription? =

On your own website. The link in the confirmation email opens a page in your theme with a button to press.

= Does it send email from my server? =

No list or campaign email is sent from WordPress: Corantr sends it. Only if you switch on "Send this site's own email through Corantr" does your site's own email (password resets and so on) go through Corantr, from your verified domain.

= Does it use a CAPTCHA? =

Not a third-party one. Every form has a hidden honeypot field, and sign-ups are rate limited per visitor and per email address.

= What happens to the data if I delete the plugin? =

Deleting the plugin removes its log of recent emails and its old settings. It keeps the copy of your lists (and any consent records from older versions) on purpose, so that a mistaken click can't destroy them. To remove them, drop the `pb_` tables and options yourself. Your lists in Corantr aren't affected either way.

= Can I change how the form looks? =

The form uses your theme's styles. Its parts carry `postbag-subscribe` classes, and the confirm and unsubscribe pages `postbag-page` classes, so your theme can style them.

== Screenshots ==

1. Settings: the connection, your lists, site email and website forms.
2. The Postbag signup block in the block editor, with its settings.
3. The confirm page, on your own site and in your theme.
4. The copy of your lists in WordPress.
5. The Mail log of your site's recent email.

== Changelog ==

= 0.11.1 =
* Moving from a GitHub download: while the older copy in the `postbag` folder is active, whatever its version, this copy waits and says so, so the two never run together.

= 0.11.0 =
* First release on WordPress.org. Licensed GPLv2 or later.
* The text domain is now `corantr-postbag`, matching the plugin's WordPress.org address.
* The Corantr Overview shows WordPress's own automatic-update setting for this plugin.

= 0.10.1 =
* The confirm page's button stays readable whatever the theme's button styles.

= 0.10.0 =
* Confirm and unsubscribe pages on your own site, with wording you can tailor.
* The Postbag signup block.

= 0.9.2 =
* The Mail log, and Send a test email.

= 0.9.0 =
* Connect with a key checked by Corantr, and disconnect.

== Upgrade Notice ==

= 0.11.0 =
First WordPress.org release. If you installed Postbag from a GitHub download, install this one, then deactivate and delete the old "Corantr Postbag" copy in the `postbag` folder. Your settings, connection and the copy of your lists are kept; only the Mail log starts afresh.
