pretix-mailchimp 0.1.0__tar.gz

pretix_mailchimp-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+
+Copyright 2026 Julian Hammer
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

pretix_mailchimp-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+recursive-include pretix_mailchimp/static *
+recursive-include pretix_mailchimp/templates *
+recursive-include pretix_mailchimp/locale *
+include LICENSE
+exclude .gitlab-ci.yml

pretix_mailchimp-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: pretix-mailchimp
+Version: 0.1.0
+Summary: Mailchimp newsletter subscription with booking (opt-in)
+Author-email: Julian Hammer <julian.hammer@betreiberverein.de>
+Maintainer-email: Julian Hammer <julian.hammer@betreiberverein.de>
+License: Apache
+Project-URL: homepage, https://github.com/zam-haus/pretix-mailchimp
+Project-URL: repository, https://github.com/zam-haus/pretix-mailchimp
+Keywords: pretix
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Dynamic: license-file
+
+pretix Mailchimp Newsletter
+===========================
+
+This is a plugin for `pretix`_.
+
+Mailchimp newsletter subscription with booking (opt-in).
+
+Behavior
+--------
+
+* Activated on organizer level.
+* Applies to all events of the organizer by default.
+* Can only be disabled per event.
+* Shows an optional checkbox in the booking contact form.
+* Also shows an optional checkbox in the attendee/question form for every personalized order position, but only if the
+  event asks for email addresses per ticket.
+* If no checkbox is selected, nothing is sent to Mailchimp.
+* If selected, the contact is created or updated in the configured Mailchimp audience.
+* The contact is tagged with the main pretix event, not the subevent/date.
+* Existing contacts are not overwritten unnecessarily; the event tag is added.
+* If booking contact and attendee use the same email address in one order, the plugin avoids duplicate Mailchimp calls.
+
+Default public text::
+
+    ZAMgefasst, der Newsletter 1x pro Monat aus dem ZAM
+
+Installation
+------------
+
+Inside your pretix virtualenv::
+
+    pip install -e .
+
+Then restart pretix and enable the plugin on organizer level.
+
+Configuration
+-------------
+
+Go to the plugin settings on organizer level and configure:
+
+* Mailchimp API key
+* Mailchimp Audience/List ID
+* status for new contacts (``pending`` recommended for double opt-in)
+* tag template
+* public checkbox label, with translations
+* public help text, with translations
+
+Per event, go to event settings and use **Newsletter opt-in deaktivieren** if the opt-in should not be shown for that
+event.
+
+Opt-in behavior
+---------------
+
+The plugin stores and evaluates two independent opt-ins:
+
+* booking contact opt-in: saved in ``order.meta_info["contact_form_data"]``
+* attendee/position opt-in: saved in ``position.meta_info["question_form_data"]``
+
+This matters for events with non-personalized products: If pretix does not ask for attendee name/email per position, the
+booking contact can still explicitly subscribe.
+
+Mailchimp tag template placeholders
+-----------------------------------
+
+The tag template can use:
+
+* ``{organizer}`` - organizer slug
+* ``{event_slug}`` - event slug
+* ``{event}`` - event name
+* ``{event_id}`` - internal event id
+
+Example::
+
+    ZAM Veranstaltung: {event}
+
+or more stable::
+
+    pretix:{organizer}:{event_slug}
+
+Privacy note
+------------
+
+This plugin only transfers a contact after explicit opt-in. For new Mailchimp contacts, ``pending`` is the recommended
+default so Mailchimp sends a confirmation email. Existing unsubscribed contacts are not forcefully resubscribed by
+default; they only receive the event tag.
+
+Development setup
+-----------------
+
+1. Make sure that you have a working `pretix development setup`_.
+
+2. Clone this repository.
+
+3. Activate the virtual environment you use for pretix development.
+
+4. Execute ``python setup.py develop`` within this directory to register this application with pretix's plugin registry.
+
+5. Execute ``make`` within this directory to compile translations.
+
+6. Restart your local pretix server. You can now use the plugin from this repository for your events by enabling it in
+   the 'plugins' tab in the settings.
+
+This plugin has CI set up to enforce a few code style rules. To check locally, you need these packages installed::
+
+    pip install flake8 isort black
+
+To check your plugin for rule violations, run::
+
+    black --check .
+    isort -c .
+    flake8 .
+
+You can auto-fix some of these issues by running::
+
+    isort .
+    black .
+
+To automatically check for these issues before you commit, you can run ``.install-hooks``.
+
+
+License
+-------
+
+
+Copyright 2026 Julian Hammer
+
+Released under the terms of the Apache License 2.0
+
+
+
+.. _pretix: https://github.com/pretix/pretix
+.. _pretix development setup: https://docs.pretix.eu/en/latest/development/setup.html

pretix_mailchimp-0.1.0/README.rst

