client.automations
Cada método deste espaço de nomes: a sua assinatura, os seus parâmetros, o que devolve e um exemplo.
Métodos
Emails and other steps that run by themselves for each contact, such as a welcome series or a birthday note: build a draft from a starter or your own trigger and steps, publish, pause, resume and archive it, send a test, read its versions and statistics, and enroll contacts or take them out.
automations.list
List one page of the automations in the workspace
list(status: nil, limit: nil, cursor: nil, api_key: nil) -> OpenEmail::PageReturns one page of the automations the caller can reach, the most recently saved first, without their definitions or settings. Paging is keyset: limit: takes 1 to 100 and defaults to 50, and next_cursor goes back as cursor: while has_more? is true. list_all and iterate do that walk for you.
Each automation carries its status, triggerKind, how many steps and emails the draft holds, hasUnpublishedChanges, publishedVersion and counts: the contacts in it now, and the ones that completed or left in all its time, counted at the moment of the read. A paused automation says why in pausedReason.
Read one with get for the draft definition, the published one, the settings and the problems that would stop a publish.
Parâmetros
statusStringOnly automations in this state:
draft,live,pausedorarchived.limitIntegerRows per page, a whole number from 1 to 100. The server defaults to 50.
cursorStringThe
next_cursorfrom the previous page, passed back exactly as it came. One that names no automation is a 400invalid_cursor.api_keyStringOverrides the client's API key for this call only.
Devolve
An OpenEmail::Page with items, has_more? and next_cursor. Each item is a Hash with id, name, description, status, triggerKind, stepCount, emailCount, hasUnpublishedChanges, publishedVersion, pausedReason, lastError, counts, createdBy, publishedAt, pausedAt, archivedAt, createdAt and updatedAt.
Exemplo
page = client.automations.list(status: "live") page.items.each do |automation| puts "#{automation[:name]} #{automation[:triggerKind]} #{automation[:counts][:active]} in it now"endNotas
An app a member connected lists only the automations that member made. An API key and an app the owner connected list every automation in the workspace.
Read only, so the SDK retries it after a network failure like any other read.
Também disponível em
automations.list_all
Collect every automation you can reach into one array
list_all(status: nil, limit: nil, cursor: nil, api_key: nil) -> Array<Hash>Follows next_cursor from page to page and returns every automation the caller can reach, the most recently saved first, in the shape list returns. limit sets the page size of each request, not the total.
Parâmetros
statusStringOnly automations in this state:
draft,live,pausedorarchived.limitIntegerPage size per request, from 1 to 100, defaulting to 50 on the server.
cursorStringA
next_cursorfrom an earlier page to start after.api_keyStringOverrides the client's API key for every page of this walk.
Devolve
An Array of Hashes holding every automation across all pages, each shaped like an item of list.
Exemplo
automations = client.automations.list_all paused = automations.select { |automation| automation[:status] == "paused" } paused.each { |automation| puts "#{automation[:name]} #{automation[:pausedReason]}" }Notas
A failure on any page raises, and the automations already fetched are discarded.
Também disponível em
automations.iterate
Stream the automations you can reach one at a time
iterate(status: nil, limit: nil, cursor: nil, api_key: nil, &block) -> Enumerator<Hash>Returns an Enumerator that yields automations one by one, the most recently saved first, or passes each one to the block you give it. It requests the next page only once the current one is drained, and breaking out of the loop stops the requests.
Parâmetros
statusStringOnly automations in this state:
draft,live,pausedorarchived.limitIntegerPage size per request, from 1 to 100, defaulting to 50 on the server.
cursorStringA
next_cursorfrom an earlier page to start after.api_keyStringOverrides the client's API key for every page of this walk.
Devolve
An Enumerator of Hashes, one automation per step, each shaped like an item of list, or yields each one to a block.
Exemplo
client.automations.iterate do |automation| puts "unpublished edits: #{automation[:name]}" if automation[:hasUnpublishedChanges]endNotas
Pages are fetched only as the loop reaches them, so an abandoned loop costs only the pages you consumed.
Também disponível em
automations.create
Create an automation as a draft
create(body = nil, api_key: nil, **fields) -> HashMakes a draft automation and returns it whole, in the shape get returns. Its trigger and steps come from definition when you send one, from the starter named in starter when you do not, and otherwise the draft starts empty. settings changes any of the defaults.
A draft may be incomplete: problems in the answer lists what is still missing, such as a template or a from address a starter leaves for you. Nothing runs until publish, which needs a complete draft and emails:send.
Parâmetros
nameStringObrigatórioWhat the workspace calls the automation, trimmed, 1 to 120 characters. Contacts never see it, and it need not be unique.
descriptionString or nilA note for the workspace, at most 500 characters. Contacts never see it.
starterStringBegin from a starter, by the
sluglist_startersreturns:welcome-series,trial-follow-up,birthdayorwin-back. Ignored whendefinitionis sent. An unknown slug is 422invalid_automation.definitionHashThe trigger and the steps, in the shape
getreturns asdefinition.triggersays what starts the automation:audience_joinedwithaudienceIdandincludeImported,form_submittedwithformId,eventwitheventNameandfilters,datewithfield,audienceIdandoffsetDays, ormanual.entryis the key of the first step, andstepsholds every step:send_email,wait,branch,add_to_audience,remove_from_audience,update_field,webhookorexit. Each step has a uniquekeyof 3 to 24 lowercase letters and digits starting with a letter, and names the next step by key innext, or inyesandnofor a branch.nilends the path. Paths never join or loop, and a definition holds at most 50 steps. Leave it out to usestarteror an empty draft.settings.timezoneStringThe IANA time zone the sending window and waits until a day and time are read in, such as
Europe/London. Defaults toUTC.settings.sendWindowHash or nilWhen emails may go out:
daysof the week, where 0 is Sunday, andstartMinutetoendMinuteof the day, counted from midnight. An email due outside it waits for the window to open.nil, the default, sends at any time.settings.reentryDaysInteger or nilHow many days after a contact finishes before they may enter again, from 1 to 3650.
nil, the default, lets each contact through once only.settings.exitOnLeaveBooleanTake a contact out when they leave the audience that started the automation. Defaults to true.
settings.listAudienceIdString or nilThe audience an unsubscribe from one of these emails is recorded in.
nil, the default, uses the audience that starts the automation, or the built-in audience of every contact when no audience starts it. An id that is not an audience of the workspace is 422invalid_automation.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash, the automation as get returns it: the fields of a list item with status draft, plus definition, published, which is nil, settings and problems.
Exemplo
automation = client.automations.create( name: "Welcome series", starter: "welcome-series", settings: {timezone: "Europe/London"}) automation[:problems].each { |problem| puts "#{problem[:path]} #{problem[:message]}" }Notas
A value of the wrong type or length is 422
invalid_parameterwithparamnaming it, and a key the body does not take is 422unknown_parameter. A definition that breaks a rule of its structure, such as two steps with one key or two paths into one step, is 422invalid_automation, andproblemson the error lists each one.A workspace holds a limited number of automations, drafts included, and support can raise that for a workspace that needs more. The next one past the limit is 422
workspace_limit_reached.Not retried automatically, and nothing deduplicates by name, so a retry after a lost response can leave two drafts. List them and delete the spare.
Também disponível em
automations.list_starters
List the ready-made automations to start from
list_starters(api_key: nil) -> Array<Hash>Returns the starting points the app offers when somebody makes an automation: a welcome series, a trial follow-up, a birthday note and a win-back. Each comes with its whole definition, so you can read it, change it and send it to create, or pass its slug to create as starter.
A starter leaves the audience, the templates and the from address as empty strings for you to fill in. The list is the same for every workspace and is not paginated.
Parâmetros
api_keyStringOverrides the client's API key for this call only.
Devolve
An Array of Hashes, each with slug, name, description and definition.
Exemplo
starters = client.automations.list_starters starters.each { |starter| puts "#{starter[:slug]} #{starter[:description]}" }Notas
Read only, so the SDK retries it after a network failure like any other read.
Também disponível em
automations.get
Retrieve an automation with its definition and settings
get(id, api_key: nil) -> HashReturns the whole automation: the draft definition you edit, published, the definition of the version that is running, settings, fresh counts and problems.
problems is what is wrong with the draft at the moment of the read, each with a code, the path of the field, the stepKey, a message and blocking, which is false for a warning. An empty list means the draft is ready, though publish checks more: that every template can be sent and that the caller may send from every from address.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash with id, name, description, status, triggerKind, stepCount, emailCount, hasUnpublishedChanges, publishedVersion, pausedReason, lastError, counts, createdBy, publishedAt, pausedAt, archivedAt, createdAt and updatedAt, plus definition, published, settings and problems.
Exemplo
automation = client.automations.get("aut_5c1e9a7b3d2f48e6a0b4c7d1") puts automation[:status], automation.dig(:definition, :trigger, :kind), automation[:definition][:steps].size automation[:problems].select { |problem| problem[:blocking] }.each { |problem| puts problem[:message] }Notas
An id that names no automation the caller can reach is 404
automation_not_found, whether it does not exist or belongs to another workspace.Read only, so the SDK retries it after a network failure like any other read.
Também disponível em
automations.update
Change the draft, the settings or the name of an automation
update(id, patch = nil, api_key: nil, **fields) -> HashA partial update that returns the automation whole. definition replaces the draft, and a live automation keeps running its published version until you publish again, so an edit never changes the path of a contact who is halfway through. settings is merged field by field and takes effect at once.
Read the automation, change it and send expectedUpdatedAt with the updatedAt you read. If someone saved it in between, the call is refused with 409 version_conflict instead of writing over their change.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.nameStringNew name, trimmed, 1 to 120 characters.
descriptionString or nilNew note, at most 500 characters.
nilclears it.definitionHashThe new draft, whole. The trigger and the steps, in the shape
getreturns asdefinition.triggersays what starts the automation:audience_joinedwithaudienceIdandincludeImported,form_submittedwithformId,eventwitheventNameandfilters,datewithfield,audienceIdandoffsetDays, ormanual.entryis the key of the first step, andstepsholds every step:send_email,wait,branch,add_to_audience,remove_from_audience,update_field,webhookorexit. Each step has a uniquekeyof 3 to 24 lowercase letters and digits starting with a letter, and names the next step by key innext, or inyesandnofor a branch.nilends the path. Paths never join or loop, and a definition holds at most 50 steps.settings.timezoneStringThe IANA time zone the sending window and waits until a day and time are read in, such as
Europe/London. Defaults toUTC.settings.sendWindowHash or nilWhen emails may go out:
daysof the week, where 0 is Sunday, andstartMinutetoendMinuteof the day, counted from midnight. An email due outside it waits for the window to open.nil, the default, sends at any time.settings.reentryDaysInteger or nilHow many days after a contact finishes before they may enter again, from 1 to 3650.
nil, the default, lets each contact through once only.settings.exitOnLeaveBooleanTake a contact out when they leave the audience that started the automation. Defaults to true.
settings.listAudienceIdString or nilThe audience an unsubscribe from one of these emails is recorded in.
nil, the default, uses the audience that starts the automation, or the built-in audience of every contact when no audience starts it. An id that is not an audience of the workspace is 422invalid_automation.expectedUpdatedAtStringThe
updatedAtyou read, as an ISO 8601 instant. When the automation was saved since, the call is refused with 409version_conflictand nothing is written.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash, the automation as get returns it after the save, with a new updatedAt and, when the draft changed, hasUnpublishedChanges true on a published automation.
Exemplo
current = client.automations.get("aut_5c1e9a7b3d2f48e6a0b4c7d1") saved = client.automations.update( current[:id], settings: {sendWindow: {days: [1, 2, 3, 4, 5], startMinute: 540, endMinute: 1020}}, expectedUpdatedAt: current[:updatedAt]) p saved[:settings][:sendWindow], saved[:updatedAt]Notas
An archived automation cannot be changed and answers 409
automation_archived.A value of the wrong type or length is 422
invalid_parameter, a key the patch does not take is 422unknown_parameter, and a definition that breaks a rule of its structure is 422invalid_automationwithproblemson the error.Retried automatically on network failure and retryable statuses, since saving the same patch twice leaves the same automation. With
expectedUpdatedAt, a retry after a lost response answers 409version_conflict: read the automation to see that your change is there.
Também disponível em
automations.delete
Delete an automation with its versions and history
delete(id, api_key: nil) -> HashDeletes the automation with its versions, its enrollments and its statistics. Contacts in it stop at once and get nothing more. The emails it already sent stay in emails.list.
There is no undo. To retire an automation and keep its history, use archive.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash with object set to automation, id and deleted set to true.
Exemplo
removed = client.automations.delete("aut_5c1e9a7b3d2f48e6a0b4c7d1") puts removed[:id], removed[:deleted]Notas
An OAuth access token needs a verification code for this call, and is refused with 403
step_up_requireduntil the app has verified one in the last 60 minutes.step_up_required?on the error says so. An API key is never asked for a code.The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
Também disponível em
automations.publish
Publish the draft and turn the automation on
publish(id, api_key: nil) -> HashSaves the draft as the next version and sets the automation live, so its trigger starts taking contacts in. Contacts already in it stay on the version they entered on. Publishing a paused automation turns it back on. It takes no body.
The draft has to be complete: a trigger, at least one step, every email with a published template that declares unsubscribeUrl and a from address the caller may send as, and every audience, form and webhook it names still there. Anything else is 422 invalid_automation, and problems on the error lists every problem that blocks it.
The automation sends as whoever published it. When that API key is revoked, expires or is turned off, the automation pauses itself with pausedReason key_revoked.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash, the automation as get returns it, with status live, a new publishedAt, the publishedVersion that is now running and hasUnpublishedChanges false.
Exemplo
automation = client.automations.publish("aut_5c1e9a7b3d2f48e6a0b4c7d1") puts automation[:status], automation[:publishedVersion], automation[:publishedAt]Notas
A plan covers a number of live automations: 1 on Free, 10 on Starter and 50 on Business, with no limit on Enterprise. One more is 403
automation_limit_reached. Pause one, or upgrade.An archived automation answers 409
automation_archived.Publishing a draft that has not changed since the last publish keeps the same version number.
Retried automatically on network failure and retryable statuses, since publishing the same draft twice leaves the same live version.
Também disponível em
automations.pause
Stop a live automation without losing anybody
pause(id, api_key: nil) -> HashStops a live automation. Nobody new enters, and everyone in it stays where they are and moves on when it is resumed. The automation.paused webhook event fires. Pausing a paused automation changes nothing. It takes no body.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash, the automation as get returns it, with status paused, pausedReason manual and pausedAt set.
Exemplo
automation = client.automations.pause("aut_5c1e9a7b3d2f48e6a0b4c7d1") puts automation[:status], automation[:pausedReason], automation[:counts][:active]Notas
A draft that was never published answers 409
automation_not_published, and an archived automation 409automation_archived.Retried automatically on network failure and retryable statuses, since pausing twice leaves the same paused automation.
Também disponível em
automations.resume
Turn a paused automation back on
resume(id, api_key: nil) -> HashTurns a paused automation back on with the version it was running, without publishing the draft. Contacts that were held move on, and from now on it sends as the caller. Resuming a live automation changes nothing. It takes no body.
The published version is checked again first, exactly as publish checks a draft. An automation OpenEmail paused, because its from address, its templates or an audience went away, stays paused with 422 invalid_automation until what stopped it is fixed.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash, the automation as get returns it, with status live and pausedReason, pausedAt and lastError cleared.
Exemplo
automation = client.automations.resume("aut_5c1e9a7b3d2f48e6a0b4c7d1") puts automation[:status], automation[:publishedVersion]Notas
An automation with no published version answers 409
automation_not_published, an archived one 409automation_archived, and a plan that covers no more live automations 403automation_limit_reached.Retried automatically on network failure and retryable statuses, since resuming twice leaves the same live automation.
Também disponível em
automations.archive
Retire an automation for good and keep its history
archive(id, api_key: nil) -> HashRetires an automation. Everyone in it leaves with the exit reason archived, nobody enters again, and it can no longer be changed, published or resumed. Its versions, enrollments and statistics stay readable. Archiving an archived automation changes nothing. It takes no body.
An automation with many contacts in it empties in the background over the next minutes. To start again from its steps, use duplicate.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash, the automation as get returns it, with status archived and archivedAt set.
Exemplo
automation = client.automations.archive("aut_5c1e9a7b3d2f48e6a0b4c7d1") puts automation[:status], automation[:archivedAt]Notas
There is no way back from archived. To stop an automation for a while, use
pause.Retried automatically on network failure and retryable statuses, since archiving twice leaves the same archived automation.
Também disponível em
automations.duplicate
Copy an automation into a new draft
duplicate(id, api_key: nil) -> HashMakes a new draft with the same draft definition and settings, named after the original with (copy) on the end. The copy has no versions, no contacts and no statistics, and it works on an archived automation too. It takes no body.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash, the copy as get returns it, with its own id and status draft.
Exemplo
copy = client.automations.duplicate("aut_5c1e9a7b3d2f48e6a0b4c7d1") puts copy[:id], copy[:name], copy[:status]Notas
A workspace that already holds the most automations it may answers 422
workspace_limit_reached.Not retried automatically, so a retry after a lost response can leave two copies. List them and delete the spare.
Também disponível em
automations.send_test
Send yourself the email of one step
send_test(id, body = nil, api_key: nil, **fields) -> HashSends the email of one step of the draft to one address, so you can read it before publishing. Contact values are filled from a sample contact, values that come from an event are left empty, and the subject starts with [Test]. It counts toward the monthly sends, is not tracked and enrolls nobody.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.stepKeyStringObrigatórioThe
keyof the email step to send, from the draftdefinition.toStringWhere the test goes. Left out, it goes to the account email of the person the key or app acts for: the workspace owner for an API key.
api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash with automationId, emailId, the email as emails.get returns it, to and stepKey.
Exemplo
test = client.automations.send_test("aut_5c1e9a7b3d2f48e6a0b4c7d1", stepKey: "welcome", to: "[email protected]") puts test[:emailId], test[:to]Notas
A
stepKeythat names no step, a step that is not an email, or a template that cannot be sent is 422invalid_automationwithparamstepKey.The from address of the step has to be one the caller may send as, or the call is refused with 403
from_address_forbidden. A domain that cannot send yet is 409domain_not_sendable, and a plan with no sends left is 429send_quota_exceeded.Not retried automatically, because a retry after a lost response would send the test twice.
Também disponível em
automations.list_versions
List the published versions of an automation
list_versions(id, api_key: nil) -> Array<Hash>Returns every published version, the newest first, each with its whole definition. current marks the one that is running. A publish that changed the definition adds a version, and each contact stays on the version they entered on. A draft that was never published has none. The list is not paginated.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.api_keyStringOverrides the client's API key for this call only.
Devolve
An Array of Hashes, each with id, automationId, version, definition, current, createdBy and createdAt.
Exemplo
versions = client.automations.list_versions("aut_5c1e9a7b3d2f48e6a0b4c7d1") versions.each { |version| puts "#{version[:version]} #{version[:current]} #{version[:createdAt]}" }Notas
Read only, so the SDK retries it after a network failure like any other read.
Também disponível em
automations.restore_version
Copy an earlier version back into the draft
restore_version(id, version, api_key: nil) -> HashCopies the definition of an earlier version into the draft, replacing what the draft holds. Nothing that is running changes until you publish. It takes no body.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.versionIntegerObrigatórioThe number of the version, from
list_versions. A whole number from 1 up.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash, the automation as get returns it, with the version in definition, and hasUnpublishedChanges true when it differs from the one that is running.
Exemplo
automation = client.automations.restore_version("aut_5c1e9a7b3d2f48e6a0b4c7d1", 2) puts automation[:hasUnpublishedChanges], automation[:definition][:steps].sizeNotas
A version the automation does not have is 404
automation_not_foundwithparamversion, and an archived automation is 409automation_archived.Retried automatically on network failure and retryable statuses, since restoring the same version twice leaves the same draft.
Também disponível em
automations.stats
Read how an automation has performed
stats(id, since: nil, until: nil, api_key: nil) -> HashReturns the numbers of an automation over a window: totals for the whole automation, steps with the same numbers step by step, and series with a point for each UTC day on which something happened. The window defaults to the last 30 days and reaches back at most 366 days before until:.
The steps are those of the published version, or of the draft when nothing is published. active in totals and the waiting of each step are counted at the moment of the read, whatever the window. Opens are a floor, because many mail apps hide them.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.sinceTime, Date or StringWhere the window starts, as a
Timeor an ISO 8601 string. Left out, 30 days beforeuntil:.untilTime, Date or StringWhere the window ends, as a
Timeor an ISO 8601 string. Left out, now. It has to be later thansince:.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash with automationId, since, until, totals (entered, active, completed, exited, sent, delivered, opened, clicked, bounced, complained and unsubscribed), steps and series.
Exemplo
stats = client.automations.stats("aut_5c1e9a7b3d2f48e6a0b4c7d1", since: "2026-09-01T00:00:00Z") p stats[:totals].values_at(:entered, :sent, :clicked) stats[:steps].each { |step| puts "#{step[:stepKey]} #{step[:kind]} #{step[:entered]} #{step[:waiting]}" }Notas
A time that is not an ISO 8601 instant, or an
until:that is not aftersince:, is 422invalid_parameter.Read only, so the SDK retries it after a network failure like any other read.
Também disponível em
automations.list_enrollments
List one page of the contacts in an automation
list_enrollments(id, status: nil, step_key: nil, q: nil, limit: nil, cursor: nil, api_key: nil) -> OpenEmail::PageReturns one page of everyone who is in the automation or has been, the most recent entry first. Each enrollment says who the contact is, the stepKey they are at, whether they are waiting and for which event, what holds a step that is due in heldFor, when they move next in nextRunAt, and how it ended in exitReason.
limit: takes 1 to 200 and defaults to 50. Pass next_cursor back as cursor:, with the same filters, while has_more? is true. list_all_enrollments and iterate_enrollments do that walk for you.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.statusStringOnly enrollments in this state:
active,completedorexited.step_keyStringOnly contacts at the step with this
key.qStringOnly contacts whose address or name contains this text, compared without case, up to 200 characters.
limitIntegerRows per page, a whole number from 1 to 200. The server defaults to 50.
cursorStringThe
next_cursorfrom the previous page, passed back exactly as it came. One that names no enrollment of this automation is a 400invalid_cursor.api_keyStringOverrides the client's API key for this call only.
Devolve
An OpenEmail::Page with items, has_more? and next_cursor. Each item is a Hash with id, automationId, version, contact, status, source, stepKey, waiting, waitingForEvent, heldFor, nextRunAt, exitReason, lastError, startedAt, finishedAt and updatedAt.
Exemplo
page = client.automations.list_enrollments("aut_5c1e9a7b3d2f48e6a0b4c7d1", status: "active") page.items.each do |enrollment| puts "#{enrollment[:contact][:email]} #{enrollment[:stepKey]} #{enrollment[:nextRunAt]}"endNotas
Read only, so the SDK retries it after a network failure like any other read.
Também disponível em
automations.list_all_enrollments
Collect every enrollment of an automation into one array
list_all_enrollments(id, status: nil, step_key: nil, q: nil, limit: nil, cursor: nil, api_key: nil) -> Array<Hash>Follows next_cursor from page to page and returns every enrollment that matches, the most recent entry first, in the shape list_enrollments returns. limit sets the page size of each request, not the total. An automation can hold a great many enrollments, so prefer iterate_enrollments when you do not need them all in memory.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.statusStringOnly enrollments in this state:
active,completedorexited.step_keyStringOnly contacts at the step with this
key.qStringOnly contacts whose address or name contains this text, compared without case, up to 200 characters.
limitIntegerPage size per request, from 1 to 200, defaulting to 50 on the server.
cursorStringA
next_cursorfrom an earlier page to start after.api_keyStringOverrides the client's API key for every page of this walk.
Devolve
An Array of Hashes holding every matching enrollment across all pages, each shaped like an item of list_enrollments.
Exemplo
exited = client.automations.list_all_enrollments("aut_5c1e9a7b3d2f48e6a0b4c7d1", status: "exited", limit: 200) unsubscribed = exited.count { |enrollment| enrollment[:exitReason] == "unsubscribed" } puts "#{unsubscribed} of #{exited.size} left by unsubscribing"Notas
A failure on any page raises, and the enrollments already fetched are discarded.
Também disponível em
automations.iterate_enrollments
Stream the enrollments of an automation one at a time
iterate_enrollments(id, status: nil, step_key: nil, q: nil, limit: nil, cursor: nil, api_key: nil, &block) -> Enumerator<Hash>Returns an Enumerator that yields enrollments one by one, the most recent entry first, or passes each one to the block you give it. It requests the next page only once the current one is drained, and breaking out of the loop stops the requests.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.statusStringOnly enrollments in this state:
active,completedorexited.step_keyStringOnly contacts at the step with this
key.qStringOnly contacts whose address or name contains this text, compared without case, up to 200 characters.
limitIntegerPage size per request, from 1 to 200, defaulting to 50 on the server.
cursorStringA
next_cursorfrom an earlier page to start after.api_keyStringOverrides the client's API key for every page of this walk.
Devolve
An Enumerator of Hashes, one enrollment per step, each shaped like an item of list_enrollments, or yields each one to a block.
Exemplo
client.automations.iterate_enrollments("aut_5c1e9a7b3d2f48e6a0b4c7d1", status: "active") do |enrollment| puts "#{enrollment[:contact][:email]} held for #{enrollment[:heldFor]}" if enrollment[:heldFor]endNotas
Pages are fetched only as the loop reaches them, so an abandoned loop costs only the pages you consumed.
Também disponível em
automations.get_enrollment
Retrieve one contact's way through an automation
get_enrollment(id, enrollment_id, api_key: nil) -> HashReturns one enrollment with runs: what each step did for the contact, oldest first, up to 200. A run has the stepKey, the kind of step, an outcome such as sent, waited, yes, no, skipped or failed, the emailId a send step produced and a detail that says why a step was skipped or failed.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.enrollment_idStringObrigatórioEnrollment id such as
aen_2b8d4f6a1c3e5079b6d8f0a2, fromlist_enrollments.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash with id, automationId, version, contact, status, source, stepKey, waiting, waitingForEvent, heldFor, nextRunAt, exitReason, lastError, startedAt, finishedAt and updatedAt, plus runs.
Exemplo
enrollment = client.automations.get_enrollment("aut_5c1e9a7b3d2f48e6a0b4c7d1", "aen_2b8d4f6a1c3e5079b6d8f0a2") enrollment[:runs].each { |run| puts "#{run[:createdAt]} #{run[:stepKey]} #{run[:outcome]} #{run[:detail]}" }Notas
An enrollment id that is not in this automation is 404
automation_enrollment_not_found.Read only, so the SDK retries it after a network failure like any other read.
Também disponível em
automations.enroll
Put a contact into a live automation
enroll(id, body = nil, api_key: nil, **fields) -> HashPuts one contact into a live automation at its first step, whatever its trigger is. Name the contact with email or contactId, never both. The contact has to exist already: save one with contacts.create first. data gives the steps the values they would otherwise read from an event.
A contact is in an automation once at a time, and comes back in only after settings.reentry_days. An address on the suppression list, or one that unsubscribed from the audience the automation sends through, is refused.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.emailStringThe contact, by email address. Send this or
contactId.contactIdStringThe contact, by id, as an event or another enrollment carries it. Send this or
email.dataHashValues the steps can read wherever a value comes from the event, such as an order number for an email. At most 50 keys and 4 KB of JSON.
api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash, the enrollment shaped like an item of list_enrollments, with status active, source api and nextRunAt now. The first step runs within about a minute.
Exemplo
enrollment = client.automations.enroll( "aut_5c1e9a7b3d2f48e6a0b4c7d1", email: "[email protected]", data: {plan: "team"}) puts enrollment[:id], enrollment[:status], enrollment[:nextRunAt]Notas
An automation that is a draft, paused or archived answers 409
automation_not_live. A contact who is in it, or finished it too recently, answers 409already_enrolled, and a suppressed or unsubscribed address 409contact_unreachable. An address or id nobody has is 404contact_not_found.Sending neither or both of
emailandcontactIdis 422invalid_parameter.Not retried automatically. After a lost response, a second attempt that answers 409
already_enrolledmeans the first one worked.
Também disponível em
automations.exit_enrollment
Take a contact out of an automation
exit_enrollment(id, enrollment_id, api_key: nil) -> HashEnds an active enrollment at once with the exit reason removed. The contact gets nothing more from this automation, and stays in the contacts and in their audiences. It takes no body.
Parâmetros
idStringObrigatórioAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.enrollment_idStringObrigatórioEnrollment id such as
aen_2b8d4f6a1c3e5079b6d8f0a2, fromlist_enrollments.api_keyStringOverrides the client's API key for this call only.
Devolve
A Hash, the enrollment shaped like an item of list_enrollments, with status exited, exitReason removed and finishedAt set.
Exemplo
enrollment = client.automations.exit_enrollment("aut_5c1e9a7b3d2f48e6a0b4c7d1", "aen_2b8d4f6a1c3e5079b6d8f0a2") puts enrollment[:status], enrollment[:exitReason], enrollment[:finishedAt]Notas
An enrollment that already completed or left answers 409
automation_enrollment_finished.Not retried automatically. After a lost response, a second attempt that answers 409
automation_enrollment_finishedmeans the first one worked.