client.Broadcasts
هر متد در این فضای نام: امضا، پارامترها، آنچه برمیگرداند و یک نمونه.
متدها
One message sent to everybody in one or more audiences, a personalised copy for each person, with unsubscribe handled for you.
Broadcasts.PreviewAsync
Count who a broadcast to some audiences would reach
Task<JsonObject> PreviewAsync( IReadOnlyDictionary<string, object?> body, string? apiKey = null, CancellationToken cancellationToken = default)Returns the numbers SendAsync would work from, without sending or writing anything: recipients, the people a broadcast to these audiences would reach now, unsubscribed, the contacts skipped because they have unsubscribed from every one of these audiences they are in, and suppressed, the subscribed contacts skipped because their address is on the suppression list. A contact in several of the audiences counts once.
The count is taken at the moment of the call, so contacts who join or leave before a send change it. Only audienceIds is sent, so you can pass the same object you are about to give SendAsync.
پارامترها
audienceIdsIEnumerable<string>الزامی1 to 10 audience ids. One that names no audience in the workspace is a 404
audience_not_found.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
خروجی
A JsonObject with audienceIds as sent, recipients, unsubscribed and suppressed.
نمونه
var draft = new Body{ ["audienceIds"] = new[] { "aud_4c1b8e2a7d9f05c36b4e8a71", "aud_7e3d9a1c5b2f84e06d9a3c51" }, ["from"] = "Acme <[email protected]>", ["subject"] = "The September release", ["text"] = "Hi {{firstName|there}}, here is what changed this month.",}; var reach = await client.Broadcasts.PreviewAsync(draft); Console.WriteLine($"{reach["recipients"]} will get it, {reach["unsubscribed"]} unsubscribed, {reach["suppressed"]} suppressed"); if ((int?)reach["recipients"] > 0){ await client.Broadcasts.SendAsync(draft);}نکتهها
Needs only
audiences:read, so a key that cannot send can still show somebody the count.The SDK retries it after a network failure or a retryable status, since it changes nothing.
همچنین در دسترس در
Broadcasts.SendAsync
Send one message to everybody in one or more audiences
Task<JsonObject> SendAsync( IReadOnlyDictionary<string, object?> body, string? idempotencyKey = null, string? apiKey = null, CancellationToken cancellationToken = default)Creates a broadcast: one message sent to every contact in the audiences you name, as a separate copy for each person. Every copy has exactly one recipient and no cc or bcc, so nobody sees who else it went to, and every copy is an ordinary email with its own msg_ id, events, tracking and webhooks. Emails.ListAsync with broadcastId: lists them. Copies are not filed in the Sent folder, because the broadcast is the record.
The call returns straight away with the broadcast queued, or scheduled when you pass scheduledAt, and the sending happens in the background, 50 people at a time. Poll GetAsync to follow status and counts as it goes.
Who gets it: every contact in at least one of audienceIds, counted once however many of them hold it, except a contact that has unsubscribed from every one of those audiences it is in, and except an address on the suppression list. A contact added to one of the audiences after this call but before the sending reaches it is included. counts.recipients is the estimate taken at the call, and PreviewAsync returns the same count without sending.
subject, html and text take merge fields, filled in from each contact: firstName, lastName, name, email and unsubscribeUrl, each written between double braces. Each takes a fallback after a bar, so {{firstName|there}} reads there for a contact with no name. The first name is the first word of the contact's name and the last name is the rest. Values are escaped in html, and any other {{…}} is left as written. With template, the same values are passed as props, but only the ones the template declares.
Every copy carries the one-click unsubscribe headers mail clients and the large mailbox providers look for. An html or text body that does not place the unsubscribeUrl merge field itself gets a one-line footer with the link, while a template is sent as it is, so put the unsubscribeUrl merge field in the template. Following the link marks the person unsubscribed in every audience this broadcast went to. Their other audiences, their contact and mail sent to them one message at a time are not affected.
The whole send is checked against the plan's monthly sends before anything is written. A broadcast the allowance cannot cover throws 429 send_quota_exceeded and leaves nothing behind, and each copy counts as one send.
پارامترها
audienceIdsIEnumerable<string>الزامی1 to 10 audience ids such as
aud_9f2c4b7e1a0d63d84c5f2e7b. A contact in several of them gets one copy. An id that names no audience in the workspace is a 404audience_not_foundand nothing is sent.fromstring or dictionaryالزامیSender as
[email protected],Acme <[email protected]>or a dictionary withemailandname. It must be an address the key may send as, otherwise 403from_address_forbidden.replyTostring or dictionaryWhere replies go, the same for every copy.
subjectstringRequired unless a template supplies it, at most 998 characters. Takes merge fields.
htmlstringHTML body, at most 1,000,000 characters, with merge fields. Without the
unsubscribeUrlmerge field in it an unsubscribe footer is added.textstringPlain text body, at most 1,000,000 characters, with merge fields. Without the
unsubscribeUrlmerge field in it an unsubscribe line is added.templatedictionaryA stored template instead of
htmlandtext, never beside them, as a dictionary withidand optionallyversion,propsandslots. The merge values reach it as props it declares, such asfirstNameandunsubscribeUrl.trackingdictionaryOpen and link tracking for every copy, as a dictionary with
opensandclicks, each true or false. A field left out follows the address it is sent from when that address set it, and is on otherwise.tagsdictionaryUp to 8 tags as a dictionary of names to values, keys of 1 to 64 letters, digits,
_or-, values up to 256 characters. Every copy carries them, plusbroadcast_id, which the server adds.scheduledAtDateTimeOffset or stringA
DateTimeOffset, an ISO 8601 instant or a duration such asPT2HorP1D, in the future and at most 365 days out. ADateTimeOffsetgoes out as an ISO 8601 instant in UTC. Left out, the sending starts straight away.idempotencyKeystring?Your own key, 1 to 255 characters of letters, digits,
_,.,:or-. Left out, the SDK makes one for the call, so its own retries never send twice. Sending the same key again answers with the broadcast it created instead of a new one. The same key with a different body is a 422idempotency_key_reuse.apiKeystring?Sends with this key instead of the client's.
cancellationTokenCancellationTokenCancels the request.
خروجی
A JsonObject, the broadcast as GetAsync returns it plus replayed, with id (brd_ plus 24 hex), status queued or scheduled, audienceIds, from, subject, scheduledAt, createdAt and counts, whose recipients is the estimate and whose other counts start at 0.
نمونه
var broadcast = await client.Broadcasts.SendAsync(new Body{ ["audienceIds"] = new[] { "aud_4c1b8e2a7d9f05c36b4e8a71" }, ["from"] = new Body { ["email"] = "[email protected]", ["name"] = "Acme" }, ["subject"] = "{{firstName|Hello}}, the September release is out", ["html"] = "<p>Hi {{firstName|there}},</p><p>Here is what changed.</p><p><a href=\"{{unsubscribeUrl}}\">Unsubscribe</a></p>", ["text"] = "Hi {{firstName|there}},\n\nHere is what changed.\n\nUnsubscribe: {{unsubscribeUrl}}", ["tags"] = new Body { ["campaign"] = "release-2026-09" }, ["scheduledAt"] = DateTimeOffset.UtcNow.AddHours(2),}, idempotencyKey: "release-2026-09"); Console.WriteLine($"{broadcast["id"]} {broadcast["status"]}, about {broadcast["counts"]?["recipients"]} people");نکتهها
Safe to retry. Every call carries an
Idempotency-Key, yours or one the SDK makes, so a retry after a network failure answers with the broadcast the first attempt created, withreplayed: true, instead of sending again. Keys are scoped to the API key or app that sent them. Reusing a key with a different body is a 422idempotency_key_reuse.Refusals: 422
no_recipientswhen the audiences are empty or everybody in them has unsubscribed or is suppressed, 409domain_not_sendablewhen thefromdomain cannot sign mail yet, 422 ontemplate.*when the template does not resolve.No attachments, cc, bcc, translation or encryption. A body from
htmlortextand atemplatetogether are refused.A test key (
oe_test_) creates a broadcast whose copies are marked sent and delivered to nobody, like any test send.
همچنین در دسترس در
- API
POST /broadcasts- TypeScript
broadcasts.send()- Python
broadcasts.send()- Ruby
broadcasts.send- PHP
broadcasts->send- Go
Broadcasts.Send- Java
broadcasts().send- CLI
openemail broadcasts send
Broadcasts.ListAsync
List one page of broadcasts, newest first
Task<Page> ListAsync( string? audienceId = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns one page of the broadcasts in the workspace, newest first, each with live counts. audienceId: keeps the ones that were sent to that audience, alone or beside others.
Paging is keyset: limit: takes 1 to 100 and defaults to 25, and nextCursor, the id of the last broadcast on the page, goes back as cursor: while hasMore is true. Send the same audienceId: with every page. ListAllAsync and IterateAsync do that walk for you.
The individual messages are not here. List the copies of one broadcast with Emails.ListAsync and broadcastId:.
پارامترها
audienceIdstring?Only the broadcasts that included this audience. An id that names no audience answers an empty page.
limitint?Rows per page, a whole number from 1 to 100. The server defaults to 25.
cursorstring?The
nextCursorfrom the previous page, a broadcast id. One that names no broadcast in the workspace is a 400invalid_cursor.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
خروجی
A Page with items, hasMore and nextCursor. Each item has id, status, audienceIds, from, subject, counts and the timestamps.
نمونه
var page = await client.Broadcasts.ListAsync(audienceId: "aud_4c1b8e2a7d9f05c36b4e8a71", limit: 10); foreach (var broadcast in page){ var counts = broadcast["counts"]; Console.WriteLine($"{broadcast["createdAt"]} {broadcast["subject"]} {broadcast["status"]} {counts?["sent"]}/{counts?["recipients"]}");}نکتهها
A key limited to particular addresses or domains lists only the broadcasts sent from an address or domain it holds.
همچنین در دسترس در
- API
GET /broadcasts- TypeScript
broadcasts.list()- Python
broadcasts.list()- Ruby
broadcasts.list- PHP
broadcasts->list- Go
Broadcasts.List- Java
broadcasts().list- CLI
openemail broadcasts list
Broadcasts.ListAllAsync
Collect every broadcast into one object
Task<IReadOnlyList<JsonObject>> ListAllAsync( string? audienceId = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Follows nextCursor from page to page and returns every broadcast in the workspace, newest first, or every one sent to audienceId: when you pass it. limit sets the page size of each request, not the total.
پارامترها
audienceIdstring?Only the broadcasts that included this audience.
limitint?Page size per request, from 1 to 100, defaulting to 25 on the server.
cursorstring?A broadcast id to start after.
apiKeystring?Overrides the client's API key for every page of this walk.
cancellationTokenCancellationTokenCancels the request.
خروجی
A list of JsonObject items holding every broadcast across all pages, each shaped like an item of ListAsync.
نمونه
var broadcasts = await client.Broadcasts.ListAllAsync(limit: 100); Console.WriteLine(broadcasts.Count);نکتهها
A failure on any page throws out of the whole call.
Every row carries live counts, so collecting a long history reads the copies of every broadcast in it. Use
IterateAsyncto stop early.A key limited to particular addresses or domains lists only the broadcasts sent from an address or domain it holds.
همچنین در دسترس در
Broadcasts.IterateAsync
Stream broadcasts one at a time, newest first
IAsyncEnumerable<JsonObject> IterateAsync( string? audienceId = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns an IAsyncEnumerable<JsonObject> that yields broadcasts one at a time, newest first, and requests the next page only once the current one is drained. Breaking out of the loop stops the requests, so this is the cheap way to find the latest broadcast that matches something the filters cannot express.
پارامترها
audienceIdstring?Only the broadcasts that included this audience.
limitint?Page size per request, from 1 to 100, defaulting to 25 on the server.
cursorstring?A broadcast id to start after.
apiKeystring?Overrides the client's API key for every page of this walk.
cancellationTokenCancellationTokenCancels the request.
خروجی
An IAsyncEnumerable<JsonObject> that yields one broadcast per step.
نمونه
using OpenEmail.Constants; await foreach (var broadcast in client.Broadcasts.IterateAsync()){ if ((string?)broadcast["status"] == BroadcastStatuses.Sending) { Console.WriteLine($"Still going: {broadcast["id"]}, {broadcast["counts"]?["queued"]} waiting"); break; }}نکتهها
The generator is lazy, so an abandoned loop costs only the pages you consumed.
A key limited to particular addresses or domains lists only the broadcasts sent from an address or domain it holds.
همچنین در دسترس در
Broadcasts.GetAsync
Read one broadcast and how far it has got
Task<JsonObject> GetAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default)Returns one broadcast with counts read live from its copies, which makes this the call to poll while it sends.
status moves from scheduled or queued to sending and settles on sent once every copy handed over has gone out or failed. It reads sending for as long as copies are still waiting, even after the last person was reached and completedAt was set. cancelled and failed are the other two ends, and on failed lastError says why: the from address can no longer be sent from, the template stopped resolving, the plan ran out part way, the sending itself kept failing, or not one copy could be written.
counts.recipients is the estimate taken when it was created. created is the copies written, one per person reached, skipped the people passed over because their address was suppressed by then, and failedToQueue the people whose copy could not be written. queued, sending, sent, failed and cancelled count the copies by the state each one is in now.
پارامترها
idstringالزامیA
brd_id fromSendAsyncorListAsync.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
خروجی
A JsonObject with id, status, mode, source, audienceIds, from, subject, counts, lastError, scheduledAt, startedAt, completedAt, cancelledAt, createdAt and updatedAt.
نمونه
var broadcast = await client.Broadcasts.GetAsync("brd_5a8c1e3f7b2d94a06c8e1f3b"); Console.WriteLine($"{broadcast["status"]} {broadcast["lastError"]}");نکتهها
A missing broadcast throws an
OpenEmailApiExceptionwhoseIsNotFoundis true, withCodebroadcast_not_found. An id from another workspace is a 404 too.For who each copy went to and what happened to it, use
ListRecipientsAsync,GetRecipientAsyncreads one copy with its content, andStatsAsyncsums it up.A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other id throws an
OpenEmailApiExceptionwithCodebroadcast_not_found, as if the broadcast did not exist.
همچنین در دسترس در
- API
GET /broadcasts/{id}- TypeScript
broadcasts.get()- Python
broadcasts.get()- Ruby
broadcasts.get- PHP
broadcasts->get- Go
Broadcasts.Get- Java
broadcasts().get- CLI
openemail broadcasts get
Broadcasts.StatsAsync
Read how a broadcast performed
Task<JsonObject> StatsAsync( string id, string? grain = null, int? offsetMinutes = null, int? days = null, int? minutes = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns the totals and a series for one broadcast. totals counts copies sent, delivered, bounced, complained (reported as spam) and failed, pending for the ones still waiting, and people who opened, clicked and unsubscribed, with opens and clicks as event counts. series is sparse and oldest first: one bucket per grain in which something happened, counting each person once at the first time it happened to them, so it adds up to the totals.
Pass days: or minutes: to also read what happened lately. window then counts the copies delivered, bounced, reported as spam, opened, clicked and unsubscribed inside it, and series keeps only its buckets, while totals still covers the whole broadcast. Without either, window is null.
پارامترها
idstringالزامیA
brd_id fromSendAsyncorListAsync.grainstring?Bucket width:
minute,hourorday, defaulting tohour.offsetMinutesint?Minutes east of UTC to cut the buckets in, from -840 to 840. Pass
(int)TimeZoneInfo.Local.GetUtcOffset(DateTimeOffset.Now).TotalMinutesfor the zone of the machine.daysint?Reads a window of this many days too, from 1 to 1095. It starts at the beginning of its first
grainbucket and ends now.minutesint?The window in minutes, from 1 to 1576800, which wins over
dayswhen both are sent.apiKeystring?Overrides the client API key for this call only.
cancellationTokenCancellationTokenCancels the request.
خروجی
A JsonObject with broadcastId, grain, totals, window and series, each bucket of series an object with bucket, delivered, opened, clicked and unsubscribed. window is an object with since, delivered, bounced, complained, opened, clicked and unsubscribed, or null when no window was asked for.
نمونه
var stats = await client.Broadcasts.StatsAsync("brd_5a8c1e3f7b2d94a06c8e1f3b", grain: "day", days: 7);var sent = (double?)stats["totals"]?["sent"] ?? 0;var opened = (double?)stats["totals"]?["opened"] ?? 0; Console.WriteLine($"{(sent > 0 ? Math.Round(opened / sent * 100) : 0)}% of the people sent it opened it"); foreach (var bucket in stats["series"]?.AsArray() ?? []){ Console.WriteLine($"{bucket?["bucket"]}: {bucket?["opened"]} opened, {bucket?["clicked"]} clicked");}نکتهها
Read only, so the SDK retries it after a network failure like any other read.
A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other id throws an
OpenEmailApiExceptionwithCodebroadcast_not_found, as if the broadcast did not exist.
همچنین در دسترس در
Broadcasts.AnalyticsAsync
Read how broadcasts did over a time window
Task<JsonObject> AnalyticsAsync( IEnumerable<string>? broadcastIds = null, int? days = null, int? minutes = null, string? grain = null, int? offsetMinutes = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns the numbers behind the Analytics tab of the Broadcasts page in one request: how the live broadcasts sent inside a window did, added up in totals and cut to grain in series, and one row per broadcast in broadcasts so they can be compared.
A copy counts when it was sent inside the window, and everything that happened to it afterwards counts with it, so an open today of a copy sent last week is in a 30 day window but not in a 1 day one. Test mode broadcasts are left out. totals and series add up the broadcasts named in broadcastIds:, or every one when it is left out, while broadcasts always lists every broadcast in the window, newest first.
series is sparse and oldest first: a bucket in which nothing happened has no entry, so a chart must fill the gaps. It counts each person once, at the first time it happened to them. 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. The window starts at the beginning of its oldest bucket, reported as since, and ends now, reported as until.
پارامترها
broadcastIdsIEnumerable<string>?Up to 50 broadcast ids for
totalsandseriesto add up, as a dictionary or one comma-separated string, sent comma separated. Leave it out, or pass an empty dictionary, for every broadcast in the window. An id with no copy in the window adds nothing, and more than 50 is a 422.daysint?Window length in days, from 1 to 1095, defaulting to 30.
minutesint?Window length in minutes, from 1 to 1576800, which wins over
dayswhen both are sent.grainstring?Bucket width:
minute,hourorday, defaulting today.offsetMinutesint?Minutes east of UTC to cut the buckets in, from -840 to 840, defaulting to 0. Pass
(int)TimeZoneInfo.Local.GetUtcOffset(DateTimeOffset.Now).TotalMinutesfor the zone of the machine.apiKeystring?Overrides the client API key for this call only.
cancellationTokenCancellationTokenCancels the request.
خروجی
A JsonObject with object set to broadcast_analytics, since, until, grain, offsetMinutes, broadcastIds, totals, series and broadcasts. totals has broadcasts and the counts the totals of StatsAsync has, each entry of series is an object with bucket, sent, delivered, opened, clicked and unsubscribed, and each entry of broadcasts has id, subject, status, sentAt and the same counts.
نمونه
var offsetMinutes = (int)TimeZoneInfo.Local.GetUtcOffset(DateTimeOffset.Now).TotalMinutes;var analytics = await client.Broadcasts.AnalyticsAsync(days: 90, offsetMinutes: offsetMinutes);var totals = analytics["totals"]; Console.WriteLine($"{totals?["broadcasts"]} broadcasts, {totals?["opened"]} people opened one"); foreach (var row in analytics["broadcasts"]?.AsArray() ?? []){ Console.WriteLine($"{row?["subject"]}: {row?["sent"]} sent, {row?["opened"]} opened, {row?["clicked"]} clicked");}نکتهها
Read only, so the SDK retries it after a network failure like any other read.
opened,clickedandunsubscribedcount people, whileopensandclickscount events.A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds, and the rest are left out as if they did not exist.
همچنین در دسترس در
Broadcasts.ListRecipientsAsync
List who a broadcast went to and what happened to each copy
Task<Page> ListRecipientsAsync( string id, string? filter = null, string? q = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns one page of the people a broadcast went to, one row per copy, sorted by address. Each row says the copy's status, when it was sent and delivered, whether it bounced or was reported as spam, how often it was opened and clicked, and whether the person unsubscribed from one of the broadcast's audiences after it went out.
Opens and clicks leave out image proxies and link scanners, and stay 0 when the broadcast went out with tracking off. emailId is the copy's msg_ id, which GetRecipientAsync reads with its content and Emails.GetAsync reads as a sent email.
پارامترها
idstringالزامیA
brd_id fromSendAsyncorListAsync.filterstring?Keeps one group:
pending,sent,delivered,opened,not_opened(sent and never opened),clicked,bounced,complained,failed(failed or cancelled) orunsubscribed.OpenEmail\Constants\BroadcastRecipientFiltersnames them.qstring?Searches the address and the name, ignoring case.
limitint?Page size, from 1 to 200. The server defaults to 50.
cursorstring?The
nextCursorof the previous page. Send the samefilter:andq:with it.apiKeystring?Overrides the client API key for this call only.
cancellationTokenCancellationTokenCancels the request.
خروجی
A Page with items, hasMore and nextCursor. Each item has emailId, contactId, email, name, status, sentAt, deliveredAt, bouncedAt, complainedAt, failure, opens, firstOpenAt, clicks, firstClickAt and unsubscribedAt.
نمونه
using OpenEmail.Constants; var page = await client.Broadcasts.ListRecipientsAsync("brd_5a8c1e3f7b2d94a06c8e1f3b", filter: BroadcastRecipientFilters.Bounced); foreach (var copy in page){ Console.WriteLine($"{copy["email"]} bounced at {copy["bouncedAt"]}");}نکتهها
A missing broadcast throws an
OpenEmailApiExceptionwithCodebroadcast_not_found.A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other id throws an
OpenEmailApiExceptionwithCodebroadcast_not_found, as if the broadcast did not exist.
همچنین در دسترس در
Broadcasts.ListAllRecipientsAsync
Collect everybody a broadcast went to into one object
Task<IReadOnlyList<JsonObject>> ListAllRecipientsAsync( string id, string? filter = null, string? q = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Walks every page of ListRecipientsAsync and returns every copy of the broadcast, sorted by address. One request per page, with the same filter: and q: on each.
پارامترها
idstringالزامیA
brd_id fromSendAsyncorListAsync.filterstring?Keeps one group:
pending,sent,delivered,opened,not_opened(sent and never opened),clicked,bounced,complained,failed(failed or cancelled) orunsubscribed.OpenEmail\Constants\BroadcastRecipientFiltersnames them.qstring?Searches the address and the name, ignoring case.
limitint?Page size for each request, from 1 to 200. The server defaults to 50.
cursorstring?Starts the walk after this cursor instead of the first page.
apiKeystring?Overrides the client API key for every page of this walk.
cancellationTokenCancellationTokenCancels the request.
خروجی
A list of JsonObject items holding every copy that matches, each shaped like an item of ListRecipientsAsync.
نمونه
using OpenEmail.Constants; var unopened = await client.Broadcasts.ListAllRecipientsAsync("brd_5a8c1e3f7b2d94a06c8e1f3b", filter: BroadcastRecipientFilters.NotOpened); Console.WriteLine($"{string.Join(Environment.NewLine, unopened.Select(row => row?["email"]))}");نکتهها
If any page fails the call throws and the rows already fetched are discarded.
A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other id throws an
OpenEmailApiExceptionwithCodebroadcast_not_found, as if the broadcast did not exist.
همچنین در دسترس در
Broadcasts.IterateRecipientsAsync
Walk everybody a broadcast went to, one copy at a time
IAsyncEnumerable<JsonObject> IterateRecipientsAsync( string id, string? filter = null, string? q = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns an IAsyncEnumerable<JsonObject> that yields every copy of the broadcast one at a time, fetching the next page only when the loop asks for it, sorted by address. Breaking out of the loop stops the requests.
پارامترها
idstringالزامیA
brd_id fromSendAsyncorListAsync.filterstring?Keeps one group:
pending,sent,delivered,opened,not_opened(sent and never opened),clicked,bounced,complained,failed(failed or cancelled) orunsubscribed.OpenEmail\Constants\BroadcastRecipientFiltersnames them.qstring?Searches the address and the name, ignoring case.
limitint?Page size for each request, from 1 to 200. The server defaults to 50.
cursorstring?Starts after this cursor instead of the first page.
apiKeystring?Overrides the client API key for every page of this walk.
cancellationTokenCancellationTokenCancels the request.
خروجی
An IAsyncEnumerable<JsonObject> that yields one copy per step, each shaped like an item of ListRecipientsAsync.
نمونه
using OpenEmail.Constants; var copies = client.Broadcasts.IterateRecipientsAsync("brd_5a8c1e3f7b2d94a06c8e1f3b", filter: BroadcastRecipientFilters.Clicked); await foreach (var copy in copies){ Console.WriteLine($"{copy["email"]} clicked {copy["clicks"]} times");}نکتهها
Memory stays flat however large the broadcast, because only one page is held at a time.
A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other id throws an
OpenEmailApiExceptionwithCodebroadcast_not_found, as if the broadcast did not exist.
همچنین در دسترس در
Broadcasts.GetRecipientAsync
Read one person's copy of a broadcast
Task<JsonObject> GetRecipientAsync( string id, string emailId, string? apiKey = null, CancellationToken cancellationToken = default)Returns one copy: the same row ListRecipientsAsync gives, plus the subject, html and text exactly as that person received them, with the merge fields filled in and their own unsubscribe link. The HTML is from before open and click tracking was added.
پارامترها
idstringالزامیA
brd_id fromSendAsyncorListAsync.emailIdstringالزامیThe
emailIdof the copy, fromListRecipientsAsync.apiKeystring?Overrides the client API key for this call only.
cancellationTokenCancellationTokenCancels the request.
خروجی
A JsonObject with emailId, contactId, email, name, status, sentAt, deliveredAt, bouncedAt, complainedAt, failure, opens, firstOpenAt, clicks, firstClickAt and unsubscribedAt, plus subject, html and text.
نمونه
var copy = await client.Broadcasts.GetRecipientAsync("brd_5a8c1e3f7b2d94a06c8e1f3b", "msg_01dad25067bc4dac966d515d"); Console.WriteLine($"{copy["subject"]}, delivered {copy["deliveredAt"]?.ToString() ?? "not yet"}");Console.WriteLine($"{copy["text"]}");نکتهها
An
emailIdthat is not a copy of this broadcast throws anOpenEmailApiExceptionwithCoderecipient_not_found.A key limited to particular addresses or domains reads only broadcasts sent from an address or domain it holds. Any other id throws an
OpenEmailApiExceptionwithCodebroadcast_not_found, as if the broadcast did not exist.
همچنین در دسترس در
Broadcasts.CancelAsync
Stop a broadcast that is scheduled, queued or still sending
Task<JsonObject> CancelAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default)Stops a broadcast that is scheduled, queued or sending, including one that has reached everybody while some copies are still waiting to go. Nobody else is added, and every copy still waiting is cancelled. A copy already being handed over finishes, and copies that have gone cannot be recalled, so counts.sent keeps them and counts.cancelled shows what was stopped.
Once every copy has gone out there is nothing left to stop, and the call throws 409 broadcast_not_cancellable. A failed broadcast with copies still waiting can be cancelled to stop them, and one with nothing waiting is refused the same way. Cancelling a broadcast that is already cancelled returns it as it stands, so the call is safe to repeat, and the SDK retries it after a network failure.
پارامترها
idstringالزامیThe
brd_id to cancel.apiKeystring?Cancels with this key instead of the client's.
cancellationTokenCancellationTokenCancels the request.
خروجی
A JsonObject, the broadcast as GetAsync returns it in its new state: status cancelled with cancelledAt set and the copies counted by where each one ended up.
نمونه
var scheduled = await client.Broadcasts.SendAsync(new Body{ ["audienceIds"] = new[] { "aud_4c1b8e2a7d9f05c36b4e8a71" }, ["from"] = "[email protected]", ["subject"] = "Doors open on Friday", ["text"] = "Hi {{firstName|there}}, doors open at nine.", ["scheduledAt"] = "P1D",}); var cancelled = await client.Broadcasts.CancelAsync(scheduled["id"]!.GetValue<string>()); Console.WriteLine($"{cancelled["status"]}, {cancelled["counts"]?["cancelled"]} copies stopped");نکتهها
Cancelling a scheduled broadcast before
scheduledAtsends nothing at all.A cancelled broadcast stays cancelled. There is no resume, so send again to the audiences that still need it.
A key limited to particular addresses or domains cancels only broadcasts sent from an address or domain it holds. Any other id throws an
OpenEmailApiExceptionwithCodebroadcast_not_found, as if the broadcast did not exist.