Skip to content

Custom Fields

Custom fields let you store app-specific data on each subscriber — things like subscription tier, favorite category, or referral code. Use them to personalize emails and build targeted segments.

How Custom Fields Work

Custom fields are stored as a JSON object on each subscriber. There's no schema to define up front — just set a key and value, and it's stored.

{
    "app_subscription_status": "premium",
    "favorite_category": "dinner",
    "referral_code": "FRIEND10",
    "app_subscription_expires_at": "2025-12-31"
}

Setting Custom Fields

From the SDK

MailJawn.setUserProperties([
    "app_subscription_status": "premium",
    "favorite_category": "dinner",
    "referral_code": "FRIEND10"
])

This triggers an /identify call that merges the properties into the subscriber's custom fields.

From the API

Include custom_fields in the identify request body:

POST /api/v1/projects/{project_id}/subscribers/identify/

{
    "email": "jane@example.com",
    "custom_fields": {
        "app_subscription_status": "premium",
        "favorite_category": "dinner"
    }
}

From the Dashboard

Edit a subscriber's profile and update their custom fields directly.

Merge Behavior

Custom fields are merged additively:

  • New keys are added
  • Existing keys are updated with the new value
  • Unmentioned keys are preserved — they are never deleted

For example, if a subscriber has:

{"favorite_category": "dinner", "referral_code": "FRIEND10"}

And you send:

{"favorite_category": "breakfast", "loyalty_tier": "gold"}

The result is:

{"favorite_category": "breakfast", "referral_code": "FRIEND10", "loyalty_tier": "gold"}

Tip

To clear a custom field, explicitly set it to null or an empty string.

Querying Custom Fields in Segments

Custom fields can be used as segment rules to build targeted audiences.

Available operators:

Operator Description
eq Equals
neq Not equals
gt Greater than
gte Greater than or equal
lt Less than
lte Less than or equal
exists Field is present on subscriber
not_exists Field is not present

Example segment rule — subscribers on the premium plan:

{"type": "custom_field", "field": "app_subscription_status", "operator": "eq", "value": "premium"}

Example — subscribers who have a referral code (regardless of value):

{"type": "custom_field", "field": "referral_code", "operator": "exists"}

Storage Details

Custom fields are stored as PostgreSQL JSONB, which means:

  • Values can be strings, numbers, booleans, or nested objects
  • Queries use PostgreSQL's JSONB operators for efficient filtering
  • Fields are not individually indexed — for fields that become heavily queried, they can be promoted to dedicated database columns (contact support)

Use Cases

Field Example Value Purpose
app_subscription_status "premium", "free", "trial" Target campaigns by app tier
app_subscription_expires_at "2025-12-31" Trigger renewal reminders
favorite_category "dinner", "desserts" Personalize content recommendations
referral_code "FRIEND10" Track referral campaigns
onboarding_completed true Segment by onboarding status
lifetime_purchases 12 Segment by engagement level

See also: