openemail.events
هر متد در این فضای نام: امضا، پارامترها، آنچه برمیگرداند و یک نمونه.
متدها
Things your contacts did, sent by your own code, such as an order placed or a trial started. An event starts the automations whose trigger names it and ends the waits that were holding out for it.
events.send()
Record that something happened to a contact
def send( body: ContactEventSend, *, idempotency_key: str | None = None, api_key: str | None = None, timeout: float | None = None,) -> ContactEventResultResourceRecords an event against one contact, named by email or contactId: an order placed, a trial started, a plan changed. Every live automation whose trigger is this event name, and whose filters match properties, takes the contact in, and any wait step holding out for the name moves on. enrolled and resumed in the answer say what it set off. Events are kept for 90 days.
Every call carries an Idempotency-Key. The SDK generates one per call and reuses it on that call's retries, so a retried network failure returns the stored event instead of recording a second one. Pass idempotency_key= to extend that across processes and restarts. A replay returns the stored event with replayed set to True and starts nothing again. The same key with a different event is a 422 idempotency_key_reuse.
An event sent with a test key is stored with mode test and starts or resumes nothing.
پارامترها
body['name']strالزامیWhat happened, such as
order.placed: 1 to 100 letters, digits, dots, colons, dashes and underscores, starting with a letter or a digit. Names are matched exactly, case included.body['email']strThe contact the event is about, by email address. Send this or
contactId.body['contactId']strThe contact the event is about, by id. Send this or
email.body['properties']dict[str, Any]Anything worth keeping about the event, as a dict of at most 50 keys and 4 KB of JSON. An event trigger can filter on these, and steps can put them in an email or a contact field.
body['occurredAt']datetime | strWhen it happened, as a
datetimeor an ISO 8601 string. Left out, it is now. It cannot be in the future or more than 90 days ago.body['createContact']boolAdd the address to the contacts when nobody has it yet. It needs
email. Left out orFalse, an unknown address is a 404contact_not_found.body['contactName']strThe name to give a contact that
createContactadds, at most 200 characters.idempotency_keystrYour own key, 1 to 255 characters of letters, digits,
_,.,:or-. Anything else is a 400invalid_idempotency_key.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
خروجی
ContactEventResultResource: the event, with id, contactId, email, name, properties, occurredAt, mode and createdAt, plus replayed, enrolled, the ids of the automations it put the contact into, and resumed, how many waits it ended.
نمونه
from openemail import openemail event = openemail.events.send( { 'name': 'order.placed', 'email': '[email protected]', 'properties': {'orderId': 'AC-4192', 'total': 129}, 'createContact': True, }, idempotency_key='order:AC-4192:placed',) print(event['id'], event['enrolled'], event['resumed'], event['replayed'])نکتهها
A name, properties or an
occurredAtthat break a rule, or a body that names no contact, is 422invalid_eventwithparamnaming the field.A key or an app may send 600 events a minute. Past that the call is 429
event_rate_limited.An app a member connected reaches only the contacts that member added, and a contact it creates belongs to that member.
Retried automatically on network failure and retryable statuses, because the idempotency key makes a retry safe.
همچنین در دسترس در
- API
POST /events- TypeScript
events.send()- Ruby
events.send- PHP
events->send- Go
Events.Send- Java
events().send- C#
Events.SendAsync- CLI
openemail events send
events.send_batch()
Record up to 100 contact events in one call
def send_batch( events: Sequence[ContactEventSend], *, idempotency_key: str | None = None, api_key: str | None = None, timeout: float | None = None,) -> ContactEventBatchResourceRecords each event in order, as if events.send had been called for it, and reports per event. It is never all or nothing: accepted holds the events that were stored and failed the ones that were not, each with the index it had in the list, so one unknown address does not stop the rest. The call returns whenever the batch was processed, so check failed instead of waiting for an exception.
The batch shares one Idempotency-Key, generated once per call or supplied as idempotency_key=, and the server remembers each event under the key and its position. Retrying the same list replays the events that were already stored and records only the ones that were not. Reordering the list between attempts makes an event that moved fail with idempotency_key_reuse.
پارامترها
eventsSequence[ContactEventSend]الزامیThe events, 1 to 100 of them, each in the shape
events.sendtakes:name,emailorcontactId, and optionallyproperties,occurredAt,createContactandcontactName.idempotency_keystrYour own key for the whole batch, 1 to 255 characters of letters, digits,
_,.,:or-.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
خروجی
ContactEventBatchResource, a dict with accepted, each a ContactEventResultResource plus its index, and failed, each with index, code and message.
نمونه
from openemail import openemail batch = openemail.events.send_batch( [ {'name': 'trial.started', 'email': '[email protected]'}, { 'name': 'trial.started', 'email': '[email protected]', 'properties': {'plan': 'team'}, }, ], idempotency_key='trials:2026-10-11',) for failure in batch['failed']: print(failure['index'], failure['code'], failure['message']) print(len(batch['accepted']))نکتهها
A body of the wrong shape, an empty list or more than 100 events is refused whole with 422
invalid_parameter, andparamnames the event and the field, such asevents.3.name.The batch counts as that many events toward the 600 a minute a key or an app may send. A batch that would pass it is 429
event_rate_limitedand nothing is stored.A failed event carries the code the single call would answer:
invalid_event,contact_not_foundoridempotency_key_reuse.Retried automatically on network failure and retryable statuses, because the idempotency key makes a retry safe.
همچنین در دسترس در
events.list_names()
List the event names the workspace has seen
def list_names( *, api_key: str | None = None, timeout: float | None = None,) -> builtins.list[ContactEventNameResource]Returns the distinct names of the events the workspace holds, in byte order, at most 100. It is what the app suggests when somebody picks the event that starts an automation. Events are kept for 90 days, so a name nothing has sent in that time is gone. The list is not paginated.
پارامترها
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
خروجی
list[ContactEventNameResource], each with name.
نمونه
from openemail import openemail names = openemail.events.list_names() print([entry['name'] for entry in names])نکتهها
It needs
automations:read, not a contacts scope, because it serves the automation builder.Read only, so the SDK retries it after a network failure like any other read.