Documentation version: 2026-09-18.3
Canonical: https://docs.creator.gg/guides/email-content.md

# Email content, merge fields, and unsubscribe footers

## Discover available fields at runtime
Call `email_merge_fields_list({"category":"all"})` when composing personalized email. It combines a maintained standard email catalogue with live contact custom fields and workspace custom values. Copy each returned `mergeToken` exactly. User-created fields appear on the next call; no documentation rebuild is needed. Use category=contact/workspace/user/date to narrow the list. Read https://docs.creator.gg/tools/email_merge_fields_list.md for the full contract and standard catalogue.

Check `coverage` and `partial`: an unavailable category is not an empty list. Workspace custom values require additional read permission that an existing connection may lack. `rejectedKeys` flags definitions without a usable key. Discovery returns definitions, not stored custom values or recipient data. For contact values, match returned custom-field IDs with contacts_get. Standard/user tokens still require the indicated record context.

There is no universal all-product merge-field inventory here. Appointment, invoice, opportunity, company/custom-object and other contextual fields require their corresponding records and are not enumerated by this email tool.

## Establish the footer mode
An account can append an automatic unsubscribe footer, or the content can include the built-in `{{unsubscribe}}` tag. The tag becomes an unsubscribe link during sending. Do not invent a recipient-specific URL or substitute the website homepage.

Check Settings → Business Profile → General in the connected account using authorized browser access, or obtain the user's confirmed unsubscribe configuration. There is no Creators tool to read this toggle. A template list cannot establish it.

- Automatic footer confirmed enabled: preserve it. Its contents may not appear in saved template HTML.
- Automatic footer confirmed disabled: include `{{unsubscribe}}` in message content and verify its rendering through the account test/preview workflow.
- Configuration unknown: resolve it or keep the campaign as a draft; do not assume a footer will be appended.
- Both methods present: an additional link may appear. Check the actual message before changing content or account settings.

The documented tag is `{{unsubscribe}}` as content. Do not assume it is a bare URL for an href attribute without validating editor behavior.

Do not toggle footer settings just to simplify a template. Preserve working unsubscribe behavior and suppression preferences. An untested custom unsubscribe workflow is not a replacement.

## Personalization: first name and other standard fields
Use the literal token `{{contact.first_name}}` in HTML or text content. It refers to the recipient's saved first name. Pass it unchanged in editorContent; Creators resolves it for each contact during sending. Example: `<p>Hey {{contact.first_name}},</p>`.

| Recipient value | Token | Contact tool field to inspect |
| --- | --- | --- |
| First name | `{{contact.first_name}}` | firstName |
| Last name | `{{contact.last_name}}` | lastName |
| Full name | `{{contact.name}}` | firstName and lastName |
| Email | `{{contact.email}}` | email |
| Phone | `{{contact.phone}}` | phone |

Read contacts_search/contacts_get to check audience data. Tool properties use camelCase; email tokens have their own spelling. `firstName` is not the token `contact.first_name`. A stored template preview can show literal braces because it lacks a recipient context. That alone is not an error.

## Missing names and fallback text
A missing value can leave a blank greeting. Inspect every selected contact before choosing personalized wording. For mixed or unknown name coverage, use a static greeting such as `Hello,`, or configure fallback text in the account email editor: select the merge tag, open Default Text, save a fallback and test with a blank-field contact. Fallback applies per occurrence and does not edit the contact.

The current Creators HTML/text API has no separately validated fallback-syntax contract. Do not invent a filter such as `| default` or assume another template language is supported. Visual-editor fallback configuration is a handoff, not an API argument. Do not populate missing names with guesses merely to make a template render.

## Custom fields and record context
contacts_fields_list reads configured definitions and their fieldKey values. email_merge_fields_list returns validated, ready-to-use tokens from those keys. A field ID or display label is not a merge token.

Use email_merge_fields_list for live custom fields and workspace custom values; use the email editor picker if discovery reports unavailable permission or an unsupported key. Appointment, invoice and other record-specific tokens need that record context, which an ordinary contact campaign does not supply. The current email tools do not add appointment/invoice context to a campaign. Inspect personalization with a suitable test recipient before broad delivery.

Use the business's confirmed name/address. Never fabricate a physical address from a domain or inferred location.

## Metadata and editing
Use editorType=html or text. Content replacement requires editorType and editorContent together. HTML replacement of visual-builder content is unsupported.

Template metadata uses subjectLine/fromName/fromEmail/previewText. Send-time emailMeta requires subject; fromName/fromEmail are optional overrides of the authenticated-user defaults. replyToAddress/previewText are optional. Template metadata does not replace send-time metadata.

## Troubleshoot personalization
1. A blank value: inspect the saved recipient field and verify the correct contact is in the audience.
2. Literal braces in a saved preview: inspect a recipient-aware test; saved content is not a rendered message.
3. Literal braces in an actual message: verify token spelling and editor support in the account picker.
4. An unexpected person's name: compare the contact ID and recipient record; the sending user's profile is not the recipient's first name.
5. Confirmed missing data: use static wording or a verified editor fallback; preserve the actual contact data.

email_campaigns_test provides a handoff. It does not send or render email. Creating a draft with a token also does not verify personalization. Verification sends require the user's requested scope.

## Rendering
Use readable mobile text, contrast, meaningful links, alt text, and text fallback when images are blocked. Prefer table layouts and inline styles.

Saved-content browser preview, true test email, campaign submission, and recipient delivery are separate checks. Browser rendering cannot prove all mail clients or resolve send-time footer behavior.

The Creators test tool returns a handoff. Its invocation is not evidence that a test email was sent.

## Saved content and preview links
Creators returns opaque https://mcp.creator.gg/assets/ links for supported stored email content and media. These links expire after 24 hours; read the record again to refresh one. Preview fetches are limited to 8 MiB. Larger files and unsupported previews can be inspected in the account screen. Preview HTML is sandboxed and does not execute scripts. A preview still has no recipient context.

You may reuse a current link in a tool argument, including editorContent or social media. Creators resolves it to the stored asset before saving or scheduling, so the preview expiry does not expire the saved campaign or post. Treat preview links as access capabilities and share them only within the authorized task. For a durable link used outside Creators tools, use your own published asset URL.