Basics — fundamentos de Marketing Cloud AMPscript | Cleon

AMPscript es el lenguaje de personalización que Marketing Cloud usa cuando necesitás contenido per-destinatario en send time. Corre adentro de los emails mientras se rendereaen para cada subscriber, adentro de CloudPages componiendo HTML dinámico, adentro de Mobile Push y SMS, y en cualquier otro lugar donde MC esté templatizando contenido para un destinatario individual. La superficie de funciones se ve chica (~150 funciones) pero el lenguaje tiene sus propias reglas de scoping, tres formas de sintaxis distintas, una superficie de NULL con tres funciones distintas para "nada acá", y un preview de personalización que usa un code path distinto al del envío real — ver gotchas.

Esta página es la orientación. El resto del catálogo de AMPscript (páginas de referencia por categoría de función, Style Guide, snippets de debugging) construye sobre el modelo mental de abajo.

Sintaxis oficial

AMPscript tiene tres formas de sintaxis. Cada una hace algo distinto:

<!-- 1. Forma de bloque — lógica multi-sentencia.
     Cualquier cosa entre %%[ y ]%% es AMPscript, no HTML. -->
%%[
  SET @firstName = AttributeValue("FirstName")
  IF Empty(@firstName) THEN
    SET @firstName = "Friend"
  ENDIF
]%%

<!-- 2. Forma de función inline — renderea un valor en el HTML.
     La función o variable se evalúa y el resultado se outputea. -->
<p>Hola, %%=v(@firstName)=%%</p>

<!-- 3. Forma de interpolación de campo — renderea una columna de DE
     o Subscriber Attribute directamente. Sin prefijo @. -->
<p>Tu orden #%%OrderId%% se envía mañana.</p>

Un cuerpo de email típico intercala las tres: un bloque al tope para calcular variables y traer lookups, referencias de función inline en la prosa para renderear los valores, e interpolación de campo para columnas de DE crudas que no necesitan transformación.

La superficie del lenguaje soportada adentro de un bloque:

| Feature | Disponible | |---|---| | SET @var = value (asignación) | ✓ | | IF / ELSEIF / ELSE / ENDIF | ✓ | | FOR / NEXT (loop numérico) | ✓ | | VAR @x, @y, @z (declaración sin asignación) | ✓ | | Llamadas a funciones — Lookup, Empty, Concat, DateAdd, Substring, etc. | ✓ | | OUTPUT / OUTPUTLINE (renderear explícitamente desde un bloque) | ✓ | | Comentarios — /* ... */ (single o multi-línea) | ✓ | | Loops WHILE | ✗ — solo FOR | | BREAK / CONTINUE | ✗ — reestructurar con IF | | Funciones custom | ✗ — sin funciones definidas por el usuario | | Expresiones regulares | ✗ — carácter por carácter con Substring e IndexOf | | try / catch | ✗ — defaults defensivos con Empty() en su lugar | | Manejo de errores nativo | ✗ — la mayoría de las fallas devuelven NULL o 0 en silencio (ver gotchas) |

Referencia:

AMPscript Guide ↗ — el function reference construido por la comunidad que Salesforce debería haber entregado
Salesforce Developer — referencia de AMPscript ↗
Salesforce Help — vista general de AMPscript ↗

Lo que sobrevive en producción

Dónde corre AMPscript — y cómo cada contexto cambia los patrones

AMPscript corre en varios contextos de MC. El lenguaje es el mismo; el contexto de runtime cambia qué patrones tienen sentido.

Cuerpo de email (el contexto primario):

Renderea una vez por destinatario en send time.
Las variables y los lookups pasan para cada destinatario — un Send de 50k son 50k corridas de AMPscript, cada una independiente.
La performance importa a escala: un LookupRows pesado en el cuerpo del email corre 50.000 veces. Pre-formateá el data en una SQL Activity y leé un DE finito en el email.
El preview de personalización es necesario pero no suficiente — ver gotchas — #9.

CloudPages:

