Concepts

Concepts#

Acumbamail Service Concepts with Plone/Volto

Overview#

Acumbamail is a cloud-based Email Marketing and Marketing Automation platform that provides services such as:

  • Newsletter management

  • Contact and subscriber management

  • Marketing automation

  • Subscription forms

  • Landing pages

  • Transactional email

  • SMS campaigns

  • Campaign analytics

When integrated with Plone and Volto, Acumbamail can be used to collect subscribers, synchronize contacts, automate email campaigns, and personalize communications based on user interactions.

Architecture#

                    +----------------------+
                    |      Volto UI        |
                    | (React Frontend)     |
                    +----------+-----------+
                               |
                               | REST API
                               |
                    +----------v-----------+
                    |       Plone          |
                    |  Business Logic      |
                    +----------+-----------+
                               |
                     HTTP REST API
                               |
                    +----------v-----------+
                    |     Acumbamail API   |
                    +----------+-----------+
                               |
                 Email Marketing Platform

Main Concepts#

1. Account#

The Acumbamail account represents the organization using the service.

It contains:

  • Mailing lists

  • Subscribers

  • Campaigns

  • Forms

  • Automation workflows

  • Statistics

2. API Key#

The API Key is used to authenticate requests from Plone.

Example:

Authorization: Bearer YOUR_API_KEY

Recommendations:

  • Never expose it in Volto.

  • Store it only in the Plone backend.

  • Load it from environment variables.

Example:

ACUMBAMAIL_API_KEY=xxxxxxxxxxxxxxxx

3. Lists#

A List is a collection of subscribers.

Examples:

  • Newsletter

  • Customers

  • Events

  • Employees

Typical operations:

  • Create subscriber

  • Remove subscriber

  • Update subscriber

  • Query subscriber

Example

Newsletter Subscribers

4. Subscribers#

A subscriber represents one contact.

Typical fields

Field

Description

email

Email address

name

Full name

surname

Last name

phone

Optional phone

language

Preferred language

custom fields

Organization-specific data

Example

{
  "email": "john@example.com",
  "name": "John",
  "surname": "Doe"
}

5. Double Opt-in#

Recommended for GDPR compliance.

Workflow

User
 ↓
Subscription Form
 ↓
Confirmation Email
 ↓
User Confirms
 ↓
Subscriber becomes Active

Advantages

  • Better email quality

  • GDPR compliance

  • Lower spam complaints

6. Forms#

Acumbamail allows creation of subscription forms.

With Plone there are two approaches.

Embedded Form#

Using Acumbamail HTML.

Pros

  • Very simple

Cons

  • Limited customization

Native Plone Form#

Preferred.

Workflow

Volto Form
        ↓
REST API
        ↓
Plone
        ↓
Acumbamail API

Advantages

  • Better UX

  • Validation

  • Security

  • Analytics

  • Integration with workflows

Campaigns#

Campaigns are email messages sent to subscribers.

Possible campaign types

  • Newsletter

  • Promotions

  • Announcements

  • Invitations

Campaign creation is usually performed directly inside Acumbamail.

Plone normally triggers subscriber synchronization.

Segments#

Subscribers can be divided into segments.

Examples

Customers

Employees

Spanish speakers

Premium users

Event attendees

Useful for personalized communications.

Custom Fields#

Custom fields store organization-specific information.

Example

Field

Company

Country

Department

Membership Level

These can be synchronized from Plone.

Tags#

Tags classify subscribers.

Examples

volunteer

customer

speaker

vip

donor

Useful for automation.

Automation#

Acumbamail supports automated workflows.

Example

New subscriber
        ↓
Welcome email
        ↓
Wait 3 days
        ↓
Send resources
        ↓
Wait 7 days
        ↓
Request feedback

Transactional Emails#

Different from campaigns.

Examples

  • Password reset

  • Registration confirmation

  • Purchase confirmation

  • Invoice delivery

These are typically triggered directly from Plone.

Statistics#

Acumbamail provides metrics such as

  • Delivered

  • Open rate

  • Click rate

  • Bounce rate

  • Unsubscribe rate

These statistics can be displayed inside Plone if desired.

Integration Patterns#

Pattern 1#

Newsletter Subscription

Volto Form

↓

Plone REST Endpoint

↓

Acumbamail API

↓

Subscriber Added

Pattern 2#

Registration Synchronization

User Registration

↓

Plone User Created

↓

Subscriber Created

↓

Welcome Automation

Pattern 3#

CRM Synchronization

CRM

↓

Plone

↓

Acumbamail

REST Integration#

Typical backend flow

Volto

↓

POST /newsletter

↓

Plone REST Service

↓

Acumbamail API

↓

Response

↓

Volto

Example JSON Payload#

{
  "email": "user@example.com",
  "name": "John",
  "surname": "Doe",
  "list": "Newsletter"
}

Error Handling#

Common validations

  • Invalid email

  • Already subscribed

  • Invalid API key

  • Rate limit exceeded

  • Network timeout

Backend should return meaningful messages.

Security Recommendations#

Never expose the API Key#

Correct

Volto

↓

Plone

↓

Acumbamail

Incorrect

Volto

↓

Acumbamail

Validate Input#

Validate

  • email

  • required fields

  • duplicates

before calling the API.

HTTPS#

Always communicate using HTTPS.

Logging#

Log

  • successful subscriptions

  • failed requests

  • API errors

Avoid logging API keys.

GDPR Considerations#

Recommended

  • Explicit consent checkbox

  • Privacy policy link

  • Double Opt-in

  • Right to unsubscribe

  • Right to delete subscriber

  • Consent timestamp

Suggested Plone Components#

Possible implementation

acumbamail/
│
├── browser/
├── services/
├── subscribers/
├── adapters/
├── interfaces.py
├── api.py
├── utils.py
└── configure.zcml

Suggested Volto Components#

src/
│
├── components/
│     └── NewsletterForm
│
├── hooks/
│
├── services/
│
├── helpers/
│
└── config/

Best Practices#

  • Keep the API key only in Plone.

  • Use REST services for communication.

  • Implement Double Opt-in.

  • Handle duplicate subscriptions gracefully.

  • Synchronize custom fields.

  • Log integration errors.

  • Retry transient API failures.

  • Monitor API rate limits.

  • Use asynchronous tasks for bulk synchronization.

  • Follow GDPR and local privacy regulations.

References#

  • Acumbamail API Documentation

  • Plone REST API Documentation

  • Volto Developer Documentation

  • Plone Backend Developer Documentation

Contents