Automatizaciones
Correos y pasos que se ejecutan solos para cada contacto, y los eventos que los inician.
Herramientas de automatizaciones
| Herramienta | Qué hace |
|---|---|
| listAutomations | Las automatizaciones del espacio de trabajo, primero las modificadas más recientemente, con su estado, qué inicia cada una y cuántos contactos hay en ella. |
| getAutomation | Una automatización al completo: su estado, sus ajustes y sus cifras, lo que falla en su borrador y la definición del borrador como JSON. includePublished añade la versión que está en marcha. |
| listAutomationStarters | Las automatizaciones ya preparadas desde las que puede empezar una nueva, cada una con su definición. |
| createAutomation | Crear un borrador a partir de un punto de partida, de una definición escrita como JSON o vacío, con cualquier ajuste. Nada se ejecuta hasta que se publica. |
| updateAutomation | Cambiar el nombre y los ajustes de una automatización, que se aplican al momento, o reemplazar la definición de su borrador. Una automatización activa sigue ejecutando su versión publicada. |
| deleteAutomation | Eliminar una automatización para siempre, con sus versiones, inscripciones y cifras. Los contactos que están en ella se detienen de inmediato. |
| publishAutomation | Hacer del borrador la versión que se ejecuta y activar la automatización. Un borrador incompleto se rechaza con cada problema que lo bloquea. También requiere emails:send. |
| pauseAutomation | Detener una automatización activa. No entra nadie nuevo, y todos los que están en ella se quedan donde están. |
| resumeAutomation | Volver a activar una automatización en pausa con la versión que tenía en marcha. También requiere emails:send. |
| archiveAutomation | Retirar una automatización para siempre y conservar su historial. Todos los que están en ella salen. |
| duplicateAutomation | Copiar una automatización en un borrador nuevo, sin sus versiones, contactos ni cifras. |
| sendAutomationTest | Enviarte a ti o a una dirección el correo de un paso del borrador. También requiere emails:send. |
| listAutomationVersions | Las versiones publicadas, las más recientes primero, y cuál está en marcha. includeDefinitions añade cada definición. |
| restoreAutomationVersion | Copiar una versión anterior de vuelta al borrador. Nada de lo que está en marcha cambia hasta la siguiente publicación. |
| getAutomationStats | Contactos que entraron, que están dentro ahora, que completaron y que salieron, y correos enviados, entregados, abiertos y con clic en un periodo, en total y por cada paso. |
| listAutomationEnrollments | Los contactos que están o han estado en una automatización, de página en página, con el paso en el que está cada uno y cómo terminó. Filtra por estado, paso o una parte de la dirección. |
| getAutomationEnrollment | El camino de un contacto por una automatización: qué hizo cada paso por él, del más antiguo al más reciente. |
| enrollInAutomation | Meter a un contacto en una automatización activa por su primer paso, sea lo que sea lo que la inicia normalmente. |
| removeFromAutomation | Sacar de inmediato a un contacto de una automatización. |
| sendContactEvent | Registrar que a un contacto le ocurrió algo. Inicia las automatizaciones activas cuyo desencadenante nombra el evento y termina las esperas que lo estaban aguardando. |
| sendContactEvents | Registrar hasta 100 eventos en una sola llamada. Que uno falle no detiene a los demás. |
| listContactEventNames | Los nombres de evento que el espacio de trabajo ha registrado en los últimos 90 días. |
| listContactEvents | Los eventos registrados de un contacto, los más recientes primero, de página en página. |
Leer requiere automations:read y cada cambio requiere automations:write. Publicar, reanudar y enviar una prueba también requieren emails:send, porque entonces la automatización envía correo en nombre de quien la publicó. Enviar un evento requiere contacts:write, leer los eventos de un contacto requiere contacts:read, y listContactEventNames requiere automations:read. Un cliente que actúa en nombre de un miembro solo ve las automatizaciones que creó ese miembro y los contactos que añadió.
Algunas herramientas de este servidor hacen un cambio que la API REST protege con un código de verificación, y piden el mismo código. Hasta que el cliente haya verificado un código en los últimos 60 minutos, o la persona haya elegido Permitir cambios durante 60 minutos para él en Cuenta → Aplicaciones conectadas, esa herramienta responde con un resultado que empieza por Refused (step_up_required): y no cambia nada. emptyAudience nunca pide un código. La página Autenticación de la API enumera cada herramienta que lo pide y muestra cómo pedir un código y verificarlo.
Las herramientas aplican las mismas reglas y rechazos que la API REST, y las páginas de /automations y /events de la referencia de la API describen cada campo. Una definición se pasa entera como JSON: léela con getAutomation, cámbiala y pásala completa a updateAutomation.
Referencia
listAutomations
List the automations in this workspace, the most recently changed first: name, id, status (draft, live, paused or archived), what starts each one, its steps and how many contacts are in it now, completed it or left early. Use it to find an automation by name before reading or changing it. One page at a time: when more follow, the last line gives a cursor to pass back.
Entradas
statusstring- Uno de
"draft""live""paused""archived" limitinteger- Al menos 1Como máximo 100
cursorstring- De 1 a 64 caracteres
También disponible en
- API
GET /automations- TypeScript
automations.list()automations.listAll()automations.iterate()- Python
automations.list()automations.list_all()automations.iterate()- Ruby
automations.listautomations.list_allautomations.iterate- PHP
automations->listautomations->listAllautomations->iterate- Go
Automations.ListAutomations.ListAllAutomations.Iterate- Java
automations().listautomations().listAllautomations().iterate- C#
Automations.ListAsyncAutomations.ListAllAsyncAutomations.IterateAsync
getAutomation
Read one automation: its status, settings, numbers, what is wrong with its draft, and the draft definition (trigger and steps) as JSON, to change and pass back to updateAutomation. includePublished adds the definition of the version that is running, which differs from the draft while there are unpublished changes.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteresincludePublishedboolean- Predeterminado
false
También disponible en
listAutomationStarters
The ready-made automations a new one can begin from, such as a welcome series or a birthday note: slug, name, what each is for and its definition as JSON. Pass a slug to createAutomation as starter. A starter leaves the audience, the templates and the from address empty to fill in.
Entradas
No recibe entradas.
También disponible en
createAutomation
Create an automation as a draft: from a starter (listAutomationStarters names them), from a definition written out as JSON, or empty. Nothing runs until publishAutomation. The answer lists what the draft still needs before it can be published, such as a template or a from address for each email. Find audiences with listAudiences, templates with listTemplates and forms with listForms.
Entradas
namestringObligatorioA short name for the automation. Contacts never see it.
De 1 a 120 caracteresdescriptionstringOne line about what it is for.
Hasta 500 caracteresstarterstring- De 1 a 64 caracteres
definitionRecord<string, any> | stringThe trigger and steps as JSON: {"trigger": {...}, "entry": "<key of the first step>", "steps": [...]}. Triggers: {"kind": "audience_joined", "audienceId", "includeImported": false}, {"kind": "form_submitted", "formId"}, {"kind": "event", "eventName", "filters": []}, {"kind": "date", "field": "birthday" or "joined", "audienceId", "offsetDays": 0} and {"kind": "manual"}. Every step has a unique key of 3 to 24 lowercase letters and digits starting with a letter, and points at the next step by key in next, or null to end the path. Steps: {"kind": "send_email", "key", "next", "templateId", "templateVersion": null, "from": {"email", "name"}, "replyTo": null, "subject": null, "props": {}}, {"kind": "wait", "key", "next", "wait": {"mode": "duration", "amount": 3, "unit": "days"}}, {"kind": "branch", "key", "condition": {"kind": "email_clicked", "stepKey"}, "yes", "no"}, {"kind": "add_to_audience" or "remove_from_audience", "key", "next", "audienceId"}, {"kind": "update_field", "key", "next", "field", "value": {"source": "static", "value"}}, {"kind": "webhook", "key", "next", "endpointId"} and {"kind": "exit", "key"}. A wait can also be {"mode": "until", "weekdays": [1], "hour": 9, "minute": 0} or {"mode": "event", "eventName", "timeout": {"amount": 7, "unit": "days"}}. Conditions: email_opened and email_clicked with stepKey, in_audience with audienceId, field with field, operator and value, and event with eventName and withinDays. A props value is {"source": "static", "value"}, {"source": "contact", "field"} or {"source": "event", "path"}. Paths never join or loop. getAutomation shows a saved definition in this shape, and listAutomationStarters has ready-made ones.
settingsRecord<string, any> | stringHow it runs, as JSON with any of: timezone (an IANA zone such as Europe/London), sendWindow ({"days": [1, 2, 3, 4, 5], "startMinute": 540, "endMinute": 1020} or null for any time), reentryDays (days after finishing before a contact may enter again, or null for once only), exitOnLeave (true takes a contact out when they leave the audience that started it) and listAudienceId (the audience unsubscribes are recorded in).
También disponible en
updateAutomation
Change an automation. Its name, description and settings apply at once. definition replaces the whole draft, so start from getAutomation, change the JSON and pass all of it back. A live automation keeps running its published version until publishAutomation, and contacts already in it stay on the version they entered on. Pass only what changes.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteresnamestring- De 1 a 120 caracteres
descriptionstring- Puede ser nullHasta 500 caracteres
definitionRecord<string, any> | stringThe trigger and steps as JSON: {"trigger": {...}, "entry": "<key of the first step>", "steps": [...]}. Triggers: {"kind": "audience_joined", "audienceId", "includeImported": false}, {"kind": "form_submitted", "formId"}, {"kind": "event", "eventName", "filters": []}, {"kind": "date", "field": "birthday" or "joined", "audienceId", "offsetDays": 0} and {"kind": "manual"}. Every step has a unique key of 3 to 24 lowercase letters and digits starting with a letter, and points at the next step by key in next, or null to end the path. Steps: {"kind": "send_email", "key", "next", "templateId", "templateVersion": null, "from": {"email", "name"}, "replyTo": null, "subject": null, "props": {}}, {"kind": "wait", "key", "next", "wait": {"mode": "duration", "amount": 3, "unit": "days"}}, {"kind": "branch", "key", "condition": {"kind": "email_clicked", "stepKey"}, "yes", "no"}, {"kind": "add_to_audience" or "remove_from_audience", "key", "next", "audienceId"}, {"kind": "update_field", "key", "next", "field", "value": {"source": "static", "value"}}, {"kind": "webhook", "key", "next", "endpointId"} and {"kind": "exit", "key"}. A wait can also be {"mode": "until", "weekdays": [1], "hour": 9, "minute": 0} or {"mode": "event", "eventName", "timeout": {"amount": 7, "unit": "days"}}. Conditions: email_opened and email_clicked with stepKey, in_audience with audienceId, field with field, operator and value, and event with eventName and withinDays. A props value is {"source": "static", "value"}, {"source": "contact", "field"} or {"source": "event", "path"}. Paths never join or loop. getAutomation shows a saved definition in this shape, and listAutomationStarters has ready-made ones.
settingsRecord<string, any> | stringHow it runs, as JSON with any of: timezone (an IANA zone such as Europe/London), sendWindow ({"days": [1, 2, 3, 4, 5], "startMinute": 540, "endMinute": 1020} or null for any time), reentryDays (days after finishing before a contact may enter again, or null for once only), exitOnLeave (true takes a contact out when they leave the audience that started it) and listAudienceId (the audience unsubscribes are recorded in).
expectedUpdatedAtstringThe Updated time getAutomation gave. When somebody saved the automation since, the change is refused instead of written over theirs.
Formatodate-time
También disponible en
deleteAutomation
Delete an automation for good, with its versions, its enrollments and its numbers. Contacts in it stop at once. The emails it already sent stay. It cannot be undone: to retire one and keep its history, use archiveAutomation.
- Pide un código de verificación
DELETE /automations/{id}
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteres
También disponible en
publishAutomation
Publish an automation: its draft becomes the version that runs and it goes live, so its trigger starts putting contacts in and its emails start going out. Use it for a first publish and to put later changes to work. The draft has to be complete, and a refusal lists every problem that blocks it. Contacts already in it stay on the version they entered on.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteres
También disponible en
pauseAutomation
Pause a live automation. Nobody new enters, and everyone in it stays where they are and moves on when it is resumed with resumeAutomation.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteres
También disponible en
resumeAutomation
Turn a paused automation back on with the version it was running, without publishing the draft. Contacts that were held move on and its emails go out again. One that was paused because something it needs went away stays paused until that is fixed, and the refusal says what.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteres
También disponible en
archiveAutomation
Retire an automation for good and keep its history. Everyone in it leaves, nobody enters again and it can no longer be changed, published or resumed. Its versions, enrollments and numbers stay readable. To stop one for a while, use pauseAutomation.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteres
También disponible en
duplicateAutomation
Copy an automation into a new draft with "(copy)" after its name: the same draft definition and settings, and none of its versions, contacts or numbers.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteres
También disponible en
sendAutomationTest
Send the email of one step of the draft to one address, to read it before publishing. It goes to the user's own account address unless to names another. Contact values come from a sample contact, the subject starts with [Test], and nobody is enrolled. It counts toward the monthly sends.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteresstepKeystringObligatorioThe key of the email step, from the definition getAutomation returns.
De 1 a 64 caracterestostringWhere the test goes, when not to the user themselves.
Hasta 320 caracteresFormatoemail
También disponible en
listAutomationVersions
The published versions of an automation, the newest first: number, when it was published and whether it is the one running. includeDefinitions adds each definition as JSON. restoreAutomationVersion copies one back into the draft.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteresincludeDefinitionsboolean- Predeterminado
false
También disponible en
restoreAutomationVersion
Copy the definition of an earlier version back into the draft, replacing what the draft holds. Nothing that is running changes until publishAutomation.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteresversionintegerObligatorioThe version number, from listAutomationVersions.
Al menos 1
También disponible en
getAutomationStats
How one automation did over a window, 30 days by default: contacts that entered, are in it now, completed it or left early, emails sent, delivered, opened, clicked, bounced and marked as spam, and unsubscribes, in total and for each step. Opens are a floor, because many mail apps hide them. includeDaily adds a line for each day.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteressincestringWhere the window starts, as an ISO 8601 instant.
Formatodate-timeuntilstringWhere the window ends, as an ISO 8601 instant. Left out, now.
Formatodate-timeincludeDailyboolean- Predeterminado
false
También disponible en
listAutomationEnrollments
The contacts that are in an automation or have been, the most recent entry first: which step each is at, what they are waiting for, what holds a step that is due, when they move next and how it ended. Narrow it by status, by step or by a piece of the address or name. One page at a time: when more follow, the last line gives a cursor.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteresstatusstring- Uno de
"active""completed""exited" stepKeystring- De 1 a 64 caracteres
qstring- Hasta 200 caracteres
limitinteger- Al menos 1Como máximo 200
cursorstring- De 1 a 64 caracteres
También disponible en
- API
GET /automations/{id}/enrollments- TypeScript
automations.listEnrollments()automations.listAllEnrollments()automations.iterateEnrollments()- Python
automations.list_enrollments()automations.list_all_enrollments()automations.iterate_enrollments()- Ruby
automations.list_enrollmentsautomations.list_all_enrollmentsautomations.iterate_enrollments- PHP
automations->listEnrollmentsautomations->listAllEnrollmentsautomations->iterateEnrollments- Go
Automations.ListEnrollmentsAutomations.ListAllEnrollmentsAutomations.IterateEnrollments- Java
automations().listEnrollmentsautomations().listAllEnrollmentsautomations().iterateEnrollments- C#
Automations.ListEnrollmentsAsyncAutomations.ListAllEnrollmentsAsyncAutomations.IterateEnrollmentsAsync
getAutomationEnrollment
One contact's way through an automation: where they are, and what each step did for them, oldest first, such as an email sent, a wait, a yes or no at a branch, or why a step was skipped or failed.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteresenrollmentIdstringObligatorioThe enrollment, by id (aen_...), from listAutomationEnrollments.
De 1 a 64 caracteres
También disponible en
enrollInAutomation
Put one contact into a live automation at its first step, whatever starts it normally, so its emails start going to them. The contact has to exist already. A contact is in an automation once at a time, and an address that is suppressed or unsubscribed is refused.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteresemailstringObligatorioThe contact to enroll, by email address.
Hasta 320 caracteresFormatoemaildataRecord<string, any>Values the steps read wherever a value comes from the event, such as an order number. At most 50 keys and 4 KB of JSON.
También disponible en
removeFromAutomation
Take one contact out of an automation at once, by the id of their enrollment from listAutomationEnrollments. They get nothing more from it, and stay in the contacts and in their audiences.
Entradas
idstringObligatorioThe automation, by id (aut_...). listAutomations finds it by name.
De 1 a 64 caracteresenrollmentIdstringObligatorioThe enrollment, by id (aen_...), from listAutomationEnrollments.
De 1 a 64 caracteres
También disponible en
sendContactEvent
Record that something happened to one contact, such as order.placed or trial.started. Every live automation that starts on that event name takes the contact in, so its emails start going to them, and a wait step holding out for the name moves on. The answer says which automations it started. Events are kept for 90 days.
Entradas
namestringObligatorioWhat happened, such as order.placed: letters, digits, dots, colons, dashes and underscores. Names are matched exactly, case included.
De 1 a 100 caracteresemailstringObligatorioThe contact the event is about, by email address.
Hasta 320 caracteresFormatoemailpropertiesRecord<string, any>Details of the event as a JSON object, at most 50 keys and 4 KB. An event trigger can filter on them and steps can use them.
occurredAtstringWhen it happened, as an ISO 8601 instant. Left out, it is now. Not in the future, and at most 90 days ago.
Formatodate-timecreateContactbooleantrue adds the address to the contacts when nobody has it yet.
contactNamestringThe name to give a contact that createContact adds.
Hasta 200 caracteres
sendContactEvents
Record up to 100 events in one call, each handled as sendContactEvent handles one, in order. One event failing does not stop the rest: the answer says which were recorded, what each started, and why any was not.
Entradas
eventsobject[]Obligatorio- De 1 a 100 elementos
namestringObligatorioWhat happened, such as order.placed: letters, digits, dots, colons, dashes and underscores. Names are matched exactly, case included.
De 1 a 100 caracteresemailstringObligatorioThe contact the event is about, by email address.
Hasta 320 caracteresFormatoemailpropertiesRecord<string, any>Details of the event as a JSON object, at most 50 keys and 4 KB. An event trigger can filter on them and steps can use them.
occurredAtstringWhen it happened, as an ISO 8601 instant. Left out, it is now. Not in the future, and at most 90 days ago.
Formatodate-timecreateContactbooleantrue adds the address to the contacts when nobody has it yet.
contactNamestringThe name to give a contact that createContact adds.
Hasta 200 caracteres
listContactEventNames
The names of the events this workspace has recorded in the last 90 days, to choose the event that starts an automation or that a wait step holds out for.
Entradas
No recibe entradas.
También disponible en
listContactEvents
The events recorded for one contact in the last 90 days, the most recent first: name, when it happened and its properties. Narrow it to one event name. One page at a time: when more follow, the last line gives a cursor.
Entradas
emailstringObligatorioThe contact the event is about, by email address.
De 3 a 320 caracteresnamestring- De 1 a 100 caracteres
limitinteger- Al menos 1Como máximo 200
cursorstring- De 1 a 64 caracteres
También disponible en
- API
GET /contacts/{email}/events- TypeScript
contacts.listEvents()contacts.listAllEvents()contacts.iterateEvents()- Python
contacts.list_events()contacts.list_all_events()contacts.iterate_events()- Ruby
contacts.list_eventscontacts.list_all_eventscontacts.iterate_events- PHP
contacts->listEventscontacts->listAllEventscontacts->iterateEvents- Go
Contacts.ListEventsContacts.ListAllEventsContacts.IterateEvents- Java
contacts().listEventscontacts().listAllEventscontacts().iterateEvents- C#
Contacts.ListEventsAsyncContacts.ListAllEventsAsyncContacts.IterateEventsAsync