Forms and autoresponders

Superfunky provides public JSON submission endpoints and private WordPress inboxes. Notification transport, mailing-list synchronisation, file handling, and customer autoresponders are separate layers that must each be verified.

Submission flow

Purpose	Endpoint
Newsletter consent	POST /wp-json/funkycommerce/v1/newsletter-submissions
Contact, enquiry, or application form	POST /wp-json/funkycommerce/v1/form-submissions

Successful requests return HTTP 201 with {"received":true}. The routes are public so visitors can submit without a WordPress account.

The storefront newsletter helper sends:

{
  "email": "customer@example.com",
  "consent": true,
  "source": "footer",
  "language": "en",
  "website": ""
}

website is the honeypot and must remain empty. Newsletter requests require a valid email address and explicit consent.

A generic form integration sends:

{
  "formId": "contact",
  "formName": "Contact form",
  "subject": "Product question",
  "email": "customer@example.com",
  "source": "https://shop.example.com/contact",
  "language": "en",
  "fields": {
    "Name": "Example customer",
    "Message": "Please send more information.",
    "Marketing consent": false
  },
  "website": ""
}

The released frontend helper supports text, number, and boolean field values. The backend accepts at most 50 values, limits labels to 120 characters, and limits each value to 5,000 characters. formId is required.

Free setup

In Appearance > FunkyCommerce > Forms & Newsletter:

1. enable honeypot protection;
2. set the administrator notification email;
3. confirm the public form shows a clear success and error state;
4. submit one test from the deployed storefront.

The current backend applies a privacy-minimised rate limit of 10 requests per submission type per 15 minutes. Treat this as abuse reduction, not a replacement for CDN/WAF protection.

Valid generic forms are stored privately, then the notification address is called through WordPress wp_mail. A failed notification does not mean the inbox record was lost.

Private inboxes

Administrators with manage_options can use:

• Appearance > Newsletter Submissions;
• Appearance > Form Submissions.

Records can be marked unread, read, archived, spam, or not spam. Permanent deletion does not use the trash. CSV exports neutralise spreadsheet-formula prefixes, but exported files still contain personal data and need access controls.

Superfunky does not impose an automatic retention period. Define one in the store's privacy policy, periodically export only what is required, and permanently delete expired records.

Akismet and spam

Superfunky Pro can send submissions to an active, configured Akismet installation.

• Detected spam is retained in the Spam view.
• Spam does not trigger the administrator notification or connector hook.
• Mark as spam and Not spam train Akismet when its API is available.
• The honeypot and rate limit should remain enabled alongside Akismet.

Test with provider-approved spam test data rather than real abusive content.

Providers and double opt-in

Pro exposes newsletter provider, Mailchimp credentials/audience, and double-opt-in settings. The inspected core runtime stores newsletter consent but does not itself perform Mailchimp/MailPoet synchronisation.

Use the Control Center Runtime coverage result and the active Pro/provider connector to verify all of the following before launch:

1. only non-spam, explicitly consented records are transferred;
2. source and language mapping are correct;
3. double opt-in email and confirmation status are provider-owned;
4. duplicate signups and provider errors have a defined outcome;
5. unsubscribe and deletion requests propagate to every owning system.

Do not call a stored WordPress record "subscribed" until the selected provider confirms it.

Autoresponders

The Pro order subject/template and form-autoresponder fields are configuration for the active companion or delivery integration. The core form endpoint does not send a customer autoresponder.

When an autoresponder is implemented:

• send only after successful storage and spam checks;
• use the submitted email only after validation;
• escape customer-controlled fields in HTML;
• include the correct language, sender identity, and reply-to policy;
• avoid echoing sensitive form answers back by email;
• log a provider message ID or explicit failure without exposing secrets.

Complete SMTP and email delivery before enabling autoresponders.

File uploads

The generic form endpoint accepts JSON forms and multipart forms with bounded file attachments. Allowed extensions, detected MIME types, file count, and file size are validated before the complete submission is accepted. Attachments are renamed, stored outside every public root, and exposed only through the capability- and nonce-protected administrator download action.

