Documentation version: 2026-09-18.3
Canonical: https://docs.creator.gg/tools/email_merge_fields_list.md

# email_merge_fields_list

Discover email personalization tokens for this workspace. Reads current contact custom fields and workspace custom values, combines standard fields, and reports unavailable categories. Call when composing personalized content; user-created fields are fetched live. Does not return customer field values or change records.

## Execution

Interface: Creators MCP tool at https://mcp.creator.gg/mcp. Do not construct a REST route from the tool name. The connection selects the workspace.

Effect: read-only or navigation handoff; no marketing mutation.

## Behavior and limits

Read-only, with category=all/contact/workspace/user/date. Returns fields with exact mergeToken, key, label, source, category, requires and optional ID/type. Configured contact fields and workspace custom values are fetched each call; standard fields use the maintained catalogue. No stored custom values are returned. coverage distinguishes available, unavailable and not_requested; partial=true or rejectedKeys means incomplete discovery, not an empty workspace. Workspace custom values need additional read permission that existing connections may lack. This tool does not enumerate appointment/invoice/opportunity/company/custom-object fields or imply those contexts exist in an email campaign. Read recipient values separately and verify missing-value handling.

## Example arguments

Illustrative placeholders only. Replace IDs with values from this workspace, resolve sender/content/recipients, recalculate dates, and generate a new requestId for a new action.

```json
{
  "category": "all"
}
```

## Input schema