@@ -0,0 +1,132 @@
+pretix Mailchimp Newsletter
+===========================
+
+This is a plugin for `pretix`_.
+
+Mailchimp newsletter subscription with booking (opt-in).
+
+Behavior
+--------
+
+* Activated on organizer level.
+* Applies to all events of the organizer by default.
+* Can only be disabled per event.
+* Shows an optional checkbox in the booking contact form.
+* Also shows an optional checkbox in the attendee/question form for every personalized order position, but only if the
+  event asks for email addresses per ticket.
+* If no checkbox is selected, nothing is sent to Mailchimp.
+* If selected, the contact is created or updated in the configured Mailchimp audience.
+* The contact is tagged with the main pretix event, not the subevent/date.
+* Existing contacts are not overwritten unnecessarily; the event tag is added.
+* If booking contact and attendee use the same email address in one order, the plugin avoids duplicate Mailchimp calls.
+
+Default public text::
+
+    ZAMgefasst, der Newsletter 1x pro Monat aus dem ZAM
+
+Installation
+------------
+
+Inside your pretix virtualenv::
+
+    pip install -e .
+
+Then restart pretix and enable the plugin on organizer level.
+
+Configuration
+-------------
+
+Go to the plugin settings on organizer level and configure:
+
+* Mailchimp API key
+* Mailchimp Audience/List ID
+* status for new contacts (``pending`` recommended for double opt-in)
+* tag template
+* public checkbox label, with translations
+* public help text, with translations
+
+Per event, go to event settings and use **Newsletter opt-in deaktivieren** if the opt-in should not be shown for that
+event.
+
+Opt-in behavior
+---------------
+
+The plugin stores and evaluates two independent opt-ins:
+
+* booking contact opt-in: saved in ``order.meta_info["contact_form_data"]``
+* attendee/position opt-in: saved in ``position.meta_info["question_form_data"]``
+
+This matters for events with non-personalized products: If pretix does not ask for attendee name/email per position, the
+booking contact can still explicitly subscribe.
+
+Mailchimp tag template placeholders
+-----------------------------------
+
+The tag template can use:
+
+* ``{organizer}`` - organizer slug
+* ``{event_slug}`` - event slug
+* ``{event}`` - event name
+* ``{event_id}`` - internal event id
+
+Example::
+
+    ZAM Veranstaltung: {event}
+
+or more stable::
+
+    pretix:{organizer}:{event_slug}
+
+Privacy note
+------------
+
+This plugin only transfers a contact after explicit opt-in. For new Mailchimp contacts, ``pending`` is the recommended
+default so Mailchimp sends a confirmation email. Existing unsubscribed contacts are not forcefully resubscribed by
+default; they only receive the event tag.
+
+Development setup
+-----------------
+
+1. Make sure that you have a working `pretix development setup`_.
+
+2. Clone this repository.
+
+3. Activate the virtual environment you use for pretix development.
+
+4. Execute ``python setup.py develop`` within this directory to register this application with pretix's plugin registry.
+
+5. Execute ``make`` within this directory to compile translations.
+
+6. Restart your local pretix server. You can now use the plugin from this repository for your events by enabling it in
+   the 'plugins' tab in the settings.
+
+This plugin has CI set up to enforce a few code style rules. To check locally, you need these packages installed::
+
+    pip install flake8 isort black
+
+To check your plugin for rule violations, run::
+
+    black --check .
+    isort -c .
+    flake8 .
+
+You can auto-fix some of these issues by running::
+
+    isort .
+    black .
+
+To automatically check for these issues before you commit, you can run ``.install-hooks``.
+
+
+License
+-------
+
+
+Copyright 2026 Julian Hammer
+
+Released under the terms of the Apache License 2.0
+
+
+
+.. _pretix: https://github.com/pretix/pretix
+.. _pretix development setup: https://docs.pretix.eu/en/latest/development/setup.html

pretix_mailchimp-0.1.0/pretix_mailchimp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pretix_mailchimp-0.1.0/pretix_mailchimp/apps.py

@@ -0,0 +1,36 @@
+from django.utils.translation import gettext_lazy as _
+
+try:
+    from pretix.base.plugins import PLUGIN_LEVEL_ORGANIZER, PluginConfig
+except ImportError as exc:  # pragma: no cover
+    raise RuntimeError("Please use pretix 2025.7 or above to run this plugin.") from exc
+
+
+class PluginApp(PluginConfig):
+    name = "pretix_mailchimp"
+    verbose_name = _("Mailchimp newsletter opt-in")
+
+    class PretixPluginMeta:
+        name = _("Mailchimp newsletter opt-in")
+        author = _("Betreiberverein ZAM e.V.")
+        version = "0.2.0"
+        category = "INTEGRATION"
+        description = _(
+            "Adds newsletter opt-in fields for booking contacts and attendees during checkout "
+            "and syncs opted-in contacts to a Mailchimp audience with a tag for the main event."
+        )
+        visible = True
+        restricted = False
+        compatibility = "pretix>=2025.7"
+        level = PLUGIN_LEVEL_ORGANIZER
+        settings_links = [
+            (
+                (_("Mailchimp newsletter"),),
+                "plugins:pretix_mailchimp:settings",
+                {},
+            )
+        ]
+        navigation_links = []
+
+    def ready(self):
+        from . import signals  # noqa

