client.Webhooks

이 네임스페이스의 모든 메서드: 시그니처, 매개변수, 반환값과 예시.

메서드

Endpoints that receive signed mailbox events: register, change, test and remove them, rotate their secrets, read and replay their delivery log, and follow their audit log and delivery numbers. OpenEmailClient.VerifyWebhookSignature checks each delivery.

`Webhooks.ListAsync`

List the webhook endpoints in the workspace

webhooks:read결과를 페이지 단위로 가져옴

시그니처

Task<Page> ListAsync(    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns one page of the webhook endpoints registered on the key's workspace, newest first. Webhooks.ListAllAsync collects every page and Webhooks.IterateAsync walks them lazily.

Signing secrets are never part of a read. Only Webhooks.CreateAsync and Webhooks.RotateSecretAsync return secret, so a lost secret cannot be recovered from here. An endpoint subscribed to every event, which is what an endpoint created without eventTypes is, reports eventTypes as new[] { "*" } rather than an empty object.

Read enabled, disabledReason and consecutiveFailures as the health summary. An endpoint the server switched off after 100 consecutive failed deliveries shows enabled false with disabledAt and a reason, while one you disabled yourself through Webhooks.UpdateAsync has both of those null.

매개변수

limitint?: Page size, from 1 to 100. The server defaults to 25.
cursorstring?: The nextCursor of the previous page. Leave it out for the first page.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A Page of endpoint objects, with items, hasMore and nextCursor. Each item has id, url, description, eventTypes, enabled, disabledAt, disabledReason, consecutiveFailures, addressAllowlist, domainAllowlist, lastDeliveryAt and createdAt.

예시

var page = await client.Webhooks.ListAsync(); Console.WriteLine(page.Count);

참고

A narrowed key reads every endpoint, and may write one whose own addressAllowlist and domainAllowlist sit inside what the key holds. A write that would take an endpoint wider than the key is 422 capability_unsupported on addressAllowlist.
lastDeliveryAt moves on failed attempts as well as successful ones, so it shows the endpoint is being called, not that it is healthy.
The cursor is opaque and holds where the last row sat in this order, so a row deleted or edited between pages never breaks the walk: the next page starts at the first row that sorts after it. A cursor this list did not hand out is a 400 invalid_cursor.

다른 사용처

API: GET /webhooks
TypeScript: webhooks.list()
Python: webhooks.list()
Ruby: webhooks.list
PHP: webhooks->list
Go: Webhooks.List
Java: webhooks().list
CLI: openemail webhooks list

`Webhooks.ListAllAsync`

Collect every webhook endpoint into one object

webhooks:read결과를 페이지 단위로 가져옴

시그니처

Task<IReadOnlyList<JsonObject>> ListAllAsync(    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Walks every page of Webhooks.ListAsync and returns all webhook endpoints in one object, newest first. One request per page.

매개변수

limitint?: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk after this cursor instead of the first page.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

반환값

A list of endpoint objects holding every webhook endpoint.

예시

var endpoints = await client.Webhooks.ListAllAsync(); Console.WriteLine(endpoints.Count);

참고

If any page fails, the exception is thrown and the webhook endpoints already fetched are discarded.

다른 사용처

API: GET /webhooks
TypeScript: webhooks.listAll()
Python: webhooks.list_all()
Ruby: webhooks.list_all
PHP: webhooks->listAll
Go: Webhooks.ListAll
Java: webhooks().listAll

`Webhooks.IterateAsync`

Stream the webhook endpoints one at a time

webhooks:read결과를 페이지 단위로 가져옴

시그니처

IAsyncEnumerable<JsonObject> IterateAsync(    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns an IAsyncEnumerable<JsonObject> that yields webhook endpoints one at a time, newest first, and requests the next page only once the current one is used up. Nothing is fetched until the loop starts, and breaking out of the await foreach stops the requests.

매개변수

limitint?: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk after this cursor instead of the first page.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

반환값

An IAsyncEnumerable<JsonObject> that yields one endpoint per step.

예시

await foreach (var endpoint in client.Webhooks.IterateAsync()){    if ((bool?)endpoint["enabled"] != true && endpoint["disabledAt"] is not null)    {        Console.WriteLine($"{endpoint["url"]} was switched off: {endpoint["disabledReason"]}");    }}

참고

The generator is lazy, so an abandoned loop costs only the pages you consumed.

다른 사용처

API: GET /webhooks
TypeScript: webhooks.iterate()
Python: webhooks.iterate()
Ruby: webhooks.iterate
PHP: webhooks->iterate
Go: Webhooks.Iterate
Java: webhooks().iterate

`Webhooks.GetAsync`

Read one webhook endpoint by id

webhooks:read

시그니처

Task<JsonObject> GetAsync(    string id,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns a single endpoint with its URL, subscription list, enabled state and delivery health. The signing secret is never part of a read. It appears only in the responses of Webhooks.CreateAsync and Webhooks.RotateSecretAsync, and a lost one is replaced with Webhooks.RotateSecretAsync rather than read back.

An id from another workspace answers exactly like one that never existed, with 404 resource_not_found, so a 404 does not tell you whether the endpoint was deleted or was never yours.

consecutiveFailures resets to 0 on any successful delivery and when Webhooks.UpdateAsync sets enabled to true. When it reaches 100 the server disables the endpoint, fills in disabledAt and disabledReason, and emails the workspace owner and every member whose role can read webhooks.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A JsonObject with id, url, description, eventTypes, enabled, disabledAt, disabledReason, consecutiveFailures, addressAllowlist, domainAllowlist, lastDeliveryAt and createdAt. No secret.

예시

var endpoint = await client.Webhooks.GetAsync("whe_3f9c2a7b1e4d8f60a5c7b92d"); Console.WriteLine($"{endpoint["url"]}{((bool?)endpoint["enabled"] == true ? " is on" : " is off")}, last called {endpoint["lastDeliveryAt"]?.ToString() ?? "never"}");

참고

eventTypes of new[] { "*" } means the endpoint named none, so it receives the default email.* set. email.replied, domain.*, suppression.*, file.* and form.* sit outside that set and have to be named explicitly.
A GET is retried automatically on network failure and on 408, 429, 500, 502, 503 and 504 responses, up to the client's MaxRetries.

다른 사용처

API: GET /webhooks/{id}
TypeScript: webhooks.get()
Python: webhooks.get()
Ruby: webhooks.get
PHP: webhooks->get
Go: Webhooks.Get
Java: webhooks().get
CLI: openemail webhooks get

`Webhooks.CreateAsync`

webhooks:write

시그니처

Task<JsonObject> CreateAsync(    IReadOnlyDictionary<string, object?> body,    string? apiKey = null,    CancellationToken cancellationToken = default)

Registers a receiver URL and subscribes it to events on the key's workspace. The endpoint starts enabled, so the next matching event is delivered to it straight away. Leave eventTypes out, or pass an empty object, and the endpoint receives the default set, which is the email.* events other than email.replied. Every family outside it has to be named: email.replied, domain.*, suppression.*, file.* and form.*. Reads report an unnamed subscription as new[] { "*" }.

By default an endpoint hears about every address the workspace owns. addressAllowlist and domainAllowlist narrow it, exactly as the same two lists narrow an API key: name whole domains, single addresses, or both. An event reaches the endpoint when the address or domain it concerns is covered. Events that name no address at all, such as suppression.removed, reach every endpoint whatever its lists say. form.* is the exception: a sign-up belongs to the whole workspace, so an endpoint limited to some addresses or domains never receives form.submitted or form.confirmed.

This response is the only place the full secret ever appears. Every later read omits it, so store it before doing anything else, and if it is lost call Webhooks.RotateSecretAsync. The secret is whsec_ followed by 43 base64url characters, and the HMAC key is the whole string including the prefix, so pass it to OpenEmailClient.VerifyWebhookSignature exactly as returned.

url must be https. localhost, hosts ending .localhost, .internal or .local, and IP literals in loopback, private, link local, carrier grade NAT, multicast or unique local ranges are refused with 422 invalid_webhook_url. The host is resolved again on every delivery, and an attempt to a name that resolves into one of those ranges is recorded as failed without being sent. Deliveries never follow redirects, so register the final address.

매개변수

urlstring필수: The https receiver URL. Another scheme or a blocked host is 422 invalid_webhook_url. Stored in normalised form, so the url read back can differ cosmetically.
eventTypeslist: Events to subscribe to, also in OpenEmail.Constants.WebhookEvents. Omit it, or send [], for the default email.* set: email.received, email.sent, email.failed, email.cancelled, email.scheduled, email.queued, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.suppressed, email.opened, email.clicked and email.downloaded. email.replied, domain.verified, domain.sending_changed, domain.deleted, suppression.added, suppression.removed, file.uploaded, file.deleted, form.submitted and form.confirmed are outside that set and have to be named.
descriptionstring: Free text note, at most 200 characters.
addressAllowlistIEnumerable<string>: Single addresses this endpoint hears about. An event is delivered when the address it concerns is on this list, or when its domain is in domainAllowlist. Leave both empty and the endpoint hears about every address the workspace owns. At most 50, and an address this workspace does not own is 422 invalid_parameter.
domainAllowlistIEnumerable<string>: Whole domains this endpoint hears about, including addresses added to them later. A domain also carries its own domain.* events. At most 25. An address whose domain is already listed here is dropped from addressAllowlist when the endpoint is saved, so the two lists never overlap.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A JsonObject for the endpoint plus the plaintext secret: id, url, description, eventTypes, enabled, disabledAt, disabledReason, consecutiveFailures, addressAllowlist, domainAllowlist, lastDeliveryAt, createdAt and secret.

예시

using OpenEmail.Constants; var endpoint = await client.Webhooks.CreateAsync(new Body{    ["url"] = "https://hooks.acme.com/openemail",    ["eventTypes"] = new[]    {        WebhookEvents.EmailBounced,        WebhookEvents.EmailComplained,        WebhookEvents.EmailReplied,    },    ["description"] = "Bounces, complaints and replies",    ["domainAllowlist"] = new[] { "acme.com" },}); await File.WriteAllTextAsync(".webhook-secret", (string?)endpoint["secret"]); Console.WriteLine($"Created {endpoint["id"]} for {string.Join(", ", endpoint["eventTypes"]?.AsArray() ?? [])}");

참고

Verify each delivery with OpenEmailClient.VerifyWebhookSignature(payload, signature, secret), passing the raw request body and the value of the X-OpenEmail-Signature header, or the request headers themselves. It checks the X-OpenEmail-Signature HMAC-SHA256 over the timestamp, a dot and the raw body in constant time, rejects a timestamp more than 300 seconds off, throws an OpenEmailWebhookException on failure and returns the event as a JsonObject with id, type, createdAt and data.
Each attempt is one POST with a 5 second timeout. A failure worth repeating (no answer, 408, 425, 429 or a 5xx) is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours, up to 8 attempts over about 27 and a half hours, each wait varied by up to 10% and stretched when your server's Retry-After asks for longer, up to 6 hours. A 410 Gone switches the endpoint off. Webhooks.ListDeliveriesAsync shows every attempt with its number, and Webhooks.ReplayDeliveryAsync sends one of them again, one event at a time, once your receiver is fixed.
A workspace holds 10 endpoints by default, and support can raise that for a workspace that needs more. The next one past the limit is 422 workspace_limit_reached. A narrowed key may create an endpoint, but only one whose own lists sit inside what the key holds. Anything wider is 422 capability_unsupported on addressAllowlist.
Not retried automatically, so a network failure can leave an endpoint created with a secret you never saw. Check Webhooks.ListAsync before creating it again.

다른 사용처

API: POST /webhooks
TypeScript: webhooks.create()
Python: webhooks.create()
Ruby: webhooks.create
PHP: webhooks->create
Go: Webhooks.Create
Java: webhooks().create
CLI: openemail webhooks create

`Webhooks.UpdateAsync`

Change an endpoint URL, events or enabled state

webhooks:write

시그니처

Task<JsonObject> UpdateAsync(    string id,    IReadOnlyDictionary<string, object?> patch,    string? apiKey = null,    CancellationToken cancellationToken = default)

Patches the URL, subscription list, description or enabled flag of one endpoint. Every field is optional, and an empty patch is accepted and changes nothing you can read back. A new url goes through the same https and host checks as Webhooks.CreateAsync, and ["description"] = null clears the note.

eventTypes replaces the subscription set wholesale, so send the complete list you want rather than a delta. An empty object does not unsubscribe: it puts the endpoint back on the default email.* set. To stop deliveries, set enabled to false instead.

addressAllowlist and domainAllowlist replace the endpoint's scope the same way, wholesale rather than as a delta. Send both empty to widen it back to every address the workspace owns. Each list is checked against the domains and addresses this workspace actually owns, and an unknown one is 422 invalid_parameter.

Writing enabled clears disabledAt and disabledReason either way, so an endpoint you switch off yourself reports both as null. Setting it back to true also resets consecutiveFailures to 0, which is how an endpoint the server disabled after 100 failures is brought back. Events that fire while an endpoint is disabled are never delivered to it later, but a delivery that failed before it was switched off can be sent again with Webhooks.ReplayDeliveryAsync once it is back on, one event at a time.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
urlstring: Replacement https URL, checked against the same host rules as Webhooks.CreateAsync.
eventTypeslist: Complete replacement subscription set. [] means the default email.* set.
addressAllowlistIEnumerable<string>: Complete replacement list of single addresses this endpoint hears about. At most 50. Send [] on both lists to hear about every address again.
domainAllowlistIEnumerable<string>: Complete replacement list of whole domains this endpoint hears about, including addresses added to them later. At most 25.
descriptionstring: Replacement note of at most 200 characters, or null to clear it.
enabledbool: False stops deliveries. True resumes them and resets consecutiveFailures.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A JsonObject for the endpoint as saved. The signing secret is untouched and not included.

예시

using OpenEmail.Constants; var endpoint = await client.Webhooks.UpdateAsync("whe_3f9c2a7b1e4d8f60a5c7b92d", new Body{    ["url"] = "https://hooks.acme.com/openemail/v2",    ["eventTypes"] = new[] { WebhookEvents.EmailBounced, WebhookEvents.EmailComplained },    ["enabled"] = true,}); Console.WriteLine($"{endpoint["url"]} now hears {string.Join(", ", endpoint["eventTypes"]?.AsArray() ?? [])}");

참고

Read the current eventTypes first if you mean to add one, since a partial list silently unsubscribes the rest. The same applies to the two allowlists. Do not send back new[] { "*" } as read: it is a 422 invalid_parameter, and [] is how to ask for the default set.
This route never touches the signing secret. Use Webhooks.RotateSecretAsync for that.
Retried automatically on network failure and retryable statuses, since the same patch applied twice lands on the same row.

다른 사용처

API: PATCH /webhooks/{id}
TypeScript: webhooks.update()
Python: webhooks.update()
Ruby: webhooks.update
PHP: webhooks->update
Go: Webhooks.Update
Java: webhooks().update
CLI: openemail webhooks update

`Webhooks.DeleteAsync`

Delete an endpoint and its delivery log

webhooks:write

시그니처

Task<JsonObject> DeleteAsync(    string id,    string? apiKey = null,    CancellationToken cancellationToken = default)

Removes the endpoint for good. Deliveries stop immediately, the signing secret is gone, and the delivery log for the endpoint is deleted with it, so read it with Webhooks.ListAllDeliveriesAsync first if you need it for an audit trail.

There is no undo and no soft delete. If the aim is only to pause deliveries, call Webhooks.UpdateAsync with new Body { ["enabled"] = false } and keep the endpoint, its secret and its log.

The response is a tombstone rather than an empty body, so a log line can name what went. Deleting frees a slot against the workspace's endpoint limit straight away.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A JsonObject with object set to webhook, the id and deleted set to true.

예시

var log = await client.Webhooks.ListAllDeliveriesAsync("whe_3f9c2a7b1e4d8f60a5c7b92d", limit: 100); var deleted = await client.Webhooks.DeleteAsync("whe_3f9c2a7b1e4d8f60a5c7b92d"); Console.WriteLine($"Deleted {deleted["id"]} after saving {log.Count} deliveries");

참고

Not idempotent: a second call on the same id is 404 resource_not_found, and the SDK does not retry it after a network failure.
A narrowed key may delete only an endpoint whose own allowlists sit inside what the key holds. Any other is 422 capability_unsupported on addressAllowlist.

다른 사용처

API: DELETE /webhooks/{id}
TypeScript: webhooks.delete()
Python: webhooks.delete()
Ruby: webhooks.delete
PHP: webhooks->delete
Go: Webhooks.Delete
Java: webhooks().delete
CLI: openemail webhooks delete

`Webhooks.RotateSecretAsync`

Issue a new signing secret for an endpoint

webhooks:write

시그니처

Task<JsonObject> RotateSecretAsync(    string id,    string? apiKey = null,    CancellationToken cancellationToken = default)

Generates a new signing secret and returns the endpoint plus the new plaintext secret. As with Webhooks.CreateAsync, this response is the only place that secret appears, so store it before anything else.

There is no overlap window. Every delivery is signed at send time with the current secret, so the old one stops verifying the moment this call commits, and any event that fires before your receiver has the new secret fails verification on your side.

The safe order is to deploy a receiver that tries both the old secret and a new one read from config, call this, write the returned secret to config, then drop the old one. Webhooks.TestAsync confirms the new secret verifies before you remove the fallback.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A JsonObject for the full endpoint plus the new secret, formatted whsec_ followed by 43 base64url characters.

예시

var rotated = await client.Webhooks.RotateSecretAsync("whe_3f9c2a7b1e4d8f60a5c7b92d"); await File.WriteAllTextAsync(".webhook-secret", (string?)rotated["secret"]); var check = await client.Webhooks.TestAsync(rotated["id"]!.GetValue<string>()); Console.WriteLine($"A test signed with the new secret: {check["delivery"]?["status"]?.ToString() ?? "not recorded"}");

참고

There is no request body and the success status is 200, not 201.
Not retried automatically. A lost response means a secret you never saw is already live, so rotate again rather than waiting.
Subscriptions, enabled state and consecutiveFailures are left as they were.

다른 사용처

API: POST /webhooks/{id}/rotate-secret
TypeScript: webhooks.rotateSecret()
Python: webhooks.rotate_secret()
Ruby: webhooks.rotate_secret
PHP: webhooks->rotateSecret
Go: Webhooks.RotateSecret
Java: webhooks().rotateSecret
CLI: openemail webhooks rotate-secret

`Webhooks.TestAsync`

Send a synthetic event and report how delivery went

webhooks:write

시그니처

Task<JsonObject> TestAsync(    string id,    string? apiKey = null,    CancellationToken cancellationToken = default)

Posts a signed synthetic email.sent event to the endpoint and waits for the attempt to finish before returning. The payload data holds test set to true and a note, and no mail is sent, so it is safe against a production receiver. It proves the URL is reachable and that your signature check accepts the current secret before real mail depends on it.

The outcome comes back as delivery, read from the newest row of the delivery log. status is delivered for any 2xx answer and failed otherwise, responseCode is the HTTP status or null when no response arrived, such as a DNS failure or the 5 second timeout, and error explains a failure. A 3xx counts as failed because redirects are never followed.

The event goes out whatever the endpoint subscribes to, and even when it is disabled. It is recorded like any delivery, so it appears in Webhooks.ListDeliveriesAsync and can be sent again with Webhooks.ReplayDeliveryAsync, but it is tried once and leaves consecutiveFailures and lastDeliveryAt alone, so a failing test never counts toward the 100 that disable an endpoint. A 410 Gone answer does switch the endpoint off, as it would for a real event.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A JsonObject with object set to webhook_test, the endpoint id, and delivery holding status, responseCode, durationMs and error, or null when no delivery row could be read back.

예시

var result = await client.Webhooks.TestAsync("whe_3f9c2a7b1e4d8f60a5c7b92d"); var delivery = result["delivery"]; if (delivery is null){    Console.WriteLine("No delivery row was recorded");}else if ((string?)delivery["status"] == "delivered"){    Console.WriteLine($"Delivered in {delivery["durationMs"]} ms");}else{    Console.WriteLine($"Failed with {delivery["responseCode"]?.ToString() ?? "no response"}: {delivery["error"]}");}

참고

The call returns 200 when your receiver fails. Branch on result["delivery"]["status"], not on whether the call threw.
A 4xx from your receiver is a useful answer: the URL is reachable and the rejection came from your own handler, often its signature check.
Not retried automatically, since every call sends another request to your receiver.
If a real event reaches the same endpoint at the same moment, delivery can describe that attempt instead, because it reads the newest log row.

다른 사용처

API: POST /webhooks/{id}/test
TypeScript: webhooks.test()
Python: webhooks.test()
Ruby: webhooks.test
PHP: webhooks->test
Go: Webhooks.Test
Java: webhooks().test
CLI: openemail webhooks test

`Webhooks.ListDeliveriesAsync`

List one page of delivery attempts for one endpoint

webhooks:read결과를 페이지 단위로 가져옴

시그니처

Task<Page> ListDeliveriesAsync(    string id,    string? status = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns one page of an endpoint's delivery log, newest first. Nothing is dropped from the log, so following nextCursor while hasMore is true reaches the endpoint's very first delivery, and Webhooks.ListAllDeliveriesAsync and Webhooks.IterateDeliveriesAsync do that walk for you. status:, since: and until: narrow it the way the Deliveries tab of the app does: status: 'failed' is its "only failed" switch.

Each attempt is one POST with a 5 second timeout, and one event can appear several times: when the failure is worth repeating, a delivery is tried up to 8 times, as it happens and then after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours, about 27 and a half hours in all, and each Webhooks.ReplayDeliveryAsync adds a row of its own. attempt and maxAttempts say which try a row is, and eventId is the same across all of them, so this log distinguishes a retry from a new event. nextAttemptAt is when the automatic retry that follows a row is due, and null when none is waiting, so a failed row with a time in it is not the final word. status is delivered for a 2xx answer and failed for anything else, including a 3xx, since redirects are not followed.

responseCode null means no response arrived, such as a DNS or TLS failure or the timeout, which is a different fact from a receiver that answered. durationMs is null only when the attempt was never made because the server could not read the signing secret, and error then says so. The body that was sent and your server's answer are not part of this response, and Webhooks.GetDeliveryAsync returns both. Webhooks.ListWorkspaceDeliveriesAsync reads every endpoint at once.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
statusstring?: failed keeps only the attempts that did not get a 2xx, the "only failed" view of the app, and delivered keeps the rest.
sinceDateTimeOffset?: Only rows at or after this instant. A DateTimeOffset, sent as ISO 8601 in UTC.
untilDateTimeOffset?: Only rows before this instant. It has to be later than since:, or the server answers 400 invalid_parameter.
limitint?: Rows per page, a whole number from 1 to 100. The server defaults to 25.
cursorstring?: The nextCursor from the previous page, passed back unchanged. Never build one yourself.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A Page of delivery objects, with items, hasMore and nextCursor. Each item has id, endpointId, eventType, eventId, status, responseCode, durationMs, attempt, maxAttempts, error, createdAt and nextAttemptAt.

예시

var failed = await client.Webhooks.ListDeliveriesAsync("whe_3f9c2a7b1e4d8f60a5c7b92d", status: "failed", since: DateTimeOffset.UtcNow.AddDays(-1)); Console.WriteLine(failed.Count);

참고

Synthetic events from Webhooks.TestAsync appear here too, recorded as email.sent.
Each endpoint's copy of an event gets its own evt_ id, sent in the X-OpenEmail-Delivery header and as the payload id, and every retry and replay of that copy keeps it. One event fanned out to two endpoints arrives with two different ids, and a repeat to one endpoint arrives with the same one.
The cursor stays valid under every filter as long as each page sends the same status:, since: and until:, which Webhooks.ListAllDeliveriesAsync and Webhooks.IterateDeliveriesAsync do for you.
A 404 resource_not_found means the endpoint id is wrong or belongs to another workspace, not that the log is empty. A cursor that names no delivery of this endpoint is a 400 invalid_cursor, and a since: or until: that does not parse is a 400 invalid_parameter.

다른 사용처

API: GET /webhooks/{id}/deliveries
TypeScript: webhooks.listDeliveries()
Python: webhooks.list_deliveries()
Ruby: webhooks.list_deliveries
PHP: webhooks->listDeliveries
Go: Webhooks.ListDeliveries
Java: webhooks().listDeliveries
CLI: openemail webhooks list-deliveries

`Webhooks.ListAllDeliveriesAsync`

Collect an endpoint's whole delivery log into one object

webhooks:read결과를 페이지 단위로 가져옴

시그니처

Task<IReadOnlyList<JsonObject>> ListAllDeliveriesAsync(    string id,    string? status = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Walks every page of an endpoint's delivery log and returns all of its attempts, newest first, under the same status:, since: and until: filters as Webhooks.ListDeliveriesAsync. The log is never pruned, so an endpoint that has been busy for a long time can hold a great many rows. Narrow it with a window, or prefer Webhooks.IterateDeliveriesAsync when you can stop early.

Pages are keyset on createdAt and id, walking backwards in time. Attempts recorded after the walk starts are newer than its first page and are not included.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
statusstring?: failed keeps only the attempts that did not get a 2xx, the "only failed" view of the app, and delivered keeps the rest.
sinceDateTimeOffset?: Only rows at or after this instant. A DateTimeOffset, sent as ISO 8601 in UTC.
untilDateTimeOffset?: Only rows before this instant. It has to be later than since:, or the server answers 400 invalid_parameter.
limitint?: Page size for each request, 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk from this cursor instead of the newest row.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

반환값

A list of delivery objects holding every matching attempt on the endpoint, newest first.

예시

var deliveries = await client.Webhooks.ListAllDeliveriesAsync("whe_3f9c2a7b1e4d8f60a5c7b92d", since: DateTimeOffset.UtcNow.AddDays(-7), limit: 100); Console.WriteLine(deliveries.Count);

참고

If any page fails, the exception is thrown and the attempts already fetched are discarded.
One request per page, so a large log takes many requests. Read it with Webhooks.IterateDeliveriesAsync to stop as soon as you have what you need.

다른 사용처

API: GET /webhooks/{id}/deliveries
TypeScript: webhooks.listAllDeliveries()
Python: webhooks.list_all_deliveries()
Ruby: webhooks.list_all_deliveries
PHP: webhooks->listAllDeliveries
Go: Webhooks.ListAllDeliveries
Java: webhooks().listAllDeliveries

`Webhooks.IterateDeliveriesAsync`

Stream an endpoint's delivery attempts one at a time, newest first

webhooks:read결과를 페이지 단위로 가져옴

시그니처

IAsyncEnumerable<JsonObject> IterateDeliveriesAsync(    string id,    string? status = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns an IAsyncEnumerable<JsonObject> over an endpoint's delivery log that yields attempts one at a time and fetches the next page only when the current one is used up, under the same status:, since: and until: filters as Webhooks.ListDeliveriesAsync. Nothing is requested until the loop starts, and breaking out of the await foreach stops further requests, which makes it the right way to find the latest attempt of some kind without reading the whole history.

The walk ends when hasMore is false, when the server stops offering a cursor, or when it repeats one. Attempts recorded after the walk starts are newer than its cursor and are not yielded.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
statusstring?: failed keeps only the attempts that did not get a 2xx, the "only failed" view of the app, and delivered keeps the rest.
sinceDateTimeOffset?: Only rows at or after this instant. A DateTimeOffset, sent as ISO 8601 in UTC.
untilDateTimeOffset?: Only rows before this instant. It has to be later than since:, or the server answers 400 invalid_parameter.
limitint?: Page size per request, 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk from this cursor instead of the newest row.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

반환값

An IAsyncEnumerable<JsonObject> that yields one delivery per step.

예시

await foreach (var delivery in client.Webhooks.IterateDeliveriesAsync("whe_3f9c2a7b1e4d8f60a5c7b92d", status: "failed")){    if (delivery["nextAttemptAt"] is null)    {        Console.WriteLine($"Latest final failure: {delivery["id"]} {delivery["error"]}");         break;    }}

참고

The generator is lazy, so an abandoned loop costs only the pages you consumed.

다른 사용처

API: GET /webhooks/{id}/deliveries
TypeScript: webhooks.iterateDeliveries()
Python: webhooks.iterate_deliveries()
Ruby: webhooks.iterate_deliveries
PHP: webhooks->iterateDeliveries
Go: Webhooks.IterateDeliveries
Java: webhooks().iterateDeliveries

`Webhooks.GetDeliveryAsync`

Read one delivery attempt in full, with the body that was sent

webhooks:read

시그니처

Task<JsonObject> GetDeliveryAsync(    string id,    string deliveryId,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns one attempt from an endpoint's delivery log with what Webhooks.ListDeliveriesAsync leaves out. payload is the exact JSON body that was POSTed, an object with id, type, createdAt and data, and responseBody is the first 2,000 characters your server answered, or null when nothing came back or the answer was a redirect.

attempts lists every try of the same event on this endpoint, oldest first: the first attempt, the automatic retries and any replays, each with its own id, attempt, status, responseCode, error and createdAt. They share eventId, which is the payload id your receiver saw. nextAttemptAt is when the next automatic retry of the event is due, whichever attempt it follows, and null when none is waiting.

replayRefusal says whether Webhooks.ReplayDeliveryAsync would accept this attempt before you call it: null when it would, and otherwise the code and message the replay would be refused with, such as webhook_disabled while the endpoint is switched off, or retry_in_progress while an automatic retry of the same event is being sent.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
deliveryIdstring필수: Delivery id, whd_ followed by 24 hex characters, as Webhooks.ListDeliveriesAsync returns it.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A JsonObject with the delivery fields (id, eventType, eventId, status, responseCode, durationMs, attempt, maxAttempts, error, createdAt, nextAttemptAt) plus endpointId, payload, responseBody, attempts and replayRefusal.

예시

var delivery = await client.Webhooks.GetDeliveryAsync("whe_3f9c2a7b1e4d8f60a5c7b92d", "whd_8c1e4a7f2b9d3e6a0c5f1b28"); Console.WriteLine($"Event {delivery["payload"]?["id"]} was tried {delivery["attempts"]?.AsArray().Count} times");Console.WriteLine($"Your server answered: {delivery["responseBody"]?.ToString() ?? "nothing"}"); if (delivery["replayRefusal"] is not null){    Console.WriteLine($"A replay would be refused: {delivery["replayRefusal"]?["message"]}");}

참고

A delivery id that belongs to another endpoint, even one in the same workspace, is 404 resource_not_found, exactly like one that never existed.
Your server's answer is cut at 2,000 characters when it is recorded, so a longer one reads back truncated.
A GET is retried automatically on network failure and on 408, 429, 500, 502, 503 and 504 responses, up to the client's MaxRetries.
A narrowed key may read a delivery only on an endpoint whose own allowlists sit inside what the key holds, where holding one address never covers its whole domain, because the body names the addresses the event is about. Any other is 422 capability_unsupported on addressAllowlist. Over OAuth only the workspace owner, or a member whose role holds addresses:all, may read one, and any other member's token is 403 owner_only. That member's token is held to the domains the workspace has now, so it reads only a delivery of an endpoint with allowlists, and one with none is 422 capability_unsupported for it too.

다른 사용처

API: GET /webhooks/{id}/deliveries/{deliveryId}
TypeScript: webhooks.getDelivery()
Python: webhooks.get_delivery()
Ruby: webhooks.get_delivery
PHP: webhooks->getDelivery
Go: Webhooks.GetDelivery
Java: webhooks().getDelivery
CLI: openemail webhooks get-delivery

`Webhooks.ReplayDeliveryAsync`

Send one stored event to the endpoint again, now

webhooks:write

시그니처

Task<JsonObject> ReplayDeliveryAsync(    string id,    string deliveryId,    string? apiKey = null,    CancellationToken cancellationToken = default)

Posts the event behind a recorded attempt to the endpoint once more, straight away, and returns when that attempt has finished. The body is the one stored with the original, with the same id, type, createdAt and data, so a receiver that drops ids it has already handled treats the replay as the event it already knows. Only X-OpenEmail-Signature is new, because every POST is signed with the current secret at the moment it goes out, so a replay verifies after a Webhooks.RotateSecretAsync too.

It accepts a delivered attempt as well as a failed one. Replaying a success is how a receiver that lost its copy, or handled it wrongly, is brought back in step. Any attempt of the event will do, since they all carry the same event.

The replay is recorded in the log as a new delivery, attempt 1 of 1, and is never retried automatically. Before it goes out, the automatic retries of the same event that have not started are paused, so the receiver never gets two copies at once. When the replay is delivered they stay cancelled. When it fails they resume on their schedule. If an automatic retry of the event is being sent at that very moment, the replay sends nothing and is refused with 409 retry_in_progress, and if another replay of the same event is still being sent, it is refused with 409 replay_in_progress, so two copies never go out at once. The call returns 200 whatever your server answered, so branch on replay["delivery"]["status"] rather than on whether the call threw.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
deliveryIdstring필수: Any attempt of the event to send again, whd_ followed by 24 hex characters.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A JsonObject with object set to webhook_replay, id (the new delivery), endpointId, replayOf (the attempt you named), eventId, eventType, and delivery holding status, responseCode, durationMs and error.

예시

using OpenEmail.Constants; try{    var replay = await client.Webhooks.ReplayDeliveryAsync("whe_3f9c2a7b1e4d8f60a5c7b92d", "whd_8c1e4a7f2b9d3e6a0c5f1b28");}catch (OpenEmailApiException error) when (error.IsConflict){    if (error.Code == WebhookReplayErrorCodes.RetryInProgress)    {        Console.WriteLine("A retry of this event is being sent right now");    }    else    {        Console.WriteLine($"Refused: {error.Code}");    }}

참고

Refused with 409 when nobody who wants the event would receive it: webhook_disabled while the endpoint is switched off, event_not_subscribed when it no longer listens for the event type, event_out_of_scope when its allowlists no longer cover the address the event is about, delivery_not_replayable when the attempt has no stored event, retry_in_progress while an automatic retry of the same event is being sent, and replay_in_progress while another replay of it is. The codes are in OpenEmail\Constants\WebhookReplayErrorCodes. Wait a few seconds and check Webhooks.GetDeliveryAsync before replaying again, since that retry or replay may deliver it. Webhooks.GetDeliveryAsync reports the same answer in advance as replayRefusal. A synthetic event from Webhooks.TestAsync replays whatever the endpoint subscribes to.
Not retried automatically, because a retry after a lost response would send the event again. A receiver that drops repeated ids handles that safely, but the SDK does not assume yours does.
A delivered replay resets consecutiveFailures, and a failed one does not add to it. A 410 Gone switches the endpoint off, as it does for an automatic delivery.
A narrowed key may replay only on an endpoint whose own allowlists sit inside what the key holds. Any other is 422 capability_unsupported on addressAllowlist.

다른 사용처

API: POST /webhooks/{id}/deliveries/{deliveryId}/replay
TypeScript: webhooks.replayDelivery()
Python: webhooks.replay_delivery()
Ruby: webhooks.replay_delivery
PHP: webhooks->replayDelivery
Go: Webhooks.ReplayDelivery
Java: webhooks().replayDelivery
CLI: openemail webhooks replay-delivery

`Webhooks.ListWorkspaceDeliveriesAsync`

List one page of delivery attempts across every endpoint

webhooks:read결과를 페이지 단위로 가져옴

시그니처

Task<Page> ListWorkspaceDeliveriesAsync(    IEnumerable<string>? endpointIds = null,    string? status = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns one page of the whole workspace's delivery log, newest first: the all-endpoints Deliveries tab of the app. Each row carries endpointId, so the endpoint an attempt went to is never lost. endpointIds: narrows it to some endpoints, and status:, since: and until: work exactly as they do on Webhooks.ListDeliveriesAsync.

Nothing is pruned, so following nextCursor while hasMore is true reaches the workspace's first delivery. Webhooks.ListAllWorkspaceDeliveriesAsync and Webhooks.IterateWorkspaceDeliveriesAsync do that walk. The body that was sent is not here: read it with Webhooks.GetDeliveryAsync, passing the row's endpointId and id.

매개변수

endpointIdsIEnumerable<string>?: Endpoint ids to read, at most 50, as a list or one comma-separated string. Left out, every endpoint in the workspace.
statusstring?: failed keeps only the attempts that did not get a 2xx, the "only failed" view of the app, and delivered keeps the rest.
sinceDateTimeOffset?: Only rows at or after this instant. A DateTimeOffset, sent as ISO 8601 in UTC.
untilDateTimeOffset?: Only rows before this instant. It has to be later than since:, or the server answers 400 invalid_parameter.
limitint?: Rows per page, a whole number from 1 to 100. The server defaults to 25.
cursorstring?: The nextCursor from the previous page, passed back unchanged. Never build one yourself.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

예시

var page = await client.Webhooks.ListWorkspaceDeliveriesAsync(status: "failed", since: DateTimeOffset.UtcNow.AddHours(-1)); foreach (var delivery in page){    Console.WriteLine($"{delivery["endpointId"]} {delivery["eventType"]} {delivery["error"]}");}

참고

An endpoint id in endpointIds: that belongs to no endpoint here simply matches nothing. A removed endpoint takes its deliveries with it.
The cursor stays valid under every filter as long as each page sends the same endpointIds:, status:, since: and until:, which Webhooks.ListAllWorkspaceDeliveriesAsync and Webhooks.IterateWorkspaceDeliveriesAsync do for you.
The list carries no payloads, so a key narrowed to some addresses may read it. Opening a delivery with Webhooks.GetDeliveryAsync is where the narrowing applies.

다른 사용처

API: GET /webhooks/deliveries
TypeScript: webhooks.listWorkspaceDeliveries()
Python: webhooks.list_workspace_deliveries()
Ruby: webhooks.list_workspace_deliveries
PHP: webhooks->listWorkspaceDeliveries
Go: Webhooks.ListWorkspaceDeliveries
Java: webhooks().listWorkspaceDeliveries
CLI: openemail webhooks list-workspace-deliveries

`Webhooks.ListAllWorkspaceDeliveriesAsync`

Collect the workspace's whole delivery log into one object

webhooks:read결과를 페이지 단위로 가져옴

시그니처

Task<IReadOnlyList<JsonObject>> ListAllWorkspaceDeliveriesAsync(    IEnumerable<string>? endpointIds = null,    string? status = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Walks every page of Webhooks.ListWorkspaceDeliveriesAsync under the same filters and returns every matching attempt, newest first. The log is never pruned, so give it a since: or endpointIds: unless you mean to read all of it, or use Webhooks.IterateWorkspaceDeliveriesAsync to stop early.

매개변수

endpointIdsIEnumerable<string>?: Endpoint ids to read, at most 50, as a list or one comma-separated string. Left out, every endpoint in the workspace.
statusstring?: failed keeps only the attempts that did not get a 2xx, the "only failed" view of the app, and delivered keeps the rest.
sinceDateTimeOffset?: Only rows at or after this instant. A DateTimeOffset, sent as ISO 8601 in UTC.
untilDateTimeOffset?: Only rows before this instant. It has to be later than since:, or the server answers 400 invalid_parameter.
limitint?: Page size for each request, 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk from this cursor instead of the newest row.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

반환값

A list of delivery objects holding every matching attempt, newest first.

예시

var deliveries = await client.Webhooks.ListAllWorkspaceDeliveriesAsync(endpointIds: new[] { "whe_3f9c2a7b1e4d8f60a5c7b92d", "whe_8a1c4e7b2d9f3a60c5e1b7d4" }, since: DateTimeOffset.UtcNow.AddDays(-1), limit: 100); Console.WriteLine(deliveries.Count);

참고

If any page fails, the exception is thrown and the attempts already fetched are discarded.

다른 사용처

API: GET /webhooks/deliveries
TypeScript: webhooks.listAllWorkspaceDeliveries()
Python: webhooks.list_all_workspace_deliveries()
Ruby: webhooks.list_all_workspace_deliveries
PHP: webhooks->listAllWorkspaceDeliveries
Go: Webhooks.ListAllWorkspaceDeliveries
Java: webhooks().listAllWorkspaceDeliveries

`Webhooks.IterateWorkspaceDeliveriesAsync`

Stream the workspace's delivery attempts one at a time, newest first

webhooks:read결과를 페이지 단위로 가져옴

시그니처

IAsyncEnumerable<JsonObject> IterateWorkspaceDeliveriesAsync(    IEnumerable<string>? endpointIds = null,    string? status = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns an IAsyncEnumerable<JsonObject> over Webhooks.ListWorkspaceDeliveriesAsync under the same filters. It fetches a page only when the one before is used up and stops requesting when you break out of the foreach.

매개변수

endpointIdsIEnumerable<string>?: Endpoint ids to read, at most 50, as a list or one comma-separated string. Left out, every endpoint in the workspace.
statusstring?: failed keeps only the attempts that did not get a 2xx, the "only failed" view of the app, and delivered keeps the rest.
sinceDateTimeOffset?: Only rows at or after this instant. A DateTimeOffset, sent as ISO 8601 in UTC.
untilDateTimeOffset?: Only rows before this instant. It has to be later than since:, or the server answers 400 invalid_parameter.
limitint?: Page size per request, 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk from this cursor instead of the newest row.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

반환값

An IAsyncEnumerable<JsonObject> that yields one delivery per step.

예시

await foreach (var delivery in client.Webhooks.IterateWorkspaceDeliveriesAsync(status: "failed")){    Console.WriteLine($"Most recent failure: {delivery["endpointId"]} {delivery["eventType"]} at {delivery["createdAt"]}");     break;}

참고

The generator is lazy, so an abandoned loop costs only the pages you consumed.

다른 사용처

API: GET /webhooks/deliveries
TypeScript: webhooks.iterateWorkspaceDeliveries()
Python: webhooks.iterate_workspace_deliveries()
Ruby: webhooks.iterate_workspace_deliveries
PHP: webhooks->iterateWorkspaceDeliveries
Go: Webhooks.IterateWorkspaceDeliveries
Java: webhooks().iterateWorkspaceDeliveries

`Webhooks.ListActivityAsync`

List one page of what happened to one endpoint

webhooks:read결과를 페이지 단위로 가져옴

시그니처

Task<Page> ListActivityAsync(    string id,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns one page of an endpoint's audit log, newest first, the Activity tab of the endpoint in the app. Every change is a row: created, updated, enabled, disabled, auto_disabled, secret_rotated, tested, replayed and removed, whether it came from the app, from a key over the API, or from OpenEmail itself. actor says who, with label already formatted the way the app shows it: @username for a person, API key <name> for a key, and actor is null when OpenEmail made the change on its own, such as switching an endpoint off after 100 failed events in a row. detail carries what moved: the URL, previousUrl when it changed, the event types and allowlists an update set, or the status and response code a test or a replay got.

Nothing is pruned, and a removed endpoint keeps its history, so this answers for an endpoint that is gone too. since: and until: keep a window.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
sinceDateTimeOffset?: Only rows at or after this instant. A DateTimeOffset, sent as ISO 8601 in UTC.
untilDateTimeOffset?: Only rows before this instant. It has to be later than since:, or the server answers 400 invalid_parameter.
limitint?: Rows per page, a whole number from 1 to 100. The server defaults to 25.
cursorstring?: The nextCursor from the previous page, passed back unchanged. Never build one yourself.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A Page of change objects, with items, hasMore and nextCursor. Each item has id, endpointId, endpointLabel, type, createdAt, actor and detail.

예시

var page = await client.Webhooks.ListActivityAsync("whe_3f9c2a7b1e4d8f60a5c7b92d", since: DateTimeOffset.UtcNow.AddDays(-30)); foreach (var change in page){    Console.WriteLine($"{change["createdAt"]} {change["type"]} by {change["actor"]?["label"]?.ToString() ?? "OpenEmail"}");}

참고

A 404 means no endpoint and no history with that id exists in this workspace. The cursor is opaque: pass nextCursor back as it came, and one this list did not hand out is a 400 invalid_cursor.

다른 사용처

API: GET /webhooks/{id}/activity
TypeScript: webhooks.listActivity()
Python: webhooks.list_activity()
Ruby: webhooks.list_activity
PHP: webhooks->listActivity
Go: Webhooks.ListActivity
Java: webhooks().listActivity
CLI: openemail webhooks list-activity

`Webhooks.ListAllActivityAsync`

Collect one endpoint's whole audit log into one object

webhooks:read결과를 페이지 단위로 가져옴

시그니처

Task<IReadOnlyList<JsonObject>> ListAllActivityAsync(    string id,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Walks every page of Webhooks.ListActivityAsync under the same window and returns every change, newest first.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
sinceDateTimeOffset?: Only rows at or after this instant. A DateTimeOffset, sent as ISO 8601 in UTC.
untilDateTimeOffset?: Only rows before this instant. It has to be later than since:, or the server answers 400 invalid_parameter.
limitint?: Page size for each request, 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk from this cursor instead of the newest row.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

반환값

A list of change objects, newest first.

예시

var changes = await client.Webhooks.ListAllActivityAsync("whe_3f9c2a7b1e4d8f60a5c7b92d"); Console.WriteLine(changes.Count);

참고

If any page fails, the exception is thrown and the rows already fetched are discarded.

다른 사용처

API: GET /webhooks/{id}/activity
TypeScript: webhooks.listAllActivity()
Python: webhooks.list_all_activity()
Ruby: webhooks.list_all_activity
PHP: webhooks->listAllActivity
Go: Webhooks.ListAllActivity
Java: webhooks().listAllActivity

`Webhooks.IterateActivityAsync`

Stream one endpoint's audit log one change at a time

webhooks:read결과를 페이지 단위로 가져옴

시그니처

IAsyncEnumerable<JsonObject> IterateActivityAsync(    string id,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns an IAsyncEnumerable<JsonObject> over Webhooks.ListActivityAsync under the same window, fetching a page only when the one before is used up.

매개변수

idstring필수: Endpoint id, whe_ followed by 24 hex characters.
sinceDateTimeOffset?: Only rows at or after this instant. A DateTimeOffset, sent as ISO 8601 in UTC.
untilDateTimeOffset?: Only rows before this instant. It has to be later than since:, or the server answers 400 invalid_parameter.
limitint?: Page size per request, 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk from this cursor instead of the newest row.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

반환값

An IAsyncEnumerable<JsonObject> that yields one change per step.

예시

await foreach (var change in client.Webhooks.IterateActivityAsync("whe_3f9c2a7b1e4d8f60a5c7b92d")){    if ((string?)change["type"] == "auto_disabled")    {        Console.WriteLine($"Switched off by OpenEmail at {change["createdAt"]}");         break;    }}

다른 사용처

API: GET /webhooks/{id}/activity
TypeScript: webhooks.iterateActivity()
Python: webhooks.iterate_activity()
Ruby: webhooks.iterate_activity
PHP: webhooks->iterateActivity
Go: Webhooks.IterateActivity
Java: webhooks().iterateActivity

`Webhooks.ListWorkspaceActivityAsync`

List one page of what happened to every endpoint

webhooks:read결과를 페이지 단위로 가져옴

시그니처

Task<Page> ListWorkspaceActivityAsync(    IEnumerable<string>? endpointIds = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns one page of the whole workspace's webhook audit log, newest first, the Activity tab of Settings, Webhooks. Every change is a row: created, updated, enabled, disabled, auto_disabled, secret_rotated, tested, replayed and removed, whether it came from the app, from a key over the API, or from OpenEmail itself. actor says who, with label already formatted the way the app shows it: @username for a person, API key <name> for a key, and actor is null when OpenEmail made the change on its own, such as switching an endpoint off after 100 failed events in a row. detail carries what moved: the URL, previousUrl when it changed, the event types and allowlists an update set, or the status and response code a test or a replay got.

endpointIds: narrows it to some endpoints, removed ones included, and since: and until: keep a window.

매개변수

endpointIdsIEnumerable<string>?: Endpoint ids to read, at most 50, as a list or one comma-separated string. Left out, every endpoint in the workspace.
sinceDateTimeOffset?: Only rows at or after this instant. A DateTimeOffset, sent as ISO 8601 in UTC.
untilDateTimeOffset?: Only rows before this instant. It has to be later than since:, or the server answers 400 invalid_parameter.
limitint?: Rows per page, a whole number from 1 to 100. The server defaults to 25.
cursorstring?: The nextCursor from the previous page, passed back unchanged. Never build one yourself.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A Page of change objects, with items, hasMore and nextCursor. Each item has id, endpointId, endpointLabel, type, createdAt, actor and detail.

예시

var page = await client.Webhooks.ListWorkspaceActivityAsync(since: DateTimeOffset.UtcNow.AddDays(-7)); foreach (var change in page){    Console.WriteLine($"{change["endpointLabel"]}: {change["type"]} by {change["actor"]?["label"]?.ToString() ?? "OpenEmail"}");}

참고

The cursor is opaque: pass nextCursor back as it came. One this list did not hand out is a 400 invalid_cursor.

다른 사용처

API: GET /webhooks/activity
TypeScript: webhooks.listWorkspaceActivity()
Python: webhooks.list_workspace_activity()
Ruby: webhooks.list_workspace_activity
PHP: webhooks->listWorkspaceActivity
Go: Webhooks.ListWorkspaceActivity
Java: webhooks().listWorkspaceActivity
CLI: openemail webhooks list-workspace-activity

`Webhooks.ListAllWorkspaceActivityAsync`

Collect the whole webhook audit log into one object

webhooks:read결과를 페이지 단위로 가져옴

시그니처

Task<IReadOnlyList<JsonObject>> ListAllWorkspaceActivityAsync(    IEnumerable<string>? endpointIds = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Walks every page of Webhooks.ListWorkspaceActivityAsync under the same filters and returns every change, newest first.

매개변수

endpointIdsIEnumerable<string>?: Endpoint ids to read, at most 50, as a list or one comma-separated string. Left out, every endpoint in the workspace.
sinceDateTimeOffset?: Only rows at or after this instant. A DateTimeOffset, sent as ISO 8601 in UTC.
untilDateTimeOffset?: Only rows before this instant. It has to be later than since:, or the server answers 400 invalid_parameter.
limitint?: Page size for each request, 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk from this cursor instead of the newest row.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

반환값

A list of change objects, newest first.

예시

var changes = await client.Webhooks.ListAllWorkspaceActivityAsync(since: DateTimeOffset.UtcNow.AddDays(-90), limit: 100); Console.WriteLine(changes.Count);

참고

If any page fails, the exception is thrown and the rows already fetched are discarded.

다른 사용처

API: GET /webhooks/activity
TypeScript: webhooks.listAllWorkspaceActivity()
Python: webhooks.list_all_workspace_activity()
Ruby: webhooks.list_all_workspace_activity
PHP: webhooks->listAllWorkspaceActivity
Go: Webhooks.ListAllWorkspaceActivity
Java: webhooks().listAllWorkspaceActivity

`Webhooks.IterateWorkspaceActivityAsync`

Stream the whole webhook audit log one change at a time

webhooks:read결과를 페이지 단위로 가져옴

시그니처

IAsyncEnumerable<JsonObject> IterateWorkspaceActivityAsync(    IEnumerable<string>? endpointIds = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns an IAsyncEnumerable<JsonObject> over Webhooks.ListWorkspaceActivityAsync under the same filters, fetching a page only when the one before is used up.

매개변수

endpointIdsIEnumerable<string>?: Endpoint ids to read, at most 50, as a list or one comma-separated string. Left out, every endpoint in the workspace.
sinceDateTimeOffset?: Only rows at or after this instant. A DateTimeOffset, sent as ISO 8601 in UTC.
untilDateTimeOffset?: Only rows before this instant. It has to be later than since:, or the server answers 400 invalid_parameter.
limitint?: Page size per request, 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk from this cursor instead of the newest row.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

반환값

An IAsyncEnumerable<JsonObject> that yields one change per step.

예시

await foreach (var change in client.Webhooks.IterateWorkspaceActivityAsync()){    if ((string?)change["type"] == "removed")    {        Console.WriteLine($"{change["endpointLabel"]} was removed by {change["actor"]?["label"]?.ToString() ?? "OpenEmail"} at {change["createdAt"]}");    }}

다른 사용처

API: GET /webhooks/activity
TypeScript: webhooks.iterateWorkspaceActivity()
Python: webhooks.iterate_workspace_activity()
Ruby: webhooks.iterate_workspace_activity
PHP: webhooks->iterateWorkspaceActivity
Go: Webhooks.IterateWorkspaceActivity
Java: webhooks().iterateWorkspaceActivity

`Webhooks.ListEventsAsync`

List the events an endpoint can subscribe to

webhooks:read

시그니처

Task<JsonObject> ListEventsAsync(    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns every event an endpoint can name in eventTypes, each with a sentence saying when it fires, and the limits an endpoint is held to: how many endpoints the workspace may have, which its plan decides, and how many addresses and domains one allowlist may name.

An endpoint that names no events receives every email event except email.replied, so email.replied and the domain, suppression, file and form families only reach an endpoint that asks for them by name.

매개변수

apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A JsonObject with events, a list of objects with id and label, then maxEndpoints, maxAddresses and maxDomains.

예시

var catalogue = await client.Webhooks.ListEventsAsync(); foreach (var entry in catalogue["events"]?.AsArray() ?? []){    Console.WriteLine($"{entry?["id"]}: {entry?["label"]}");} Console.WriteLine($"Up to {catalogue["maxEndpoints"]} endpoints, each naming up to {catalogue["maxAddresses"]} addresses and {catalogue["maxDomains"]} domains");

참고

The same events are the constants of OpenEmail.Constants.WebhookEvents, and WebhookEvents.Values lists their ids, so code that only needs the ids can skip the call.
Retried automatically on network failure, since it only reads.

다른 사용처

API: GET /webhooks/events
TypeScript: webhooks.listEvents()
Python: webhooks.list_events()
Ruby: webhooks.list_events
PHP: webhooks->listEvents
Go: Webhooks.ListEvents
Java: webhooks().listEvents
CLI: openemail webhooks list-events

`Webhooks.StatsAsync`

Read how webhook deliveries went inside a window

webhooks:read

시그니처

Task<JsonObject> StatsAsync(    IEnumerable<string>? endpointIds = null,    DateTimeOffset? since = null,    DateTimeOffset? until = null,    string? grain = null,    int? offsetMinutes = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns the numbers behind the Analytics tab of the Webhooks page: how many delivery attempts were made, how many were delivered and how many failed, the median time a receiver took to answer, a series of buckets, the events sent and the response codes received.

It covers every endpoint, or the ones endpointIds: names. Each try of an event counts as one attempt, so an event retried three times counts three times. The window runs from since: to until:, and left out it is the 30 days before now. grain: sets the bucket width and the key shape, YYYY-MM-DD, YYYY-MM-DDTHH or YYYY-MM-DDTHH:MM, and offsetMinutes: shifts the boundaries so days break where the reader's day does.

매개변수

endpointIdsIEnumerable<string>?: Only these endpoints, at most 50, as a list or one comma-separated string. Left out, every endpoint.
sinceDateTimeOffset?: The start of the window, a DateTimeOffset. Defaults to 30 days before until:.
untilDateTimeOffset?: The end of the window, not included. Defaults to now.
grainstring?: Bucket width: minute, hour or day, defaulting to day.
offsetMinutesint?: Minutes east of UTC to bucket in, from -840 to 840, defaulting to 0. Pass (int)TimeZoneInfo.Local.GetUtcOffset(DateTimeOffset.Now).TotalMinutes for the local zone.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

반환값

A JsonObject with the window it covered (since, until, grain and endpointIds), totals (attempts, delivered, failed and medianDurationMs), buckets, events and codes.

예시

var stats = await client.Webhooks.StatsAsync(    since: DateTimeOffset.UtcNow.AddDays(-7),    grain: "day",    offsetMinutes: (int)TimeZoneInfo.Local.GetUtcOffset(DateTimeOffset.Now).TotalMinutes);var totals = stats["totals"]; Console.WriteLine($"{totals?["delivered"]} of {totals?["attempts"]} attempts delivered, median {totals?["medianDurationMs"]?.ToString() ?? "n/a"} ms"); foreach (var code in stats["codes"]?.AsArray() ?? []){    Console.WriteLine($"{code?["id"]}: {code?["count"]}");}

참고

buckets is sparse: a bucket with no attempt has no entry, so a chart must fill the gaps.
medianDurationMs is null when nothing was sent in the window.
Retried automatically on network failure, since it only reads.

다른 사용처

API: GET /webhooks/stats
TypeScript: webhooks.stats()
Python: webhooks.stats()
Ruby: webhooks.stats
PHP: webhooks->stats
Go: Webhooks.Stats
Java: webhooks().stats
CLI: openemail webhooks stats