Use App activity for trial emails

FloKit uses App activity for Trial not converted → trial-value only. Billing reminders keep their existing schedule. The connection reads activity; your endpoint does not send emails or change subscriptions.

Prepare the endpoint

Provide a public HTTPS endpoint that accepts POST requests with JSON and a client-issued, read-only API key in Authorization: Bearer <api-key>. Use a URL without credentials, a query string, or a fragment. Redirects and private-network addresses are refused. The endpoint must resolve to public IPv4. Each request contains up to 200 users from the same App and environment:

{
  "users": [
    {
      "customer_id": "example-user-123",
      "trial_started_at": "2026-10-05T10:00:00.000Z"
    }
  ]
}

customer_id is the exact, case-sensitive customer reference supplied to FloKit by the accepted payment trial event (identity.userRef). Confirm that your endpoint maps that reference to the correct App account. Do not match by email or assume a payment provider’s customer ID is the same reference. FloKit retains the reference for new accepted payment trials while the lookup is enabled. Existing trials without a retained reference use the approved generic email. Enabling the connection does not populate historical trials.

Return activity facts

Return HTTP 200, Content-Type: application/json, and no compressed response. Return only the fields below; do not include raw events, profile data, health information, or additional attributes.

{
  "data_as_of": "2026-10-06T10:00:00.000Z",
  "users": [
    {
      "customer_id": "example-user-123",
      "status": "ok",
      "has_opened_app": true,
      "activated_in_trial": true,
      "last_active_at": "2026-10-06T09:45:00.000Z"
    }
  ]
}

Field	Meaning
`data_as_of`	UTC timestamp through which the response covers activity, rather than a guessed request timestamp.
`customer_id`	Exact reference from the request. Return each reference at most once.
`status`	`ok`, `unknown_customer`, or `unavailable`.
`has_opened_app`	Boolean: whether the customer has opened the App by `data_as_of`.
`activated_in_trial`	Boolean: whether the customer completed your defined meaningful first activity during the requested trial window.
`last_active_at`	UTC timestamp of the latest known activity, or `null` when none is known.

For unknown_customer or unavailable, return only customer_id and status:

{
  "data_as_of": "2026-10-06T10:00:00.000Z",
  "users": [
    { "customer_id": "example-user-123", "status": "unknown_customer" }
  ]
}

Use real booleans and valid UTC timestamps. Activity cannot occur after data_as_of; coverage cannot precede the requested trial start. A customer who has never opened the App cannot already be activated or have a last activity timestamp. Activation in the requested trial requires a known last activity within that trial window. An omitted requested customer uses generic copy. Do not return unrequested customers or duplicate references. The maximum response is 1 MiB. Each attempt has a ten-second timeout, with at most one immediate retry for a transient failure. Authentication, validation, rate-limit responses, and redirects are not immediately retried. Activity decisions may be cached for fifteen minutes; coverage older than one hour uses generic copy.

How the email is chosen

Fresh activity	Trial-value outcome
Never opened the App	Open/get-started email.
Opened but not activated during the trial	First-activity email.
Activated and last active more than 24 hours ago	Return-to-App email.
Activated and active within the last 24 hours, including the boundary	Skip only the trial-value nudge; continue to the original next enabled billing reminder.
Missing, unknown, unavailable, stale, invalid, or failed lookup	Existing approved generic trial-value email.

A missing or unapproved generic template blocks delivery. Current consent, conversion, suppression, email mode, pause, campaign rules, sender readiness, send timing, and frequency limits still apply. A skipped nudge is not counted as an email sent. A retry after possible provider submission retains the same email content.

Configure FloKit

Select the correct App. These settings apply to the production environment. Open Governance → Marketing emails → Campaign rules → Trial not converted: App activity lookup.
Enter the endpoint URL and API key. Never paste the key into a chat or support message. Saved keys are write-only; leave the key blank to retain the saved key.
Confirm the exact customer-reference mapping.
Review and approve the three content variants. Confirm the App’s approved generic trial-value template, public App destination, business mailing address, and sending identity are configured.
Enable the lookup and select Save lookup. Saving changes the lookup only; email mode, pause, campaign switches, and schedules are separate controls.
Select Test saved connection. The test authenticates against the saved endpoint with exactly {"users":[]} and expects a valid envelope with a fresh data_as_of and "users":[]. No customers are queried and no email is sent.

Company owners and admins can save and test. Viewers and impersonated sessions can inspect the settings but cannot change or test the connection. Changing the endpoint requires re-entering the key. For key rotation, replace the key in FloKit and test the saved connection before retiring the previous key.

Troubleshooting

Symptom	Check
Generic email selected	Verify exact reference mapping, trial timestamps, coverage freshness, response fields, and endpoint availability. Older trials may have no retained reference.
Cannot enable lookup	Confirm identity mapping, approve variants, and install the active generic trial-value template.
Test fails	Check HTTPS/public IPv4, bearer authentication, JSON content type, empty-batch support, timeout, and response size.
No trial-value email	Check recent activation/activity and delivery eligibility, including consent, conversion, pause, mode, campaign rules, timing, frequency, and sender verification.
Settings changed error	Reload the settings and reapply the intended change.

See branded email setup for sender verification.

Start

Platform

Setup guides

Outbound webhooks

AI assistant

SDKs

Use App activity for trial emails

Prepare the endpoint

Return activity facts

How the email is chosen

Configure FloKit

Troubleshooting

​Prepare the endpoint

​Return activity facts

​How the email is chosen

​Configure FloKit

​Troubleshooting

Prepare the endpoint

Return activity facts

How the email is chosen

Configure FloKit

Troubleshooting