Schedules
Schedule a job for an agent
On each date of the cron, in the timezone you send, the agent gets the goal as a run and writes first by email to the contact, with a file from one of its granted actions if it needs one. If the contact answers, the same agent keeps the conversation by email. The run is unattended: the agent never stops to ask a person, so write a goal it can finish alone. Send the contact as contactId or externalRef, exactly one; the contact needs an email address, and the agent needs the email channel and an active status. from must belong to a verified domain. A date missed while the service was down is not replayed. A contact that opted out or is outside the recipient allowlist is skipped with schedule.skipped. Three runs in a row that fail pause the task with schedule.paused. Use dryRun=true to run the same checks and see the task as it would be created, without saving it.
Required scope: schedules:write.
path Parameters
id^agt_[0-9A-Za-z]{22}… · requiredThe id of the agent (agt_…).
query Parameters
dryRunWhen true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus dryRun: true; an id in it is not saved. It does not use the Idempotency-Key.
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Idempotency-KeyMakes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Schedule a job for an agent › Request Body
namecronFive fields: minute hour day-of-month month day-of-week. It is read in the timezone below. 422 invalid_cron if it cannot be read.
goalThe job the agent gets on each date, as in a run. The agent runs it unattended: it never stops to ask.
channelHow the agent reaches the contact. Only email today. The agent needs the email channel.
timezoneAn IANA timezone. 422 invalid_timezone if it is not one.
fromThe sender. Its domain must be verified (POST /v2/email/domains). Without it the first verified domain is used.
enabledSchedule a job for an agent › Responses
objectidagentIdcontactIdnamecrontimezonegoalWhat the agent is asked to do on each date.
channelfromThe limits each run gets, after the server maximums.
enabledpausedReasonWhy the platform paused the task. consecutive_failures: three runs in a row failed or were cut.
nextRunAtWhen it fires next. A date missed while it was off is not replayed.
lastRunAtcreatedAtupdatedAtdryRunPresent and true when the request had dryRun=true.
List scheduled tasks
The scheduled tasks of your organization, newest first. Filter by agentId. Read only and safe to repeat.
Required scope: schedules:read.
query Parameters
limitcursorThe nextCursor of the previous page, with the same filters.
agentIdHeaders
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
List scheduled tasks › Responses
objecthasMorenextCursorRetrieve a scheduled task
When it fires next, when it fired last and whether the platform paused it. Read only and safe to repeat.
Required scope: schedules:read.
path Parameters
id^sch_[0-9A-Za-z]{22}… · requiredThe id of the schedule (sch_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Retrieve a scheduled task › Responses
objectidagentIdcontactIdnamecrontimezonegoalWhat the agent is asked to do on each date.
channelfromThe limits each run gets, after the server maximums.
enabledpausedReasonWhy the platform paused the task. consecutive_failures: three runs in a row failed or were cut.
nextRunAtWhen it fires next. A date missed while it was off is not replayed.
lastRunAtcreatedAtupdatedAtDelete a scheduled task
It stops firing now. Runs it already started keep going and stay readable. It cannot be undone.
Required scope: schedules:write.
path Parameters
id^sch_[0-9A-Za-z]{22}… · requiredThe id of the schedule (sch_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Delete a scheduled task › Responses
Change a scheduled task
Changes only what you send. A new cron or timezone recomputes nextRunAt from now. enabled false pauses it; enabled true turns it on again from now, clears a pause made by the platform and does not replay dates missed meanwhile. Safe to repeat with the same body.
Required scope: schedules:write.
path Parameters
id^sch_[0-9A-Za-z]{22}… · requiredThe id of the schedule (sch_…).
Headers
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Change a scheduled task › Request Body optional
namecrontimezonegoalenabledfalse pauses the task. true turns it on again from now, clears a platform pause and does not replay missed dates.
Change a scheduled task › Responses
objectidagentIdcontactIdnamecrontimezonegoalWhat the agent is asked to do on each date.
channelfromThe limits each run gets, after the server maximums.
enabledpausedReasonWhy the platform paused the task. consecutive_failures: three runs in a row failed or were cut.
nextRunAtWhen it fires next. A date missed while it was off is not replayed.
lastRunAtcreatedAtupdatedAtFire a scheduled task now
Use it to see a scheduled task work without waiting for its date: it starts one run of the agent as the clock would and publishes schedule.fired, or schedule.skipped when the contact cannot be written to. It sends a real email to the contact, so point the task at a contact of yours while you try it. It does not move nextRunAt and does not use up the next real date, so the task still fires on its schedule, and you can call it as many times as you need. A paused task can be fired too. Send the same Idempotency-Key to retry safely; it is required. The answer is 202: the agent works afterwards, read the run with GET /v2/runs/{id}.
Required scope: schedules:write.
path Parameters
id^sch_[0-9A-Za-z]{22}… · requiredThe id of the schedule (sch_…).
Headers
Idempotency-KeyRequired on this operation: without it the answer is 400. Makes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.
Lelemon-Subaccount^sub_[0-9A-Za-z]{22}…The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.
Fire a scheduled task now › Responses
objectstatusskipReasonWhy no run started. Set with status skipped.