Renderea una vez por request a la página.
Lee parámetros de URL vía RequestParameter() — el equivalente AMPscript de Request.GetQueryStringParameter() en SSJS.
Puede escribir a Data Extensions vía InsertData / UpdateData / UpsertData — las mismas funciones de write que en emails, mismo comportamiento de falla silenciosa (ver gotchas — #10).
AMPscript y SSJS pueden coexistir en la misma página; la regla es un bloque por lenguaje, con handoffs explícitos.

Mobile Push y SMS:

Subset de la superficie de AMPscript — algunas funciones que andan en email no andan acá (la superficie cambia por canal).
Las restricciones de largo del cuerpo hacen visible los errores de output de AMPscript inmediatamente (mensaje truncado, conteo de caracteres mal).
Testeá en el canal real, no en preview.

Triggered sends:

AMPscript corre por trigger, igual que en email por send.
El payload del trigger está disponible vía interpolación de campo igual que una fila de DE sendable.

Las tres fuentes de donde viene el data

AMPscript tira data de tres lugares, y confundirlos es la causa #1 de las fallas "el email rendereó en blanco":

| Fuente | Cómo referenciarla | Cuándo está disponible | |---|---|---| | Columnas del DE sendable | %%ColumnName%% inline, [ColumnName] adentro de un bloque, o vía Lookup() para un DE distinto | Cuando la Send Activity corrió contra un DE que tiene esa columna | | Subscriber Attributes | AttributeValue("AttrName") o %%AttrName%% | Cuando el perfil All Subscribers tiene ese atributo configurado Y el destinatario es un subscriber válido | | Variables locales | %%=v(@varName)=%% inline, @varName adentro de un bloque | Solo después de que SET @varName = ... corrió exitosamente en un bloque previo |

Cuando dos fuentes tienen el mismo nombre (una columna de DE FirstName y un Subscriber Attribute FirstName), el inline %%FirstName%% resuelve a una de las dos según el contexto de renderizado, y la regla de resolución no siempre es intuitiva. La defensa: nombralas distinto. Ver gotchas — #4.

Mecanismos de output

Tres formas de renderear un valor en el HTML / texto renderado:

<!-- 1. Interpolación inline — el patrón más común. -->
<p>Hola, %%=v(@firstName)=%% — tu orden es %%=v(@orderTotal)=%%.</p>

<!-- 2. OUTPUT() adentro de un bloque — útil cuando necesitás emitir
     contenido condicionalmente basado en lógica difícil de expresar
     en HTML puro. -->
%%[
  IF @segment == "Gold" THEN
    OUTPUT(Concat("<p>Exclusivo: ", @goldPromo, "</p>"))
  ENDIF
]%%

<!-- 3. CONCAT() y asignación — construir el string en una variable, y
     después interpolarla. El patrón cuando el output requiere más de
     una rama. -->
%%[
  SET @greeting = Concat("Hola, ", @firstName)
  IF @hasOrders THEN
    SET @greeting = Concat(@greeting, " — bienvenido de vuelta")
  ELSE
    SET @greeting = Concat(@greeting, " — primera vez?")
  ENDIF
]%%
<p>%%=v(@greeting)=%%</p>

OUTPUT() es útil pero fácil de abusar. La convención de Cleon: preferí construir strings en variables e interpolar con %%=v(@x)=%%. OUTPUT() está reservado para los casos donde el emit a mitad de bloque es la expresión más limpia de la intención.

Categorías de funciones de un vistazo

La superficie de funciones de AMPscript se agrupa en ocho categorías aproximadas. Cada una tiene su propia página de referencia en este catálogo (a medida que se entreguen):

| Categoría | Ejemplos | Propósito | |---|---|---| | Funciones de string | Concat, Substring, Lowercase, Trim, IndexOf, Replace | Construir y partir texto | | Funciones de fecha | Now, DateAdd, DateDiff, DatePart, FormatDate | Aritmética y formateo de tiempo | | Funciones de math | Add, Subtract, Multiply, Divide, Mod, Round | Aritmética (sí, math son funciones, no operadores) | | Validación | Empty, IsNull, IsEmailAddress, IsNumeric, IsPhoneNumber | Chequeos de tipo y formato | | Data Extension | Lookup, LookupRows, InsertData, UpdateData, UpsertData, Field, Row | Leer y escribir DEs | | Subscriber / Profile | AttributeValue, _subscriberKey, _messagecontext, _jobid | Leer el contexto del destinatario actual | | Cloud-write | UpdateSingleSalesforceObject, CreateSalesforceObject, RetrieveSalesforceObjects | Leer/escribir objetos de Sales/Service Cloud | | Encoding / Hashing | URLEncode, Base64Encode, SHA256, MD5 | Encoding para links de tracking, generación de firmas |

Las páginas de referencia van a aterrizar para cada categoría a medida que se entreguen — ver Related para la lista actual.

Decisión rápida

Andá a AMPscript cuando:

Necesitás personalización per-destinatario en send time en un email o push. AMPscript corre inline en render time; SSJS y SQL no.
Necesitás leer una columna de DE sendable para el destinatario actual — %%ColumnName%% es la expresión más simple.
Necesitás renderear condicionalmente HTML basado en el data del destinatario — IF @x THEN OUTPUT(...) ENDIF.
Necesitás un lookup single-row para contexto (segmento, tier, última orden) — Lookup() es la herramienta correcta.

Andá a SSJS en su lugar cuando:

Estás en una CloudPage haciendo orquestación multi-paso (leer DE, llamar API, escribir DE, después renderear).
Necesitás callouts HTTP a APIs externas (HTTP.Get / HTTP.Post existen en SSJS, no en AMPscript).
Necesitás lecturas o escrituras en bulk que no encajan en el modelo per-destinatario de AMPscript.
Necesitás manejo de errores más allá de los defaults defensivos (SSJS tiene try / catch).

Andá a SQL Query Activity en su lugar cuando:

El trabajo es set-based read / transform / write sobre un Data Extension antes del send.
Necesitás formatear la audiencia (filtrar, joinear, dedupear) — ese es el trabajo de la SQL Activity, corriendo upstream de la Send Activity.
Estás calculando agregaciones (conteos, sumas, promedios) a lo largo de la audiencia — AMPscript no puede.

No vayas a AMPscript cuando:

La personalización se puede calcular una vez upstream en una SQL Activity y guardar en una columna. Un de_email_<send> DE con columnas pre-calculadas es más rápido (una corrida SQL para 50k destinatarios vs 50k corridas AMPscript) y más fácil de debuggear.
La lógica no es trivial. AMPscript con más de ~30 líneas es un pasivo de hand-off — refactorizá la prep de data a SQL upstream para que el cuerpo del email quede fino.

Relacionado

Gotchas de MC AMPscript — lo que rompe a escala en cada email con AMPscript
Basics de MC SSJS — la página de orientación de la subcategoría hermana (contextos CloudPage / Script Activity)
Basics de MC SQL — la página de orientación de la subcategoría hermana (formateo de audiencia set-based)
Principios de Marketing Cloud — las meta-reglas arriba de los específicos de AMPscript

Más páginas de referencia de AMPscript en camino: funciones de String / Date / Math · Validación · funciones de Data Extension (familia Lookup + funciones de write) · funciones de Subscriber / Profile · funciones de Cloud-write · Style Guide.

Más snippets how-to de debugging para las formas de falla de producción — blancos en render-time, Lookup devolviendo NULL, duplicados de UpsertData desde un form de CloudPage, fallas silenciosas de Cloud-write.