Repository navigation
Description
Note
🤖 Claude Opus 5.5 writing on behalf of Michael
One HTTP contract for sending transactional email from the server SDKs, so posthog-python and posthog-node behave the same.
- posthog-python template sends: Harley, now.
- The send API for code content and posthog-node: Michael, on top of the draft feat(node): send transactional email with the flat SDK contract posthog-js#5312.
The decisions come from the grilling in Silthus#525, the architecture in Silthus#526, and Michael and Harley's huddle on 2026-10-21 (follow-up notes). Origin: Slack thread.
TL;DR
sendtakes flat parameters in one of two forms: a template sent bytemplate_idwithtemplate_data, or code content named bytemplate_keywithsubject,htmlandtext. No content helpers.- One send endpoint,
POST /api/projects/@current/messaging/send/email/, on the app host, authenticated with the project secret key. Until it lands, template sends use/messaging_templates/{id}/send/. - A successful send returns the
message_id. It means PostHog stored the send in its queue for delivery, not that the email was delivered. - The checks that would skip a send later run before the
202, and a failed check returns an error withwhyandfix. No silent skips. - Every send has an idempotency key. The client makes one when the caller gives none, and retries with the same key. Callers can turn retries off.
- Always pass
distinct_id. Without it, the email's engagement events land on a person keyed by the email address, not on the app's user.
Client setup
| What | Contract |
|---|---|
| Client | The existing PostHog client, sync and async (AsyncPosthog in Python). Email is a namespace on it, posthog.emails, not a new client. |
| Auth | New client option secret_key / secretKey: a project secret API key (phs_). Send needs hog_flow:write. Read needs hog_flow:read. Without it, the call fails with missing_secret_key. |
| App host | New client option app_host / appHost, not api_host, because posthog-js uses that name for the ingestion host. When host is PostHog Cloud (us.i.posthog.com, us.posthog.com and the eu ones), the SDK derives the app host. Any other host may be a reverse proxy for ingestion, so the secret key never goes there: without app_host the call fails with missing_app_host. Self-hosted instances set app_host. |
| Retries | New client option max_retries / maxRetries, default 2 (3 attempts in total). 0 turns retries off. A send can override it. |
| Migration | Client option migrated_from / migratedFrom, such as "resend". Sent as X-PostHog-Migrated-From on every emails request. |
| Request context | Never used. The recipient is never the person of the current request context. |
Client interface (both SDKs)
Both SDKs expose this interface. Names follow each language: snake_case in Python, camelCase in Node. Python types the keyword arguments with a TypedDict and Unpack, the way capture does, with one @overload per form and a runtime check that exactly one form is passed.
emails.send(...) -> message_id, warnings # Python returns them, or raises. Node returns { data, error }
emails.get(id) -> EmailStatusRecord # later PR, with the status record
send(
to: string # one address
distinct_id?: string # always pass it in docs and examples. Absent: the address
idempotency_key?: string # absent: the SDK makes a UUID v4. Derive it from the email's
# purpose ("welcome:user_123") when a job runner retries
capture_engagement?: bool # code form only, default true. False turns it off for this send
max_retries?: int # overrides the client option
exactly one form:
# Template form. Templates made in PostHog have no key, so they are sent by id.
template_id: string # the template's UUID
template_data?: map # fills {{ variables.* }}. Sent as message_data
# Code form. Michael's send API.
template_key: string # names the email, so its metrics, logs and status group under it
subject: string
html?: string # at least one of html and text
text?: string # absent: the server derives it from html
from?: string # a verified sender. Absent: the project's default sender, else its only verified sender
reply_to?: string | string[]
cc?: string | string[] # at most 10 bare addresses, such as "jane@example.com"
bcc?: string | string[] # at most 10. Never shown to the other recipients
headers?: map<string, string> # at most 10 custom headers, such as { "X-Entity-Ref-ID": "order-123" }
tags?: { name, value }[] # at most 10. Added to the email's engagement events as $email_tags
attachments?: attachment[] # at most 10 files and 512 KB in total, after decoding
template_data?: map # absent: rendered content, sent as is and never stored.
# present: a local template. The SDK uploads it by hash when needed
)
warning = { code, message, fix }
error = { name, code, message, why?, fix?, status_code?, docs_url?, field?, retry_after? }
status = queued | waiting | unknown | skipped | failed | sent | delivered | bounced | complained
attachment = { filename, content, content_type?, content_id? }
# content: bytes (Python), Buffer or base64 string (Node)
# content_id: shows the file inline, as <img src="cid:...">
How the parameters map to the request:
| Parameter | Request |
|---|---|
to |
to |
distinct_id |
identifiers.distinct_id, left out when absent |
template_id |
Path /messaging_templates/{id}/send/ today, template: { id } on /messaging/send/email/ |
template_data |
message_data |
template_key, subject, html, text |
Rendered content: the same names on /messaging/send/email/ |
Code form with template_data |
Local template: template: { key: template_key, hash } plus message_data. The hash is #118924's content_hash v1. On 409 template_outdated the SDK uploads by key with if_code_managed: true and if_not_superseded: true and sends again once, with the same idempotency key. The caller never calls an upload. |
from, reply_to |
from, reply_to (a string becomes a one-item list) |
cc, bcc |
cc, bcc (a string becomes a one-item list) |
headers, tags |
headers, tags, as is |
attachments |
attachments[] of { filename, content, content_type, content_id }. The SDK base64-encodes content when it is bytes or a Buffer, and leaves a string as is |
capture_engagement |
capture_engagement on the code form, always sent: true when absent. Never sent with template_id |
idempotency_key |
Idempotency-Key header |
cc, bcc, headers, tags, attachments and capture_engagement work with both code-form cases, rendered content and a local template. With template_id the server refuses them, because a template made in PostHog sends with its own settings. The SDK refuses them before any request.
The template form moves from /messaging_templates/{id}/send/ to /messaging/send/email/ inside the SDK once #118924 lands, with no caller change.
Behavior both SDKs share
- Errors. The same fields in both SDKs. Node returns
{ data, error }like Resend's Node SDK. Python raises typed exceptions that carry the same fields, like Resend's Python SDK. - Retries. Network errors, the in-flight
409,429 throttledand503, with the same idempotency key every time.429 quota_limitedis never retried, because waiting doesn't fix a monthly quota. Retries wait 1 s and then 2 s with jitter, orRetry-Afterwhen it is longer. ARetry-Afterover 30 s fails the send at once, with the wait inretry_after(seconds in Python,retryAfterMsin Node), because a retry before it would break the rate limit.getnever retries. - SDK error codes. When PostHog did not answer with a code,
codeis one ofmissing_secret_key,missing_app_host,client_disabled,client_closed,network_error,api_error(an answer without a code) orunexpected_error. A disabled client sends nothing and fails withclient_disabled. A send aftershutdown()fails withclient_closed. Theirnameisservice_unavailablefornetwork_error,missing_api_keyformissing_secret_key, thenameof its status forapi_error(see Errors), andapplication_errorfor the others. - Local checks. The SDK checks the form, ids, keys and the idempotency key before any request. A failed check has
namevalidation_errorand a code such asinvalid_form,invalid_template_id,invalid_template_key,invalid_idempotency_keyorinvalid_message_id. Type checks only: the server holds the limits. - Suppression covers every recipient. When
to, a cc or a bcc address is suppressed, PostHog refuses the whole send with422 recipient_suppressed, and each address uses one unit of the project's sending cap. A spam complaint alone doesn't suppress an address for transactional email, because the recipient needs mail such as receipts and password resets. A bounce, a manual entry, or a complaint from an address that also bounces still suppresses it. - Attachment content is never logged and never repeated in an error. The SDK encodes it once, before the retry loop.
- User-Agent.
posthog-python/<version>orposthog-node/<version>. The server reads it assource: sdk. Send attribution in feat(messaging): attribute transactional sends to their source #120628 has to addposthog-python/. - Engagement capture. On the code form,
capture_engagementdefaults totrue, so a send captures opens and clicks unless the code passesfalse. A template sent bytemplate_idfollows the project's setting. A project whose admin turned engagement capture off captures nothing, whatever the send asks. - No events from the client. The SDK captures no event for a send. The send and its engagement events come from the server only, so nothing is counted twice.
- Warnings are logged. A send with warnings logs each one once through the client's logger, and returns them.
Errors
Every error body is { type, code, detail, attr, why, fix, docs_url }. code is PostHog's stable code to branch on. name follows Resend's error names, so migrated code that branches on it keeps working.
| Status | code |
name |
Retried |
|---|---|---|---|
202 |
Queued. A replayed key returns the first 202 with the same message_id. |
- | - |
400 |
Invalid field, or a check on the request failed: invalid_recipient, sender_not_verified, sender_not_allowed, sender_required, template_not_transactional, transactional_email_paused |
validation_error |
No |
401 |
Missing or invalid key, and the SDK's missing_secret_key |
missing_api_key |
No |
403 |
The key lacks the scope | invalid_permission |
No |
404 |
No template with this id, or the API is not enabled for the project | not_found |
No |
409 |
template_outdated: PostHog doesn't hold this local template's content, including a key it doesn't know yet. Nothing was sent |
validation_error |
The SDK uploads, then sends once more |
409 |
The same idempotency key is still in flight | concurrent_idempotent_requests |
Yes |
409 |
A local-template upload to a key whose content was edited in PostHog. Nothing was sent | validation_error |
No |
422 |
The email can't go out: sending_suspended (the project), sending_paused (this transactional email), recipient_suppressed, recipient_unreachable (the domain takes no email) |
validation_error |
No |
422 |
idempotency_key_reused: the key was used with another request. A template send and a code send never share a key |
invalid_idempotent_request |
No |
429 |
throttled: rate limited |
rate_limit_exceeded |
Yes |
429 |
quota_limited: the project is over its email quota |
monthly_quota_exceeded |
No |
503 |
The idempotency store or the email pipeline is down, or the pipeline did not confirm the send. The email may still go out, so retry only with the same idempotency key. | service_unavailable |
Yes |
5xx |
Anything else, and the SDK's unexpected_error |
application_error |
No |
An answer without a code, such as an HTML 503 from a proxy, is the SDK's api_error. It takes the name and retry of its status in this table, so a 503 is service_unavailable and is retried with the same idempotency key. A status the table doesn't list is application_error, not retried.
A field error names the field in attr, such as cc, headers, tags__0__name or attachments__0__filename, and detail says how to fix it. The server refuses:
- a cc or bcc entry that is not a bare address (no display name, no quotes, no commas), or more than 10;
- a header PostHog sets itself (
From,To,Cc,Bcc,Reply-To,Subject,Date,Message-ID,MIME-Version,Sender,Return-Path,Auto-Submitted, anyContent-*,X-PostHog-*orX-SES-*), a header name with spaces or colons, a value with line breaks or non-ASCII characters, a name set twice in another case, or more than 10 headers; - a tag name or value with characters other than ASCII letters, numbers,
_and-, a name that starts withph_, a name used twice, or more than 10 tags; - an attachment whose content is not base64 or is empty, more than 10 files or more than 512 KB in total, a file type mailbox providers block (such as
.exe), a filename with a path or line break, acontent_typethat is not a MIME type, or acontent_idwith<or>.
invalid_recipient, recipient_suppressed and recipient_unreachable let a caller skip a rejected recipient and still send to the others. Every refusal carries why and fix.
Idempotency
- The store is the one in feat(cdp): add a shared idempotency key store for workflows #120446, used by feat(messaging): add an idempotency key to the transactional email api #120392 and feat(cdp): accept an idempotency key on the transactional email route #120510. There is no second store.
- Scope
transactional-email, shared by template sends and code sends. - The fingerprint covers
template_idortemplate_key,to, the distinct ID,message_dataand the code content. - A template send replays on either URL,
/messaging_templates/{id}/send/or/messaging/send/email/, because both carry the same request. A key first used for a template send and then for a code send, or the other way round, answers422 idempotency_key_reused. - A replay returns the stored
202before any check runs. This covers a workflow paused since the first send, and a changed default sender when the caller named none. A deleted template, a local template whose content changed, or a project that no longer has a default sender still answers404,409or400. - A caller whose job runner already retries passes
max_retries=0and an idempotency key derived from the email's purpose. A generated UUID doesn't survive a job retry, and the docs say so.
Read (later PR)
GET /api/projects/@current/messaging/emails/{message_id}/ (proposed in the spec, Silthus#531) returns { id, status, created_at, status_at, reason? }.
statusis one of the values above. It is not Resend'slast_event.- Unknown ids, and ids in the first seconds after a send, return
404 not_found. No retries. - Needs
hog_flow:read. Reads have the same rates as sends, in their own buckets, so polling for status can't use up the send budget.
Code sends (decided in spec Silthus#531)
- Two cases, told apart by
template_data. Rendered content travels in the queued job and is never stored as a template version. A local template keeps the code as the source of truth: the SDK sends its hash, and uploads it only when PostHog doesn't hold that content. - Workflow per key. A
template_keythat names a template uses that template's transactional workflow. Any other key gets one workflow on its first send, made under a lock so two first sends make one. Metrics, logs and status group by the key. - Changes to feat(messaging): upload, send and lock code-managed email templates #118924's answers: a key PostHog doesn't know yet answers
409 template_outdated, not404, so the first send of a new local template uploads it. An upload withif_code_managed: truerefuses a template edited in PostHog with409, where an upload today adopts it. An upload without the flag behaves as before. - Sensitive by default. A key without a template makes a sensitive workflow, so a send's content stays out of the saved run history and a rerun skips it with a log line instead of sending it again. A key that names a template follows that template's sensitivity setting. The send API has no
sensitivefield (feat(messaging): send an email with inline html from code #127123). - Text. When only
htmlis present, the server derivestext. HTML with no text to derive, such as a single image, sends without a text part. - Storing rendered HTML as a message asset follows feat(messaging): protect sensitive data on transactional email templates #120520.
Open
- Idempotency window: whether 24 hours is durable enough (Research whether a send answer means the email is durably queued Silthus/posthog#523).
- Duplicates: the store can queue a second send after a crash between reserving the key and writing the job, or after a failed completion write and a retry past the 60 s pending window. Accepted for now: the docs promise one send per key on retries, not exactly-once.
Language extras, not part of parity
- A Python extra needs a line here first, so the two SDKs don't drift.
Not in this contract
Restricted keys limited to senders, the email lookup by address, React content (render it to html in your code), and more than one to address. Each comes as its own PR after the send.
Changes
- 2026-11-03: A code send without
fromuses the project's default sender. With no default, it uses the only verified sender. With several verified senders and no default, it answers400 sender_requiredand asks forfrom(feat(messaging): send an email with inline html from code #127123). Once the sandbox sender lands, a project with no verified sender sends from it. - 2026-10-29:
capture_engagementis part of the code form only. A template sent bytemplate_idfollows the project's engagement setting, like its other settings, and the server and the SDK refusecapture_engagementwith it. - 2026-10-28: The contract follows the send checks that shipped in feat(messaging): refuse transactional sends the email worker would skip #123019, fix(messaging): refuse a transactional email to a recipient that can't receive email #123878 and fix(messaging): stop suppression refusals dropping transactional email #123492. A send that can't go out answers
422withsending_suspended,sending_paused,recipient_suppressedorrecipient_unreachable, and keepswhyandfix.template_pausedis nowsending_paused. A spam complaint alone doesn't suppress an address for transactional email. ARetry-Afterover 30 s fails at once instead of a retry after 30 s. A template send replays across both URLs. A code send and a template send still never share a key. - 2026-10-26: Status reads have the same rates as sends, but in their own buckets. Polling no longer draws from the send budget.
- 2026-10-25:
capture_engagementdefaults totrueon every form, and the SDK always sends it. A project with engagement capture turned off still captures nothing. - 2026-10-25: A
503no longer promises that nothing was queued. When the email pipeline does not confirm a send, the email may still go out. A retry with the same idempotency key is safe once the send route's idempotency check ships. - 2026-10-22:
cc,bcc,headers,tagsandattachmentson the code form (feat(messaging): send cc, bcc, headers and tags with a code send #121851, feat(messaging): send attachments with a code send #121852). The422code isidempotency_key_reused, as the idempotency store answers. SDK-side errors and local checks have names. The upload also sendsif_not_superseded: true. - 2026-10-22: The send route refuses a field it doesn't take with
400 invalid_requeston that field (feat(messaging): send email rendered by the caller's code by key #121272). A newer SDK against an older server fails instead of losingccorattachmentsbehind a202. - 2026-10-23: A retry replays after its workflow is paused, or after the project's default sender changes when the caller named no sender. A workflow that isn't active answers
400 transactional_email_pausedafter the key lookup. HTML-only content with no text to derive sends without a text part (feat(messaging): send email rendered by the caller's code by key #121272, feat(messaging): send each email once per idempotency key on send/email #121867). - 2026-10-24: An answer without a code takes the
nameand retry of its status, as both SDKs do, instead ofapplication_error. A disabled client fails withclient_disabled. The SDK codeclient_closedcovers a send aftershutdown().
Activity
posthog commentedon Oct 21, 2026
PostHog self-driving picked up this issue and researched it. Somebody may already be working on it, so ask before you start a fix.
Report (team access only): https://us.posthog.com/project/2/inbox/reports/01a15dbf-e9de-7228-9c1c-52eb2489380e?link_source=github_comment
mayteio commentedon Oct 21, 2026
Follow-up notes on the client interface
Agreed
sendtakes plain keyword arguments, like Resend's Python SDK, SendGrid and Postmark.html(),text()andlibrary_template()are dropped.html,text,from,reply_toand the rest) and posthog-node: Michael.Proposed for posthog-python
Keyword arguments typed with a
TypedDictandUnpack, the waycapturealready works. One@overloadper form (template or code content), plus a runtime check that exactly one form is passed. No Pydantic at runtime.Errors raise typed exceptions that carry the same
nameandcodeas the contract. Resend's Python SDK raises too. Node keeps{ data, error }.A successful
sendreturns themessage_idand means the email is queued, not delivered. Docs should say so.v1 takes a single
to:v1 sends to the existing
/messaging_templates/{id}/send/by UUID. It moves to/messaging/send/email/inside the SDK once feat(messaging): upload, send and lock code-managed email templates #118924 lands, with no caller change.AsyncPosthoggetsemailstoo, with an awaitablesend.Changes to the contract
code, not status.quota_limitedmust not be retried. Waiting doesn't fix a monthly quota.max_retries=0) for callers whose job runner already retries. The docs should tell those callers to pass an idempotency key derived from the email's purpose. A generated UUID doesn't survive a job retry.hostthat is a reverse proxy for ingestion is not self-hosted, and it shouldn't receive the secret key. Don't call itapi_host, because posthog-js uses that name for the ingestion host.template_id. Templates created in the UI have no key.keytotemplate_key. Next toidempotency_key, a barekeyis ambiguous.distinct_idin docs and examples. Without it, the send's billed engagement events go to a person keyed by the email address, not the app's user.invalid_recipientin the 400 list, so callers can skip a rejected recipient and still send to the others.posthog-python/to send attribution in feat(messaging): attribute transactional sends to their source #120628.Open
docs(workflows): document both send forms, idempotency and the send c…
fix(node): match the email contract and keep long Retry-After waits
fix: match the email contract's missing_app_host and keep network causes
fix(node): fail email sends from a disabled client with client_disabled
fix: raise client_disabled for email sends from a disabled client
feat: send transactional email from posthog templates (#1093)
feat(node): send transactional email from a template (PostHog#5418)
chore: sync main into v1 (7.75.7–7.81.1) (#1169)
chore: sync main into capture-v1 (posthog-node 5.58.0-5.61.1) (#5508)
Silthus commentedon Nov 3, 2026
Note
🤖 Claude Opus 5.5 writing on behalf of Michael
Contract change approved by Michael on 2026-11-03: a batch section for
emails.batch, and a 128 KiB content cap on every send form. The batch builds on the single send and ships behind the sameworkflows-email-from-codeflag.New section, after Read (later PR)
Email batch
emails.batch(emails)sends up to 100 separate transactional emails in one call. It is not a broadcast: each email is a full single send, in either form, with its ownto.Request.
POST /api/projects/@current/messaging/send/email_batch/with{ "emails": [ … ] }. Each email is the single send's body. Its idempotency key goes in the email asidempotency_key, not in a header. A batch request with anIdempotency-Keyheader answers400 idempotency_key_per_email.Answer. When the checks on the whole call pass, the batch answers
200with{ "results": [ … ] }: one result per email, in request order. A queued email's result is the single send's202body,{ message_id, replayed }. A refused email's result is{ "error": { status, type, code, detail, attr } }, the single send's error body for that email plus its HTTP status. A batch where every email is refused still answers200.Errors for the whole call. These queue nothing:
code400attrsuch asemails__3__toemailsis empty or has more than 100 emails, or an email has a field the single send refuses400content_too_large, withattremails__<i>400duplicate_idempotency_keydetailnames both positions400idempotency_key_per_emailIdempotency-Keyheader401,403send404not_found413batch_too_large429throttled, withRetry-AfterLimits. 100 emails, one
toeach, 128 KiB of content per email, 8 MiB per request, no attachments.Rate. A batch of N emails uses N units of the send rate limits, per key and per project. A batch that doesn't fit answers
429as a whole and uses none. An email refused later, or replayed, still uses its unit, as a single send does.Idempotency. Each email has its own key, with no batch key and no keys from positions. One key dedupes across single sends and batches. The SDK makes a UUID v4 for each email without a key, before the first attempt, and keeps it across retries.
SDK behavior.
errorin Node, and a raisedEmailErrorin Python, mean the batch has no result per email. When PostHog answered the whole call with one of the errors above, nothing was queued. After a network error, a timeout or a503, some emails may have been queued: retry with the same keys. A failed email is a value in its result. Code that checks onlyerrormisses failed emails.batchcall. To retry a failed email or batch in a new call, pass your own stable keys.send's retry rules, with the same keys. It never retries one email's503: retry that email yourself with its key.503 delivery_unavailablemay still go out when itsdetailsays so. Retry it only with the same key.senddoes, and names the email's position in a local error.Fields. A batch email takes the fields the single send takes today, in either form, and refuses any other field with its position in
attr. A field the single send gains later, such asscheduled_at, reaches the batch when this contract says so. A batch refuses attachments.Status. Read each email with
emails.get(message_id).Edits to existing sections
400row: addcontent_too_largeto the codes.400 content_too_large. The size is the email as you send it, JSON-encoded, without attachments: subject,html,text,template_data, and later headers and tags. Gmail clips emails over about 102 KB."413|batch_too_large: an email batch over 8 MiB |validation_error| No.emails.batchsends up to 100 separate emails in one call, with one result per email in a200(see Email batch). Every send form refuses more than 128 KiB of content per email with400 content_too_large, attachments left out."Silthus commentedon Nov 3, 2026
Note
🤖 Claude Opus 5.5 writing on behalf of Michael
Contract change approved by Michael on 2026-11-03: scheduled sends.
sendtakesscheduled_atup to 30 days ahead, andemails.update,emails.cancelandemails.listmanage the waiting emails. It ships behind its own flag, on top of the single send and the batch.New section, after Read (later PR)
Scheduled sends
sendtakesscheduled_atto send the email later, up to 30 days after the call. Both forms take it.Send. A time at or before now sends at once. A later time answers
202withstatus: "scheduled"and the acceptedscheduled_at. A time more than 30 days after the call answers400 invalid_scheduled_at. A time without an offset answers400onscheduled_at; Python refuses a naivedatetimebefore any request.Checks. Every check of a send now runs when you schedule. Suppression, pause, suspension, the recipient and the sender are checked again at the send time. A check that fails then fails the email, with its reason in the status. A paused email is not held until the unpause.
Content and sender. A code send keeps its content, its sender and any
fromaddress or name you gave; a part offromyou left out comes from the sender at the send time. Atemplate_idsend takes its content and sender from the template at the send time.Status.
GET messaging/emails/{id}/showsscheduleduntil the outcome, andcanceledafter a cancel. It has noscheduled_at; the list has it. An email is readable for 60 days after the call.Update.
PATCH /api/projects/@current/messaging/emails/{id}/with{ scheduled_at }moves a waiting email. Only the time changes. The limit stays 30 days after the first call; a time at or before now sends at once.409 already_sendingonce PostHog has started sending it;409 canceledafter a cancel.Cancel.
POST /api/projects/@current/messaging/emails/{id}/cancel/stops a waiting email before PostHog starts sending it:200, or409 already_sending. A repeat cancel answers200while PostHog can still tell, else404. Once an email has gone out, cancel and update answer409for a few seconds, then404. A manual rerun of the workflow's run history can send a canceled email again.List.
GET /api/projects/@current/messaging/emails/?status=scheduledlists waiting emails in send-time order, 100 a page. Needstransactional_email:read. Update and cancel needtransactional_email:write. Ahog_flowkey works for each, as onsend.Idempotency.
scheduled_atis part of the fingerprint: the same key with another time answers422 idempotency_key_reused. A replay returns the first202; read the status for the current state. Update and cancel take no key; the SDK retries them like a send.getandlistnever retry.SDK versions. Use an SDK version that takes
scheduled_at. From the code-form releases on, an SDK refuses a field it doesn't know before any request. Earlier posthog-node releases dropscheduledAtand send at once.Batch. Each email of
emails.batchtakesscheduled_atassenddoes.Edits to existing sections
send(...): addscheduled_at?: datetime | Date | string # at most 30 days ahead, ISO 8601 with an offset.status: addscheduledandcanceled.400row: addinvalid_scheduled_at. The409rows: addalready_sendingandcanceled(cancel and update only),namevalidation_error, not retried.sendtakesscheduled_at, up to 30 days ahead, andemails.update,emails.cancelandemails.listmanage waiting emails (see Scheduled sends). Status reads cover 60 days."