Generated from the current executable Creators contract. Runtime rules in Behavior and limits and the linked guide also apply; JSON Schema alone cannot express all cross-field constraints.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "category": {
      "default": "all",
      "type": "string",
      "enum": [
        "all",
        "contact",
        "workspace",
        "user",
        "date"
      ]
    }
  },
  "additionalProperties": false
}
```

## Result interpretation

Results use status and message, with operation-specific data and optional link, code, nextAction, and operationId. Data may retain different list/record envelopes. A completed read or accepted send is not proof of delivery/publication. An unknown result must be reconciled. HUMAN_ACTION_REQUIRED returns instructions without performing the action.

## Standard email field catalogue

These definitions are maintained with the product. User-created fields are additional live results of the tool; they do not belong in this public static catalogue.

```json
[
  {
    "key": "contact.name",
    "mergeToken": "{{contact.name}}",
    "label": "name",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.first_name",
    "mergeToken": "{{contact.first_name}}",
    "label": "first name",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.last_name",
    "mergeToken": "{{contact.last_name}}",
    "label": "last name",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.email",
    "mergeToken": "{{contact.email}}",
    "label": "email",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.phone",
    "mergeToken": "{{contact.phone}}",
    "label": "phone",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.phone_raw",
    "mergeToken": "{{contact.phone_raw}}",
    "label": "phone raw",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.company_name",
    "mergeToken": "{{contact.company_name}}",
    "label": "company name",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.full_address",
    "mergeToken": "{{contact.full_address}}",
    "label": "full address",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.address1",
    "mergeToken": "{{contact.address1}}",
    "label": "address1",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.city",
    "mergeToken": "{{contact.city}}",
    "label": "city",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.state",
    "mergeToken": "{{contact.state}}",
    "label": "state",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.postal_code",
    "mergeToken": "{{contact.postal_code}}",
    "label": "postal code",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.timezone",
    "mergeToken": "{{contact.timezone}}",
    "label": "timezone",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.date_of_birth",
    "mergeToken": "{{contact.date_of_birth}}",
    "label": "date of birth",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.source",
    "mergeToken": "{{contact.source}}",
    "label": "source",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.website",
    "mergeToken": "{{contact.website}}",
    "label": "website",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "contact.id",
    "mergeToken": "{{contact.id}}",
    "label": "id",
    "category": "contact",
    "source": "standard",
    "requires": "recipient contact record"
  },
  {
    "key": "location.name",
    "mergeToken": "{{location.name}}",
    "label": "name",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location.full_address",
    "mergeToken": "{{location.full_address}}",
    "label": "full address",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location.address",
    "mergeToken": "{{location.address}}",
    "label": "address",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location.city",
    "mergeToken": "{{location.city}}",
    "label": "city",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location.state",
    "mergeToken": "{{location.state}}",
    "label": "state",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location.country",
    "mergeToken": "{{location.country}}",
    "label": "country",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location.postal_code",
    "mergeToken": "{{location.postal_code}}",
    "label": "postal code",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location.email",
    "mergeToken": "{{location.email}}",
    "label": "email",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location.phone",
    "mergeToken": "{{location.phone}}",
    "label": "phone",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location.phone_raw",
    "mergeToken": "{{location.phone_raw}}",
    "label": "phone raw",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location.website",
    "mergeToken": "{{location.website}}",
    "label": "website",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location.logo_url",
    "mergeToken": "{{location.logo_url}}",
    "label": "logo url",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location.id",
    "mergeToken": "{{location.id}}",
    "label": "id",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace profile"
  },
  {
    "key": "location_owner.first_name",
    "mergeToken": "{{location_owner.first_name}}",
    "label": "first name",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace owner profile"
  },
  {
    "key": "location_owner.last_name",
    "mergeToken": "{{location_owner.last_name}}",
    "label": "last name",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace owner profile"
  },
  {
    "key": "location_owner.email",
    "mergeToken": "{{location_owner.email}}",
    "label": "email",
    "category": "workspace",
    "source": "standard",
    "requires": "workspace owner profile"
  },
  {
    "key": "user.name",
    "mergeToken": "{{user.name}}",
    "label": "name",
    "category": "user",
    "source": "standard",
    "requires": "user assigned to the email context; not necessarily the authenticating user"
  },
  {
    "key": "user.first_name",
    "mergeToken": "{{user.first_name}}",
    "label": "first name",
    "category": "user",
    "source": "standard",
    "requires": "user assigned to the email context; not necessarily the authenticating user"
  },
  {
    "key": "user.last_name",
    "mergeToken": "{{user.last_name}}",
    "label": "last name",
    "category": "user",
    "source": "standard",
    "requires": "user assigned to the email context; not necessarily the authenticating user"
  },
  {
    "key": "user.email",
    "mergeToken": "{{user.email}}",
    "label": "email",
    "category": "user",
    "source": "standard",
    "requires": "user assigned to the email context; not necessarily the authenticating user"
  },
  {
    "key": "user.phone",
    "mergeToken": "{{user.phone}}",
    "label": "phone",
    "category": "user",
    "source": "standard",
    "requires": "user assigned to the email context; not necessarily the authenticating user"
  },
  {
    "key": "user.phone_raw",
    "mergeToken": "{{user.phone_raw}}",
    "label": "phone raw",
    "category": "user",
    "source": "standard",
    "requires": "user assigned to the email context; not necessarily the authenticating user"
  },
  {
    "key": "user.email_signature",
    "mergeToken": "{{user.email_signature}}",
    "label": "email signature",
    "category": "user",
    "source": "standard",
    "requires": "user assigned to the email context; not necessarily the authenticating user"
  },
  {
    "key": "user.calendar_link",
    "mergeToken": "{{user.calendar_link}}",
    "label": "calendar link",
    "category": "user",
    "source": "standard",
    "requires": "user assigned to the email context; not necessarily the authenticating user"
  },
  {
    "key": "right_now.second",
    "mergeToken": "{{right_now.second}}",
    "label": "second",
    "category": "date",
    "source": "standard",
    "requires": "message render time"
  },
  {
    "key": "right_now.minute",
    "mergeToken": "{{right_now.minute}}",
    "label": "minute",
    "category": "date",
    "source": "standard",
    "requires": "message render time"
  },
  {
    "key": "right_now.hour",
    "mergeToken": "{{right_now.hour}}",
    "label": "hour",
    "category": "date",
    "source": "standard",
    "requires": "message render time"
  },
  {
    "key": "right_now.hour_ampm",
    "mergeToken": "{{right_now.hour_ampm}}",
    "label": "hour ampm",
    "category": "date",
    "source": "standard",
    "requires": "message render time"
  },
  {
    "key": "right_now.ampm",
    "mergeToken": "{{right_now.ampm}}",
    "label": "ampm",
    "category": "date",
    "source": "standard",
    "requires": "message render time"
  },
  {
    "key": "right_now.day_of_week",
    "mergeToken": "{{right_now.day_of_week}}",
    "label": "day of week",
    "category": "date",
    "source": "standard",
    "requires": "message render time"
  },
  {
    "key": "right_now.month_name",
    "mergeToken": "{{right_now.month_name}}",
    "label": "month name",
    "category": "date",
    "source": "standard",
    "requires": "message render time"
  },
  {
    "key": "right_now.day",
    "mergeToken": "{{right_now.day}}",
    "label": "day",
    "category": "date",
    "source": "standard",
    "requires": "message render time"
  },
  {
    "key": "right_now.month",
    "mergeToken": "{{right_now.month}}",
    "label": "month",
    "category": "date",
    "source": "standard",
    "requires": "message render time"
  },
  {
    "key": "right_now.year",
    "mergeToken": "{{right_now.year}}",
    "label": "year",
    "category": "date",
    "source": "standard",
    "requires": "message render time"
  },
  {
    "key": "right_now.middle_endian_date",
    "mergeToken": "{{right_now.middle_endian_date}}",
    "label": "middle endian date",
    "category": "date",
    "source": "standard",
    "requires": "message render time"
  },
  {
    "key": "right_now.little_endian_date",
    "mergeToken": "{{right_now.little_endian_date}}",
    "label": "little endian date",
    "category": "date",
    "source": "standard",
    "requires": "message render time"
  }
]
```

## Related guides

- [email](https://docs.creator.gg/guides/email.md)
- [Recovery](https://docs.creator.gg/guides/recovery.md)
- [Unsubscribe and content](https://docs.creator.gg/guides/email-content.md)
- [Readiness](https://docs.creator.gg/guides/readiness.md)