API Docs / Integration Contract

Meisa Integration Contract

A stable, one-time integration pattern so marketing teams can configure onboarding and trigger-based emails entirely in Meisa.

The contract in one sentence

Your product must keep each user’s current state synced to Meisa via POST /api/v1/contacts/upsert/, storing product-specific telemetry under custom_fields.

Required identifiers

email: primary email
external_id: your internal user ID (stable, unique)

Custom fields (the core of the system)

Put everything you want marketing to automate on into custom_fields. Meisa detects changes and triggers your workflows.

Examples

plan: free / standard / pro / churned
subscription_status: active / trialing / past_due / canceled
mrr: number
posts_generated: number
onboarding_completed: boolean

Sync timing (recommended)

On signup: sync immediately
On plan/billing change: sync immediately
On milestones: sync when thresholds are crossed (e.g., 1, 5, 10)
Optional: daily refresh for active users

Recommended field taxonomy

A copy/paste-friendly starting point. Not every product will have every field-use what matches your domain, and keep names stable once introduced.

Billing

plan: free / standard / pro / churned
subscription_status: active / trialing / past_due / canceled
billing_cycle: monthly / annual / lifetime
mrr: number

Lifecycle & onboarding

signup_date: ISO string
last_active: ISO string
onboarding_completed: boolean
onboarding_step: string (optional)

Usage / telemetry (examples)

posts_generated: number
ideas_generated: number
projects_created: number
feature_x_used: boolean

Acquisition & attribution

utm_source: string
utm_medium: string
utm_campaign: string
referral_source: string

How this enables non-technical workflows

Trigger: Contact Created → enroll in onboarding sequence
Trigger: Contact Updated (field change) → e.g. plan free → pro
Conditions: match any custom field (e.g., posts_generated ≥ 5)

Minimal payload example

{
  "email": "[email protected]",
  "external_id": "usr_12345",
  "first_name": "Jane",
  "last_name": "Doe",
  "custom_fields": {
    "plan": "free",
    "posts_generated": 0,
    "onboarding_completed": false
  }
}