docs: merge-tag reference — custom fields, discovery, fallbacks - #14
docs: merge-tag reference — custom fields, discovery, fallbacks#14CosmoBlk wants to merge 2 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
The personalization section taught one example and left everything else to be guessed at, which is how an operator ends up inventing a tag the engine rejects. Documents the real grammar: the supported contact.* paths, the data.* namespace for custom fields and connected-tool data, which fields deliberately come back unmergeable and why, filters, and discovery through the editor's field picker or GET /v1/my/contacts/fields. Two things it is careful to state plainly. A tag with no value is an error, not a blank — the send fails for that recipient rather than delivering "Hi ," — so enrichment fields want a fallback. And transactional data.* is the caller's own per-send payload, not stored contact data; conflating the two is the easiest way to write a transactional template that silently never personalizes.
b0baa37 to
938cf05
Compare
F28: the reference claimed every empty tag fails the recipient, next to a contact.first_name example that actually renders as an empty string. The namespaces differ and now the page says so; the advice (always give a sparse field a fallback) is unchanged.
auscaster
left a comment
auscaster
left a comment
There was a problem hiding this comment.
Not safe to merge against current product truth yet. Three concrete corrections: (1) “Available filters” is incomplete—Email::VariableInterpolator::SUPPORTED_FILTERS currently includes default, upcase, downcase, capitalize, number, currency, percent, date, datetime, and boolean; either project the complete canonical grammar or avoid an exhaustive claim. (2) “Test sends and previews render … against a real contact” is false by default: Email::TestSender uses an owner proxy unless contact_id/sample_contact_id is supplied; document the selected-contact condition. (3) hold publication until nitrosend/nitrosend#406 and #408 are deployed, because filtered tags and data values in hrefs are not yet reliable in production. The rest of the namespace/fallback description matches current main.
2 participants
Summary
The merge-tag reference, written against what actually ships:
{{ data.<path> }}as the canonical custom-field syntax, the supportedcontact.*paths, filters and fallbacks, which connector namespaces merge and which plumbing does not, the scalar-only projection rule, and discovery viamerge_tag+nitro://fields.Every
{{ contact.<custom> }}/{{ contact.data.* }}claim from the rejected round is gone — that syntax is rejected by current authoring validation.Review fix included
A reviewer caught the page claiming every empty tag fails the recipient, directly above a
contact.first_nameexample that actually renders blank. The namespaces genuinely differ — a missingdata.*tag hard-fails that recipient viaEmail::MergeArtifactGuard, a missing built-incontact.*tag renders as an empty string — and the page now says so. The advice is unchanged: give any sparse field a fallback.Test plan
contact.data.syntax survives anywhere in the docs{{ data.syntax