openemail.automations
هر متد در این فضای نام: امضا، پارامترها، آنچه برمی‌گرداند و یک نمونه.
متدها
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(options?: AutomationListOptions): Promise<Page<AutomationResource>>Returns one page of the automations the caller can reach, the most recently saved first, without their definitions or settings. Paging is keyset: options.limit takes 1 to 100 and defaults to 50, and nextCursor goes back as options.cursor while hasMore is true. listAll 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.
پارامترها
options.statusAutomationStatusOnly automations in this state:
draft,live,pausedorarchived.options.limitnumberRows per page, a whole number from 1 to 100. The server defaults to 50.
options.cursorstringThe
nextCursorfrom the previous page, passed back exactly as it came. One that names no automation is a 400invalid_cursor.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
Page<AutomationResource> with items, hasMore and nextCursor. Each item has id, name, description, status, triggerKind, stepCount, emailCount, hasUnpublishedChanges, publishedVersion, pausedReason, lastError, counts, createdBy, publishedAt, pausedAt, archivedAt, createdAt and updatedAt.
نمونه
const page = await openemail.automations.list({ status: 'live' }) for (const automation of page.items) { console.log(automation.name, automation.triggerKind, `${automation.counts.active} in it now`)}نکته‌ها
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.
همچنین در دسترس در
automations.listAll()
Collect every automation you can reach into one array
listAll(options?: AutomationListOptions): Promise<Array<AutomationResource>>Follows nextCursor from page to page and resolves with 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.
پارامترها
options.statusAutomationStatusOnly automations in this state:
draft,live,pausedorarchived.options.limitnumberPage size per request, from 1 to 100, defaulting to 50 on the server.
options.cursorstringA
nextCursorfrom an earlier page to start after.options.signalAbortSignalCancels the request in flight and rejects the whole walk.
options.apiKeystringOverrides the client's API key for every page of this walk.
خروجی
Array<AutomationResource> holding every automation across all pages.
نمونه
const automations = await openemail.automations.listAll() const paused = automations.filter((automation) => automation.status === 'paused') for (const automation of paused) console.log(automation.name, automation.pausedReason)نکته‌ها
A failure on any page rejects the whole call.
همچنین در دسترس در
automations.iterate()
Stream the automations you can reach one at a time
iterate(options?: AutomationListOptions): AsyncGenerator<AutomationResource, void, undefined>Returns an async generator that yields automations one by one, the most recently saved first, and requests the next page only once the current one is drained. Breaking out of the loop stops the requests.
پارامترها
options.statusAutomationStatusOnly automations in this state:
draft,live,pausedorarchived.options.limitnumberPage size per request, from 1 to 100, defaulting to 50 on the server.
options.cursorstringA
nextCursorfrom an earlier page to start after.options.signalAbortSignalCancels the request in flight and rejects the whole walk.
options.apiKeystringOverrides the client's API key for every page of this walk.
خروجی
AsyncGenerator<AutomationResource, void, undefined> yielding one automation per step.
نمونه
for await (const automation of openemail.automations.iterate()) { if (automation.hasUnpublishedChanges) console.log('unpublished edits:', automation.name)}نکته‌ها
The generator is lazy, so an abandoned loop costs only the pages you consumed.
همچنین در دسترس در
automations.create()
Create an automation as a draft
create(body: AutomationCreate, options?: RequestScope): Promise<AutomationDetailResource>Makes 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.
پارامترها
body.namestringالزامیWhat the workspace calls the automation, trimmed, 1 to 120 characters. Contacts never see it, and it need not be unique.
body.descriptionstring | nullA note for the workspace, at most 500 characters. Contacts never see it.
body.starterstringBegin from a starter, by the
sluglistStartersreturns:welcome-series,trial-follow-up,birthdayorwin-back. Ignored whendefinitionis sent. An unknown slug is 422invalid_automation.body.definitionAutomationDefinitionThe 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. Null ends the path. Paths never join or loop, and a definition holds at most 50 steps. Leave it out to usestarteror an empty draft.body.settings.timezonestringThe IANA time zone the sending window and waits until a day and time are read in, such as
Europe/London. Defaults toUTC.body.settings.sendWindowAutomationSendWindow | nullWhen 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. Null, the default, sends at any time.body.settings.reentryDaysnumber | nullHow many days after a contact finishes before they may enter again, from 1 to 3650. Null, the default, lets each contact through once only.
body.settings.exitOnLeavebooleanTake a contact out when they leave the audience that started the automation. Defaults to true.
body.settings.listAudienceIdstring | nullThe audience an unsubscribe from one of these emails is recorded in. Null, 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 422
invalid_automation.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationDetailResource: the AutomationResource fields with status draft, plus definition, published, which is null, settings and problems.
نمونه
const automation = await openemail.automations.create({ name: 'Welcome series', starter: 'welcome-series', settings: { timezone: 'Europe/London' }}) for (const problem of automation.problems) console.log(problem.path, problem.message)نکته‌ها
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, and the error'sbodylists each one undererror.problems.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.
همچنین در دسترس در
automations.listStarters()
List the ready-made automations to start from
listStarters(options?: RequestScope): Promise<Array<AutomationStarterResource>>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.
پارامترها
options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
Array<AutomationStarterResource>, each with slug, name, description and definition.
نمونه
const starters = await openemail.automations.listStarters() for (const starter of starters) console.log(starter.slug, starter.description)نکته‌ها
Read only, so the SDK retries it after a network failure like any other read.
همچنین در دسترس در
automations.get()
Retrieve an automation with its definition and settings
get(id: string, options?: RequestScope): Promise<AutomationDetailResource>Returns 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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationDetailResource: 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.
نمونه
const automation = await openemail.automations.get('aut_5c1e9a7b3d2f48e6a0b4c7d1') console.log(automation.status, automation.definition.trigger?.kind, automation.definition.steps.length) for (const problem of automation.problems.filter((entry) => entry.blocking)) console.log(problem.message)نکته‌ها
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.
همچنین در دسترس در
automations.update()
Change the draft, the settings or the name of an automation
update(id: string, patch: AutomationPatch, options?: RequestScope): Promise<AutomationDetailResource>A 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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.patch.namestringNew name, trimmed, 1 to 120 characters.
patch.descriptionstring | nullNew note, at most 500 characters. Null clears it.
patch.definitionAutomationDefinitionThe 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. Null ends the path. Paths never join or loop, and a definition holds at most 50 steps.patch.settings.timezonestringThe IANA time zone the sending window and waits until a day and time are read in, such as
Europe/London. Defaults toUTC.patch.settings.sendWindowAutomationSendWindow | nullWhen 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. Null, the default, sends at any time.patch.settings.reentryDaysnumber | nullHow many days after a contact finishes before they may enter again, from 1 to 3650. Null, the default, lets each contact through once only.
patch.settings.exitOnLeavebooleanTake a contact out when they leave the audience that started the automation. Defaults to true.
patch.settings.listAudienceIdstring | nullThe audience an unsubscribe from one of these emails is recorded in. Null, 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 422
invalid_automation.patch.expectedUpdatedAtstringThe
updatedAtyou read, as an ISO 8601 instant. When the automation was saved since, the call is refused with 409version_conflictand nothing is written.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationDetailResource as it is after the save, with a new updatedAt and, when the draft changed, hasUnpublishedChanges true on a published automation.
نمونه
const current = await openemail.automations.get('aut_5c1e9a7b3d2f48e6a0b4c7d1') const saved = await openemail.automations.update(current.id, { settings: { sendWindow: { days: [1, 2, 3, 4, 5], startMinute: 540, endMinute: 1020 } }, expectedUpdatedAt: current.updatedAt}) console.log(saved.settings.sendWindow, saved.updatedAt)نکته‌ها
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_automation, with each problem undererror.problemsin the error'sbody.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.
همچنین در دسترس در
automations.delete()
Delete an automation with its versions and history
delete(id: string, options?: RequestScope): Promise<DeletedAutomationResource>Deletes 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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
DeletedAutomationResource, { object: 'automation', id, deleted: true }.
نمونه
const removed = await openemail.automations.delete('aut_5c1e9a7b3d2f48e6a0b4c7d1') console.log(removed.id, removed.deleted)نکته‌ها
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.isStepUpRequiredon 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.
همچنین در دسترس در
automations.publish()
Publish the draft and turn the automation on
publish(id: string, options?: RequestScope): Promise<AutomationDetailResource>Saves 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 the error's body lists every problem that blocks it under error.problems.
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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationDetailResource with status live, a new publishedAt, the publishedVersion that is now running and hasUnpublishedChanges false.
نمونه
const automation = await openemail.automations.publish('aut_5c1e9a7b3d2f48e6a0b4c7d1') console.log(automation.status, automation.publishedVersion, automation.publishedAt)نکته‌ها
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.
همچنین در دسترس در
automations.pause()
Stop a live automation without losing anybody
pause(id: string, options?: RequestScope): Promise<AutomationDetailResource>Stops 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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationDetailResource with status paused, pausedReason manual and pausedAt set.
نمونه
const automation = await openemail.automations.pause('aut_5c1e9a7b3d2f48e6a0b4c7d1') console.log(automation.status, automation.pausedReason, automation.counts.active)نکته‌ها
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.
همچنین در دسترس در
automations.resume()
Turn a paused automation back on
resume(id: string, options?: RequestScope): Promise<AutomationDetailResource>Turns 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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationDetailResource with status live and pausedReason, pausedAt and lastError cleared.
نمونه
const automation = await openemail.automations.resume('aut_5c1e9a7b3d2f48e6a0b4c7d1') console.log(automation.status, automation.publishedVersion)نکته‌ها
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.
همچنین در دسترس در
automations.archive()
Retire an automation for good and keep its history
archive(id: string, options?: RequestScope): Promise<AutomationDetailResource>Retires 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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationDetailResource with status archived and archivedAt set.
نمونه
const automation = await openemail.automations.archive('aut_5c1e9a7b3d2f48e6a0b4c7d1') console.log(automation.status, automation.archivedAt)نکته‌ها
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.
همچنین در دسترس در
automations.duplicate()
Copy an automation into a new draft
duplicate(id: string, options?: RequestScope): Promise<AutomationDetailResource>Makes 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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationDetailResource for the copy, with its own id and status draft.
نمونه
const copy = await openemail.automations.duplicate('aut_5c1e9a7b3d2f48e6a0b4c7d1') console.log(copy.id, copy.name, copy.status)نکته‌ها
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.
همچنین در دسترس در
automations.sendTest()
Send yourself the email of one step
sendTest(id: string, body: AutomationTestSend, options?: RequestScope): Promise<AutomationTestResource>Sends 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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.body.stepKeystringالزامیThe
keyof the email step to send, from the draftdefinition.body.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.
options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationTestResource with automationId, emailId, the email as emails.get returns it, to and stepKey.
نمونه
const test = await openemail.automations.sendTest('aut_5c1e9a7b3d2f48e6a0b4c7d1', { stepKey: 'welcome', to: '[email protected]'}) console.log(test.emailId, test.to)نکته‌ها
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.
همچنین در دسترس در
automations.listVersions()
List the published versions of an automation
listVersions(id: string, options?: RequestScope): Promise<Array<AutomationVersionResource>>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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
Array<AutomationVersionResource>, each with id, automationId, version, definition, current, createdBy and createdAt.
نمونه
const versions = await openemail.automations.listVersions('aut_5c1e9a7b3d2f48e6a0b4c7d1') for (const version of versions) console.log(version.version, version.current, version.createdAt)نکته‌ها
Read only, so the SDK retries it after a network failure like any other read.
همچنین در دسترس در
automations.restoreVersion()
Copy an earlier version back into the draft
restoreVersion(id: string, version: number, options?: RequestScope): Promise<AutomationDetailResource>Copies 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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.versionnumberالزامیThe number of the version, from
listVersions. A whole number from 1 up.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationDetailResource with the version in definition, and hasUnpublishedChanges true when it differs from the one that is running.
نمونه
const automation = await openemail.automations.restoreVersion('aut_5c1e9a7b3d2f48e6a0b4c7d1', 2) console.log(automation.hasUnpublishedChanges, automation.definition.steps.length)نکته‌ها
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.
همچنین در دسترس در
automations.stats()
Read how an automation has performed
stats(id: string, options?: AutomationStatsOptions): Promise<AutomationStatsResource>Returns 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. totals.active 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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.options.sinceDate | stringWhere the window starts, as a
Dateor an ISO 8601 string. Left out, 30 days beforeuntil.options.untilDate | stringWhere the window ends, as a
Dateor an ISO 8601 string. Left out, now. It has to be later thansince.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationStatsResource with automationId, since, until, totals (entered, active, completed, exited, sent, delivered, opened, clicked, bounced, complained and unsubscribed), steps and series.
نمونه
const stats = await openemail.automations.stats('aut_5c1e9a7b3d2f48e6a0b4c7d1', { since: '2026-09-01T00:00:00Z' }) console.log(stats.totals.entered, stats.totals.sent, stats.totals.clicked) for (const step of stats.steps) console.log(step.stepKey, step.kind, step.entered, step.waiting)نکته‌ها
A time that is not an ISO 8601 instant, or an
untilthat is not aftersince, is 422invalid_parameter.Read only, so the SDK retries it after a network failure like any other read.
همچنین در دسترس در
automations.listEnrollments()
List one page of the contacts in an automation
listEnrollments(id: string, options?: AutomationEnrollmentListOptions): Promise<Page<AutomationEnrollmentResource>>Returns 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.
options.limit takes 1 to 200 and defaults to 50. Pass nextCursor back as options.cursor, with the same filters, while hasMore is true. listAllEnrollments and iterateEnrollments do that walk for you.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.options.statusAutomationEnrollmentStatusOnly enrollments in this state:
active,completedorexited.options.stepKeystringOnly contacts at the step with this
key.options.qstringOnly contacts whose address or name contains this text, compared without case, up to 200 characters.
options.limitnumberRows per page, a whole number from 1 to 200. The server defaults to 50.
options.cursorstringThe
nextCursorfrom the previous page, passed back exactly as it came. One that names no enrollment of this automation is a 400invalid_cursor.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
Page<AutomationEnrollmentResource> with items, hasMore and nextCursor. Each item has id, automationId, version, contact, status, source, stepKey, waiting, waitingForEvent, heldFor, nextRunAt, exitReason, lastError, startedAt, finishedAt and updatedAt.
نمونه
const page = await openemail.automations.listEnrollments('aut_5c1e9a7b3d2f48e6a0b4c7d1', { status: 'active' }) for (const enrollment of page.items) { console.log(enrollment.contact.email, enrollment.stepKey, enrollment.nextRunAt)}نکته‌ها
Read only, so the SDK retries it after a network failure like any other read.
همچنین در دسترس در
automations.listAllEnrollments()
Collect every enrollment of an automation into one array
listAllEnrollments(id: string, options?: AutomationEnrollmentListOptions): Promise<Array<AutomationEnrollmentResource>>Follows nextCursor from page to page and resolves with every enrollment that matches, the most recent entry first, in the shape listEnrollments returns. limit sets the page size of each request, not the total. An automation can hold a great many enrollments, so prefer iterateEnrollments when you do not need them all in memory.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.options.statusAutomationEnrollmentStatusOnly enrollments in this state:
active,completedorexited.options.stepKeystringOnly contacts at the step with this
key.options.qstringOnly contacts whose address or name contains this text, compared without case, up to 200 characters.
options.limitnumberPage size per request, from 1 to 200, defaulting to 50 on the server.
options.cursorstringA
nextCursorfrom an earlier page to start after.options.signalAbortSignalCancels the request in flight and rejects the whole walk.
options.apiKeystringOverrides the client's API key for every page of this walk.
خروجی
Array<AutomationEnrollmentResource> holding every matching enrollment across all pages.
نمونه
const exited = await openemail.automations.listAllEnrollments('aut_5c1e9a7b3d2f48e6a0b4c7d1', { status: 'exited', limit: 200 }) const unsubscribed = exited.filter((enrollment) => enrollment.exitReason === 'unsubscribed') console.log(`${unsubscribed.length} of ${exited.length} left by unsubscribing`)نکته‌ها
A failure on any page rejects the whole call.
همچنین در دسترس در
automations.iterateEnrollments()
Stream the enrollments of an automation one at a time
iterateEnrollments(id: string, options?: AutomationEnrollmentListOptions): AsyncGenerator<AutomationEnrollmentResource, void, undefined>Returns an async generator that yields enrollments one by one, the most recent entry first, and requests the next page only once the current one is drained. Breaking out of the loop stops the requests.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.options.statusAutomationEnrollmentStatusOnly enrollments in this state:
active,completedorexited.options.stepKeystringOnly contacts at the step with this
key.options.qstringOnly contacts whose address or name contains this text, compared without case, up to 200 characters.
options.limitnumberPage size per request, from 1 to 200, defaulting to 50 on the server.
options.cursorstringA
nextCursorfrom an earlier page to start after.options.signalAbortSignalCancels the request in flight and rejects the whole walk.
options.apiKeystringOverrides the client's API key for every page of this walk.
خروجی
AsyncGenerator<AutomationEnrollmentResource, void, undefined> yielding one enrollment per step.
نمونه
for await (const enrollment of openemail.automations.iterateEnrollments('aut_5c1e9a7b3d2f48e6a0b4c7d1', { status: 'active' })) { if (enrollment.heldFor) console.log(enrollment.contact.email, 'held for', enrollment.heldFor)}نکته‌ها
The generator is lazy, so an abandoned loop costs only the pages you consumed.
همچنین در دسترس در
automations.getEnrollment()
Retrieve one contact's way through an automation
getEnrollment(id: string, enrollmentId: string, options?: RequestScope): Promise<AutomationEnrollmentDetailResource>Returns 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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.enrollmentIdstringالزامیEnrollment id such as
aen_2b8d4f6a1c3e5079b6d8f0a2, fromlistEnrollments.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationEnrollmentDetailResource: id, automationId, version, contact, status, source, stepKey, waiting, waitingForEvent, heldFor, nextRunAt, exitReason, lastError, startedAt, finishedAt and updatedAt, plus runs.
نمونه
const enrollment = await openemail.automations.getEnrollment('aut_5c1e9a7b3d2f48e6a0b4c7d1', 'aen_2b8d4f6a1c3e5079b6d8f0a2') for (const run of enrollment.runs) console.log(run.createdAt, run.stepKey, run.outcome, run.detail)نکته‌ها
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.
همچنین در دسترس در
automations.enroll()
Put a contact into a live automation
enroll(id: string, body: AutomationEnroll, options?: RequestScope): Promise<AutomationEnrollmentResource>Puts 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.reentryDays. An address on the suppression list, or one that unsubscribed from the audience the automation sends through, is refused.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.body.emailstringThe contact, by email address. Send this or
contactId.body.contactIdstringThe contact, by id, as an event or another enrollment carries it. Send this or
email.body.dataRecord<string, unknown>Values 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.
options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationEnrollmentResource with status active, source api and nextRunAt now. The first step runs within about a minute.
نمونه
const enrollment = await openemail.automations.enroll('aut_5c1e9a7b3d2f48e6a0b4c7d1', { email: '[email protected]', data: { plan: 'team' }}) console.log(enrollment.id, enrollment.status, enrollment.nextRunAt)نکته‌ها
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.
همچنین در دسترس در
automations.exitEnrollment()
Take a contact out of an automation
exitEnrollment(id: string, enrollmentId: string, options?: RequestScope): Promise<AutomationEnrollmentResource>Ends 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.
پارامترها
idstringالزامیAutomation id such as
aut_5c1e9a7b3d2f48e6a0b4c7d1.enrollmentIdstringالزامیEnrollment id such as
aen_2b8d4f6a1c3e5079b6d8f0a2, fromlistEnrollments.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
خروجی
AutomationEnrollmentResource with status exited, exitReason removed and finishedAt set.
نمونه
const enrollment = await openemail.automations.exitEnrollment('aut_5c1e9a7b3d2f48e6a0b4c7d1', 'aen_2b8d4f6a1c3e5079b6d8f0a2') console.log(enrollment.status, enrollment.exitReason, enrollment.finishedAt)نکته‌ها
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.