fluentcrm-custom-optin-forms

FluentCRM custom subscription and double opt-in forms

Use this skill for a public form or API that owns its user interface but stores contacts in FluentCRM. Keep the transport, consent policy, CRM mutation, email request, and confirmation side effects separate.

Read implementation-contract.md before writing the endpoint or changing an existing contact's status.

Core contract

FluentCrmApi('contacts')->createOrUpdate() does not send a double opt-in email. The canonical core flow is:

$contact = FluentCrmApi('contacts')->createOrUpdate([
    'email'  => sanitize_email($email),
    'status' => 'pending',
    'source' => 'my-plugin',
    'lists'  => $serverOwnedListIds,
    'tags'   => $serverOwnedTagIds,
], false, false);

if ($contact && $contact->status === 'pending') {
    $contact->sendDoubleOptinEmail();
}

FluentCRM then builds its tokenized confirmation URL, handles the public confirmation request, changes pending to subscribed, resumes applicable funnels, records a system note, and fires fluent_crm/subscriber_confirmed_via_double_optin. Do not create a second token, confirmation table, or confirmation route around this lifecycle.

Double opt-in, global/list-specific email settings, and the confirmation hook are Free-core features. Site code and add-ons may filter post-confirmation routing, but a custom signup integration must not require Pro for the base flow.

Workflow

1. Require a clear affirmative consent value. Store the exact consent text or policy version and submission timestamp in the application's audit store when that evidence matters; FluentCRM does not preserve the original form wording.
2. Validate and normalize the email, then sanitize only explicitly mapped name and custom fields. Never accept status, user_id, source, list IDs, tag IDs, or detach operations directly from the public payload.
3. Resolve public choices through a server-owned map and verify every resulting list/tag exists. Passing strings to FluentCRM's attach helpers can create new lists/tags; numeric IDs are not an authorization boundary.
4. Inspect the existing contact before writing and apply the status matrix below.
5. Call createOrUpdate() with $forceUpdate = false. Attach the DOI-driving list before sending so list-specific settings can be selected.
6. Call sendDoubleOptinEmail() only when the resulting status is pending.
7. Return the same generic accepted response for existing, new, suppressed, and throttled addresses. Log bounded operational failures privately.
8. Put verified-only tags or downstream work on the confirmation hook, not on the initial form request.