pretix_mailchimp-0.1.0/pretix_mailchimp/defaults.py

@@ -0,0 +1,41 @@
+from i18nfield.strings import LazyI18nString
+from pretix.base.settings import settings_hierarkey
+
+DEFAULT_MAILCHIMP_LABEL = LazyI18nString(
+    {
+        "de": "ZAMgefasst abonnieren",
+        "de-informal": "ZAMgefasst abonnieren",
+        "en": "Subscribe to ZAMgefasst",
+    }
+)
+DEFAULT_MAILCHIMP_HELP_TEXT = LazyI18nString(
+    {
+        "de": "ZAMgefasst, der Newsletter 1x pro Monat aus dem ZAM",
+        "de-informal": "ZAMgefasst, der Newsletter 1x pro Monat aus dem ZAM",
+        "en": "ZAMgefasst, the monthly newsletter from ZAM",
+    }
+)
+
+# Organizer-level settings
+settings_hierarkey.add_default("mailchimp_api_key", "", str)
+settings_hierarkey.add_default("mailchimp_audience_id", "", str)
+settings_hierarkey.add_default("mailchimp_status_if_new", "pending", str)
+settings_hierarkey.add_default(
+    "mailchimp_tag_template",
+    "ZAM Veranstaltung: {event}",
+    str,
+)
+settings_hierarkey.add_default(
+    "mailchimp_label",
+    DEFAULT_MAILCHIMP_LABEL,
+    LazyI18nString,
+)
+settings_hierarkey.add_default(
+    "mailchimp_help_text",
+    DEFAULT_MAILCHIMP_HELP_TEXT,
+    LazyI18nString,
+)
+settings_hierarkey.add_default("mailchimp_timeout", 8, int)
+
+# Event-level opt-out. Default: active.
+settings_hierarkey.add_default("mailchimp_disabled", False, bool)

pretix_mailchimp-0.1.0/pretix_mailchimp/forms.py