The default directory is funkycommerce-private-submissions beside the server document root. WordPress must be able to create and write that directory. It intentionally rejects storage inside the document root, WordPress root, or wp-content, even when that location is writable. See Security for legacy-path and Nginx protection requirements.

Fix private storage on a hardened Bitnami instance

The warning Private form storage is unavailable. means PHP could not create the private directory. A standard Bitnami WordPress image serves /opt/bitnami/wordpress, so the expected sibling directory is /opt/bitnami/funkycommerce-private-submissions. Do not solve this by making /opt/bitnami, WordPress, or wp-content generally writable.

First inspect the running workers and identify their unprivileged user and group. Ignore the root-owned master process. Bitnami commonly uses daemon:daemon, but confirm the live instance:

ps -eo user,group,pid,ppid,comm,args \
  | grep -E '[p]hp-fpm|[a]pache2|[h]ttpd'

Set the confirmed worker identity, then create only the private directory:

WORDPRESS_ROOT=/opt/bitnami/wordpress
PRIVATE_STORAGE=/opt/bitnami/funkycommerce-private-submissions
PHP_USER=daemon
PHP_GROUP=daemon

sudo install -d \
  -o "$PHP_USER" \
  -g "$PHP_GROUP" \
  -m 0700 \
  "$PRIVATE_STORAGE"

sudo -u "$PHP_USER" test -r "$PRIVATE_STORAGE"
sudo -u "$PHP_USER" test -w "$PRIVATE_STORAGE"
sudo -u "$PHP_USER" test -x "$PRIVATE_STORAGE"
sudo stat -c '%U:%G %a %n' "$PRIVATE_STORAGE"

All three test commands must exit successfully, and stat should report the selected service account with mode 700. If the instance uses a custom document root, resolve a different sibling directory and set it through the funkycommerce_submission_storage_directory filter in deployment-owned code. The resolved directory must remain outside the document root, ABSPATH, and WP_CONTENT_DIR.

Force WordPress to repeat its readiness check, trigger one web request, and inspect the result:

wp --path="$WORDPRESS_ROOT" option update funkycommerce_submission_storage_ready no
curl -fsS -o /dev/null https://cms.example.com/
wp --path="$WORDPRESS_ROOT" option get funkycommerce_submission_storage_ready

if STORAGE_ERROR="$(
  wp --path="$WORDPRESS_ROOT" option get \
    funkycommerce_submission_storage_error 2>/dev/null
)"; then
  printf 'Storage error: %s\n' "$STORAGE_ERROR"
else
  echo 'No stored storage error.'
fi

The ready value must be yes, followed by No stored storage error. A successful readiness check deletes the stored warning. If it still contains an error, re-check the actual worker account, every parent directory's execute permission, the resolved document root, and PHP filesystem restrictions such as open_basedir.

Finally submit a harmless multipart test from the deployed form and verify:

1. the request returns HTTP 201 and appears once in Appearance > Form Submissions;
2. the attachment exists under the private directory with mode 600;
3. an authorised administrator can download it through WordPress;
4. its filesystem path is not returned by the public endpoint and no direct public URL

serves it;

1. permanent deletion removes the stored attachment.

If wp-content/funkycommerce-private-submissions exists from an older release, leave its web-server deny rule in place until WordPress has moved every attachment and the administrator download test passes. Remove the empty legacy directory only after that verification.

For a customer-facing implementation pattern, see Sample form with uploads and redirect.

Acceptance checklist

• Empty honeypot succeeds and a filled honeypot is rejected.
• Invalid emails and missing newsletter consent are rejected.
• Rate limiting returns a visible retry message.
• A valid record appears once in the correct private inbox.
• Spam is stored without notification or provider transfer.
• Administrator mail arrives through the configured transport.
• CSV, archive, spam/ham, and permanent deletion behave as expected.
• Private attachment storage is writable only by the confirmed PHP service account.
• Provider, double-opt-in, autoresponder, and upload behaviour is tested independently

when enabled.

• The privacy notice names every destination and the retention period.

Next: sample form with uploads and redirect.