client.Suppressions
Every method in this namespace: its signature, its parameters, what it returns and an example.
Methods
The addresses this workspace will not send to: hard bounces, complaints and the ones you block by hand.
Suppressions.ListAsync
List one page of the suppression list
Task<Page> ListAsync( string? q = null, string? reason = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns one page of the addresses this workspace will not send to, newest first: every address that bounced hard, complained, or was added by hand. ListAllAsync collects every page and IterateAsync walks them lazily.
A send to a suppressed address is refused for that recipient before anything leaves, and a message whose recipients are all suppressed fails outright. The list belongs to the whole workspace, so a key limited to some addresses reads all of it, and a row names the recipient, never which of your addresses sent to it.
removable says whether RemoveAsync will take the address off. A hard bounce is permanent here, because the address could not take mail. A complaint or a manual entry can be removed.
Parameters
qstring?Searches the address, the reason and the detail. Words match loosely, and a close spelling is tried when nothing matches exactly.
reasonstring?Keeps one kind:
bounce,complaintormanual, as inNextmail\Constants\SuppressionReasons.limitint?Page size, from 1 to 100. The server defaults to 25.
cursorstring?The
nextCursorof the previous page. Leave it out for the first page.apiKeystring?Overrides the client API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A Page with items, hasMore and nextCursor. Each item has id, email, reason, detail, removable and createdAt.
Example
using Nextmail.Constants; var page = await client.Suppressions.ListAsync(reason: SuppressionReasons.Complaint); foreach (var row in page){ Console.WriteLine($"{row["email"]} since {row["createdAt"]}");}Notes
Needs
settings:read, the scope the Blocked addresses screen in Settings is gated on.The cursor is opaque and holds where the last row sat, so an address removed between pages never breaks the walk. A cursor this list did not hand out is a 400
invalid_cursor.
Also available in
Suppressions.ListAllAsync
Collect the whole suppression list into one object
Task<IReadOnlyList<JsonObject>> ListAllAsync( string? q = null, string? reason = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Walks every page of ListAsync and returns every suppressed address, newest first. One request per page, with the same filters on each.
Parameters
qstring?Searches the address, the reason and the detail. Words match loosely, and a close spelling is tried when nothing matches exactly.
reasonstring?Keeps one kind:
bounce,complaintormanual, as inNextmail\Constants\SuppressionReasons.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 API key for every page of this walk.
cancellationTokenCancellationTokenCancels the request.
Returns
A list of JsonObject items holding every suppressed address, each with the fields ListAsync returns.
Example
var rows = await client.Suppressions.ListAllAsync(limit: 100); Console.WriteLine(rows.Count);Notes
If any page fails the call throws and the rows already fetched are discarded.
Also available in
Suppressions.IterateAsync
Stream the suppression list one address at a time
IAsyncEnumerable<JsonObject> IterateAsync( string? q = null, string? reason = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns an IAsyncEnumerable<JsonObject> that yields one suppressed address at a time, newest first, and requests the next page only once the current one is drained. Nothing is fetched until you consume it, and breaking out of the loop stops the requests.
Parameters
qstring?Searches the address, the reason and the detail. Words match loosely, and a close spelling is tried when nothing matches exactly.
reasonstring?Keeps one kind:
bounce,complaintormanual, as inNextmail\Constants\SuppressionReasons.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 API key for every page of this walk.
cancellationTokenCancellationTokenCancels the request.
Returns
An IAsyncEnumerable<JsonObject> that yields one suppressed address per step.
Example
await foreach (var row in client.Suppressions.IterateAsync(q: "example.com")){ Console.WriteLine($"{row["email"]} {row["reason"]}");}Notes
The generator is lazy, so an abandoned loop costs only the pages you consumed.
Also available in
Suppressions.GetAsync
Read one suppressed address by id
Task<JsonObject> GetAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default)Returns one row of the suppression list: the address, why it is there, the detail the bounce or complaint carried, whether it can be removed and when it was added.
Parameters
idstringRequiredThe id from
ListAsync.apiKeystring?Overrides the client API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A JsonObject with id, email, reason, detail, removable and createdAt.
Example
var row = await client.Suppressions.GetAsync("7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e"); Console.WriteLine($"{row["email"]}{((bool?)row["removable"] == true ? " can be removed" : " stays on the list")}");Notes
An id that is not on this workspace is a 404
resource_not_found.
Also available in
Suppressions.AddAsync
Stop sending to an address
Task<JsonObject> AddAsync( IReadOnlyDictionary<string, object?> body, string? apiKey = null, CancellationToken cancellationToken = default)Puts an address on the suppression list by hand, with reason set to manual, so no address in the workspace sends to it again until it is removed. It is the Block an address control on the Blocked addresses screen.
Adding an address that is already there changes nothing: the server answers 200 with the row it already holds, whatever its reason, where a new entry answers 201. Either way you get the row back. A new entry fires suppression.added to the webhooks that asked for it.
Parameters
emailstringRequiredThe address to stop sending to. It is trimmed and lower cased.
apiKeystring?Overrides the client API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A JsonObject for the address, new or already there, with the fields GetAsync returns.
Example
var row = await client.Suppressions.AddAsync(new Body { ["email"] = "[email protected]" }); Console.WriteLine($"{row["reason"]} since {row["createdAt"]}");Notes
Safe to repeat: a second add finds the first entry, so the SDK retries it after a network failure.
A key limited to particular addresses or domains is refused with 422
capability_unsupported, because the list stops mail from every address in the workspace. So is an app connected by anybody but the owner.
Also available in
Suppressions.RemoveAsync
Allow mail to an address again
Task<JsonObject> RemoveAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default)Takes an address off the suppression list, so mail may go to it again. It is Allow again on the Blocked addresses screen, and it fires suppression.removed.
Only a complaint or a manual entry can be removed. A hard bounce answers 409 suppression_not_removable and stays, because the address could not take mail: check it is spelled right and send to the corrected one instead.
Parameters
idstringRequiredThe id from
ListAsync.apiKeystring?Overrides the client API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A JsonObject with object set to suppression, the id, the email, and deleted set to true.
Example
var page = await client.Suppressions.ListAsync(q: "[email protected]"); if (page.Count > 0){ try { await client.Suppressions.RemoveAsync(page[0]["id"]!.GetValue<string>()); } catch (NextmailApiException error) when (error.IsConflict) { Console.WriteLine($"{page[0]["email"]} bounced hard, so it stays on the list"); }}Notes
The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
A key limited to particular addresses or domains is refused with 422
capability_unsupported.
Also available in
Suppressions.ListUnsubscribesAsync
List one page of the people who unsubscribed
Task<Page> ListUnsubscribesAsync( string? q = null, string? source = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns one page of the people who asked this workspace for no more marketing mail, newest first. It is the Unsubscribed list on the Blocked addresses screen in Settings.
An unsubscribe belongs to the whole workspace and outlasts the contact: removing the person from an audience, deleting the contact or importing the address again never brings them back. Every broadcast and automation email skips them, and adding them to an audience records them there as unsubscribed. Mail people write to you, and your replies, still reach them, because only marketing mail stops. ListAsync is the hard block on every kind of mail.
removable says whether RemoveUnsubscribeAsync takes it back, which is true only for one the team recorded by hand. A person who unsubscribed decides alone whether to come back: through a sign-up form they confirm from their inbox, or Subscribe again on the unsubscribe page.
Parameters
qstring?One whole address, matched exactly and without regard to case. The addresses are stored encrypted, so a part of one finds nothing.
sourcestring?Keeps one way of unsubscribing:
link,one_click,complaint,importormanual, as inNextmail\Constants\UnsubscribeSources.limitint?Page size, from 1 to 100. The server defaults to 25.
cursorstring?The
nextCursorof the previous page. Leave it out for the first page.apiKeystring?Overrides the client API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A Page with items, hasMore and nextCursor. Each item has email, source, broadcastId, automationId, removable and createdAt.
Example
using Nextmail.Constants; var page = await client.Suppressions.ListUnsubscribesAsync(source: UnsubscribeSources.OneClick); foreach (var row in page){ Console.WriteLine($"{row["email"]} left on {row["createdAt"]}");}Notes
Needs
settings:read, the scope the Blocked addresses screen in Settings is gated on.The cursor is opaque and holds where the last row sat. A cursor this list did not hand out is a 400
invalid_cursor.
Also available in
Suppressions.AddUnsubscribeAsync
Record that somebody unsubscribed
Task<JsonObject> AddUnsubscribeAsync( IReadOnlyDictionary<string, object?> body, string? apiKey = null, CancellationToken cancellationToken = default)Records that somebody asked to stop getting marketing mail, for when they asked by phone, in a reply or anywhere else, with source set to manual. Their contact, if there is one, is unsubscribed from every audience at once, the automations sending to them end, and contact.unsubscribed fires. No broadcast or automation email goes to the address from then on, while ordinary mail and replies still do.
Recording an address that is already on the list changes nothing: the server answers 200 with the record it holds, where a new one answers 201.
Parameters
emailstringRequiredThe address that asked for no more marketing mail. It is trimmed and lower cased.
apiKeystring?Overrides the client API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A JsonObject for the address, new or already there, with the fields ListUnsubscribesAsync returns.
Example
var row = await client.Suppressions.AddUnsubscribeAsync(new Body { ["email"] = "[email protected]" }); Console.WriteLine($"{row["source"]} {row["removable"]}");Notes
Safe to repeat: a second call finds the first record, so the SDK retries it after a network failure.
A key limited to particular addresses or domains is refused with 422
capability_unsupported, because the list covers every address in the workspace. So is an app connected by anybody but the owner.
Also available in
Suppressions.RemoveUnsubscribeAsync
Take back an unsubscribe the team recorded
Task<JsonObject> RemoveUnsubscribeAsync( string email, string? apiKey = null, CancellationToken cancellationToken = default)Takes back an unsubscribe the team recorded by hand, for one recorded by mistake. The audiences it unsubscribed are subscribed again, and contact.resubscribed fires.
Every other kind is refused with 409 unsubscribe_not_removable, because a person who unsubscribed decides alone whether to come back: through a sign-up form they confirm from their inbox, or Subscribe again on the unsubscribe page. An address that has not unsubscribed is a 404.
Parameters
emailstringRequiredThe address, as
ListUnsubscribesAsyncreturns it. Case does not matter.apiKeystring?Overrides the client API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A JsonObject with object set to unsubscribe, the email, and deleted set to true.
Example
try{ await client.Suppressions.RemoveUnsubscribeAsync("[email protected]");}catch (NextmailApiException error) when (error.IsConflict){ Console.WriteLine("Only the person can subscribe again");}Notes
The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
A key limited to particular addresses or domains is refused with 422
capability_unsupported.
Also available in
- API
DELETE /suppressions/unsubscribes/{email}- TypeScript
nextmail.suppressions.removeUnsubscribe()- Python
suppressions.remove_unsubscribe()- Ruby
suppressions.remove_unsubscribe- PHP
suppressions->removeUnsubscribe- Go
Suppressions.RemoveUnsubscribe- Java
suppressions().removeUnsubscribe- CLI
openemail suppressions remove-unsubscribe