Users

Users represent your customers, the people who receive your messages. Each user profile stores contact information, preferences, and custom properties that you define. This data powers personalization in campaigns, segmentation in lists, and branching logic in journeys.

User Profiles

Every user has a profile containing:

• Identifiers: How Lunogram recognizes the user
• Contact info: Email, phone number for messaging
• Preferences: Timezone, locale, subscription states
• Custom data: Any properties you define

Identifiers

Users are identified through an identifier array. Each identifier has a source and an external_id, allowing a single user to be recognized across multiple systems.

A user needs at least one identifier. You can attach as many identifiers as needed — one per source system. The source field acts as a namespace, so the same external_id value can exist under different sources without conflict.

Common sources:

• default — your primary system's user ID
• anonymous — auto-generated IDs for unknown visitors (e.g., from the JavaScript SDK)
• posthog, segment, mixpanel — IDs from analytics tools
• Any custom string — use whatever fits your architecture

// Identify a known user with your system's ID
client.user.upsert({
  identifier: [{ externalId: "user_123" }],
  email: "alice@example.com",
});

// Attach multiple identifiers from different systems
client.user.upsert({
  identifier: [
    { externalId: "user_123", source: "default" },
    { externalId: posthog.get_distinct_id(), source: "posthog" },
  ],
  email: "alice@example.com",
});

When you call user.upsert with multiple identifiers, Lunogram resolves the user by looking up any of the provided (source, external_id) pairs. If a match is found, the existing user is updated and any new identifiers are added to their profile.

Contact Information

Preferences

Custom Data

Store any data you need on user profiles. Custom properties let you personalize messages, segment users into lists, and make decisions in journeys.

Setting Custom Data

client.user.upsert({
  identifier: [{ externalId: "user_123" }],
  email: "alice@example.com",
  data: {
    first_name: "Alice",
    plan: "premium",
    company: "Acme Inc",
    signup_source: "webinar",
    lifetime_value: 2500,
    preferences: {
      theme: "dark",
      notifications: true
    }
  }
})

curl -X POST https://your-instance.com/api/client/users \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": [{ "external_id": "user_123" }],
    "email": "alice@example.com",
    "data": {
      "first_name": "Alice",
      "plan": "premium",
      "company": "Acme Inc",
      "signup_source": "webinar",
      "lifetime_value": 2500
    }
  }'

Using Custom Data

Once stored, custom data is available everywhere via user.data:

In campaigns (personalization):

Hi
{{user.data.first_name}}, Thanks for being a
{{user.data.plan}}
member! {% if user.data.company %} We hope the team at
{{user.data.company}}
is enjoying Lunogram. {% endif %}

In lists (segmentation):

user.data.plan = "premium"
AND
user.data.lifetime_value > 1000

In journeys (branching):

Gate: user.data.plan = "enterprise"
  Yes → Send enterprise onboarding
  No → Send standard onboarding

Nested Properties

Store structured data using nested objects:

client.user.upsert({
  identifier: [{ externalId: "user_123" }],
  data: {
    address: {
      city: "Austin",
      state: "TX",
      country: "US",
    },
    preferences: {
      email_frequency: "weekly",
      product_updates: true,
    },
  },
});

Access nested properties with dot notation:

{{user.data.address.city}}, {{user.data.address.state}}

Common Custom Properties

Updating User Data

User properties merge on update. New properties are added, existing properties are overwritten, and unmentioned properties remain unchanged.

Initial upsert:

client.user.upsert({
  identifier: [{ externalId: "user_123" }],
  data: { plan: "free", city: "Austin" },
});
// Result: { plan: "free", city: "Austin" }

Later update:

client.user.upsert({
  identifier: [{ externalId: "user_123" }],
  data: { plan: "premium", company: "Acme" },
});
// Result: { plan: "premium", city: "Austin", company: "Acme" }

Updating from Journeys

Use the Update step to modify user data based on journey context. The template is a JSON string with Liquid expressions that can reference user properties and upstream step data via journey.<data_key>:

{
  "full_name": "{{ user.data.first_name }} {{ user.data.last_name }}",
  "last_score": "{{ journey.score_lookup.body.score }}"
}

In this example, score_lookup is the data key of an upstream Action step whose response contained a score field.

Creating Users

CSV Import

Upload a CSV file from the Users page to bulk create or update users. Each row becomes a user profile.

identifier,email,first_name,last_name,plan,company
user_001,alice@example.com,Alice,Smith,premium,Acme Inc
user_002,bob@example.com,Bob,Jones,free,Globex
user_003,carol@example.com,Carol,White,premium,Initech

The identifier column is required and is used as the external_id with the default source. The following columns map to standard user fields:

email, phone, first_name, last_name, timezone, locale

All other columns (like plan and company above) become custom properties.

Subscriptions

Users can subscribe or unsubscribe from each subscription group. Subscription state controls whether a user receives messages for that group.

Why Use Multiple Subscription Groups?

Instead of a single "subscribed/unsubscribed" toggle, you can create separate groups for different message types:

This lets users opt out of promotional emails while still receiving important product updates or transactional messages.

How Users Manage Subscriptions

• Preference center: Include {{ preferences_url }} in emails to link to a page where users manage all their subscription groups
• One-click unsubscribe: Include {{ unsubscribe_url }} for a direct unsubscribe link for that specific group
• SMS reply: Users can reply STOP to unsubscribe from SMS messages
• Your app: Call the SDK or API to update subscription state from your own UI