@@ -0,0 +1,106 @@
+from django import forms
+from django.utils.translation import gettext_lazy as _
+from i18nfield.forms import I18nFormField, I18nTextarea, I18nTextInput
+
+
+class OrganizerMailchimpSettingsForm(forms.Form):
+    api_key = forms.CharField(
+        label=_("Mailchimp API key"),
+        required=False,
+        widget=forms.PasswordInput(render_value=False),
+        help_text=_(
+            "Required for the first configuration. Leave empty later to keep the existing key. "
+            "The data center is read from the suffix of the key, e.g. us21."
+        ),
+    )
+    audience_id = forms.CharField(
+        label=_("Mailchimp Audience/List ID"),
+        required=True,
+        help_text=_("The Mailchimp audience ID, also called list ID."),
+    )
+    status_if_new = forms.ChoiceField(
+        label=_("Status for new contacts"),
+        choices=[
+            ("pending", _("pending – double opt-in confirmation email")),
+            ("subscribed", _("subscribed – subscribe immediately")),
+        ],
+        help_text=_(
+            "For GDPR-sensitive setups, 'pending' is usually the safer default. "
+            "Existing contacts are not forcefully resubscribed by this plugin."
+        ),
+    )
+    tag_template = forms.CharField(
+        label=_("Mailchimp tag template"),
+        required=True,
+        help_text=_(
+            "Available placeholders: {organizer}, {event_slug}, {event}, {event_id}. "
+            "The tag is based on the main event, not the subevent/date."
+        ),
+    )
+    label = I18nFormField(
+        label=_("Public checkbox label"),
+        required=True,
+        widget=I18nTextInput,
+    )
+    help_text = I18nFormField(
+        label=_("Public checkbox help text"),
+        required=False,
+        widget=I18nTextarea,
+        widget_kwargs={"attrs": {"rows": 3}},
+    )
+    timeout = forms.IntegerField(
+        label=_("Mailchimp request timeout in seconds"),
+        required=True,
+        min_value=1,
+        max_value=30,
+    )
+
+    def __init__(self, *args, existing_api_key=False, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.existing_api_key = existing_api_key
+        if not existing_api_key:
+            self.fields["api_key"].required = True
+
+    def clean_api_key(self):
+        value = (self.cleaned_data.get("api_key") or "").strip()
+        if value and "-" not in value:
+            raise forms.ValidationError(
+                _(
+                    "Mailchimp API keys usually end with a data center suffix like '-us21'."
+                )
+            )
+        if not value and not self.existing_api_key:
+            raise forms.ValidationError(_("Please enter a Mailchimp API key."))
+        return value
+
+    def clean_tag_template(self):
+        value = (self.cleaned_data.get("tag_template") or "").strip()
+        if not value:
+            raise forms.ValidationError(_("Please enter a tag template."))
+        try:
+            value.format(
+                organizer="org",
+                event_slug="event",
+                event="Event name",
+                event_id=1,
+            )
+        except KeyError as exc:
+            raise forms.ValidationError(
+                _("Unknown placeholder in tag template: {placeholder}").format(
+                    placeholder="{" + str(exc.args[0]) + "}"
+                )
+            )
+        except Exception as exc:
+            raise forms.ValidationError(str(exc))
+        return value
+
+
+class EventMailchimpSettingsForm(forms.Form):
+    disabled = forms.BooleanField(
+        label=_("Disable newsletter opt-in for this event"),
+        required=False,
+        help_text=_(
+            "The organizer-level plugin is active by default for all events. "
+            "Check this only if this event should not show the Mailchimp opt-in."
+        ),
+    )

pretix_mailchimp-0.1.0/pretix_mailchimp/locale/de/LC_MESSAGES/django.po

@@ -0,0 +1,12 @@
+msgid ""
+msgstr ""
+"Project-Id-Version: \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2017-03-07 19:01+0100\n"
+"PO-Revision-Date: \n"
+"Last-Translator: Julian Hammer\n"
+"Language-Team: \n"
+"Language: de\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"

pretix_mailchimp-0.1.0/pretix_mailchimp/locale/de_Informal/LC_MESSAGES/django.po

@@ -0,0 +1,12 @@
+msgid ""
+msgstr ""
+"Project-Id-Version: \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2017-03-07 19:01+0100\n"
+"PO-Revision-Date: \n"
+"Last-Translator: Julian Hammer\n"
+"Language-Team: \n"
+"Language: de\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"

pretix_mailchimp-0.1.0/pretix_mailchimp/mailchimp.py

@@ -0,0 +1,97 @@
+from typing import Optional
+
+import hashlib
+import requests
+from dataclasses import dataclass
+
+
+class MailchimpConfigurationError(Exception):
+    pass
+
+
+class MailchimpAPIError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class MailchimpConfig:
+    api_key: str
+    audience_id: str
+    status_if_new: str = "pending"
+    timeout: int = 8
+
+    @property
+    def data_center(self) -> str:
+        if "-" not in self.api_key:
+            raise MailchimpConfigurationError(
+                "Mailchimp API key does not contain a data center suffix."
+            )
+        return self.api_key.rsplit("-", 1)[1]
+
+    @property
+    def base_url(self) -> str:
+        return f"https://{self.data_center}.api.mailchimp.com/3.0"
+
+    def subscriber_hash(self, email: str) -> str:
+        return hashlib.md5(email.strip().lower().encode("utf-8")).hexdigest()
+
+
+class MailchimpClient:
+    def __init__(self, config: MailchimpConfig):
+        self.config = config
+
+    def _request(self, method: str, path: str, json: Optional[dict] = None):
+        url = f"{self.config.base_url}{path}"
+        try:
+            response = requests.request(
+                method,
+                url,
+                auth=("pretix", self.config.api_key),
+                json=json,
+                timeout=self.config.timeout,
+                headers={"Content-Type": "application/json"},
+            )
+        except requests.RequestException as exc:
+            raise MailchimpAPIError(str(exc)) from exc
+
+        if response.status_code >= 400:
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = {"detail": response.text}
+            raise MailchimpAPIError(
+                f"Mailchimp API returned {response.status_code}: {payload}"
+            )
+
+        if response.status_code == 204:
+            return None
+
+        if response.content:
+            return response.json()
+        return None
+
+    def upsert_member_without_resubscribe(self, email: str):
+        """Create the contact if missing, but do not force-resubscribe existing contacts."""
+        subscriber_hash = self.config.subscriber_hash(email)
+        path = f"/lists/{self.config.audience_id}/members/{subscriber_hash}"
+        return self._request(
+            "PUT",
+            path,
+            json={
+                "email_address": email.strip(),
+                "status_if_new": self.config.status_if_new,
+            },
+        )
+
+    def add_tag(self, email: str, tag: str):
+        subscriber_hash = self.config.subscriber_hash(email)
+        path = f"/lists/{self.config.audience_id}/members/{subscriber_hash}/tags"
+        return self._request(
+            "POST",
+            path,
+            json={"tags": [{"name": tag.strip(), "status": "active"}]},
+        )
+
+    def upsert_and_tag(self, email: str, tag: str):
+        self.upsert_member_without_resubscribe(email)
+        self.add_tag(email, tag)