client.ShareLinks
Every method in this namespace: its signature, its parameters, what it returns and an example.
Methods
Public links to the templates, forms and automations of the workspace, as the Share button makes them in the app: list what the workspace shares, with how often each page was opened and how often the item was copied, read the link of one item, make an item public or change whether people may copy it, and make it private again.
ShareLinks.ListAsync
List one page of the public links of the workspace
Task<Page> ListAsync( string? kind = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns one page of the templates, forms and automations this workspace shares at a public link, the newest link first, with how often each page was opened and how often the item was copied from it. Everything is private until it is shared, so an item that is not in the list has no link. Paging is keyset: limit: takes 1 to 100 and defaults to 50, and nextCursor goes back as cursor: while hasMore is true. ShareLinks.ListAllAsync collects every page and ShareLinks.IterateAsync walks them lazily.
One read scope is enough, and each one reaches its own kind: templates:read lists the templates, forms:read the forms and automations:read the automations, and the kinds a key cannot read are left out. An app a member connected lists the templates of the workspace and the forms and automations that member made.
Parameters
kindstring?Only links to this kind of item:
template,formorautomation, also inNextmail.Constants.ShareKinds. Left out, every kind the scopes read.limitint?Rows per page, a whole number from 1 to 100. The server defaults to 50.
cursorstring?The
nextCursorfrom the previous page, passed back exactly as it came. It names the last link of that page, so one that names no link of this workspace is a 400invalid_cursor, and so is one whose link was made private since.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A Page of link objects, with items, hasMore and nextCursor. Each item has id, kind, itemId, itemName, token, url, copyable, views, copies, lastViewedAt, lastCopiedAt, createdAt and updatedAt.
Example
using Nextmail.Constants; var page = await client.ShareLinks.ListAsync(kind: ShareKinds.Template); foreach (var link in page){ Console.WriteLine($"{link["itemName"]} {link["url"]}: {link["views"]} views, {link["copies"]} copies");} if (page.HasMore){ var next = await client.ShareLinks.ListAsync(kind: ShareKinds.Template, cursor: page.NextCursor); Console.WriteLine($"{next.Count} more");}Notes
A key with none of the three read scopes is refused with 403
insufficient_scope, and so is akind:its scopes do not read.A page can hold fewer links than
limit:, even none, whilehasMoreis true, because the links an app a member connected may not see are dropped after the page is read. Keep followingnextCursoruntilhasMoreis false, asShareLinks.ListAllAsyncandShareLinks.IterateAsyncdo.Read only, so the SDK retries it after a network failure like any other read.
Also available in
- API
GET /share-links- TypeScript
shareLinks.list()- Python
share_links.list()- Ruby
share_links.list- PHP
shareLinks->list- Go
ShareLinks.List- Java
shareLinks().list- CLI
nextmail share-links list
ShareLinks.ListAllAsync
Collect every public link of the workspace into one list
Task<IReadOnlyList<JsonObject>> ListAllAsync( string? kind = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Follows nextCursor from page to page and returns every template, form and automation the workspace shares at a public link, as far as the scopes of the key reach, the newest link first, in the shape ShareLinks.ListAsync returns. One request per page, and limit: sets the page size of each request, not the total.
Parameters
kindstring?Only links to this kind of item:
template,formorautomation, also inNextmail.Constants.ShareKinds. Left out, every kind the scopes read.limitint?Page size for each request, from 1 to 100. The server defaults to 50.
cursorstring?Starts the walk after this cursor, a
nextCursorfrom an earlier page, instead of the first page.apiKeystring?Overrides the client's API key for every page of this walk.
cancellationTokenCancellationTokenCancels the request in flight and the walk with it.
Returns
A list of link objects holding every public link across all pages.
Example
var links = await client.ShareLinks.ListAllAsync(); foreach (var link in links.Where(link => (int?)link["views"] == 0)){ Console.WriteLine($"Nobody opened the {link["kind"]} {link["itemName"]} yet: {link["url"]}");}Notes
If any page fails, the exception is thrown and the links already fetched are discarded. That includes a 400
invalid_cursorwhen the last link of the page before was made private in between, so start the walk again then.
Also available in
ShareLinks.IterateAsync
Stream the public links of the workspace one at a time
IAsyncEnumerable<JsonObject> IterateAsync( string? kind = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default)Returns an IAsyncEnumerable<JsonObject> that yields public links one at a time, the newest link 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.
Parameters
kindstring?Only links to this kind of item:
template,formorautomation, also inNextmail.Constants.ShareKinds. Left out, every kind the scopes read.limitint?Page size for each request, from 1 to 100. The server defaults to 50.
cursorstring?Starts the walk after this cursor, a
nextCursorfrom an earlier page, instead of the first page.apiKeystring?Overrides the client's API key for every page of this walk.
cancellationTokenCancellationTokenCancels the request in flight and the walk with it.
Returns
An IAsyncEnumerable<JsonObject> that yields one link per step.
Example
using Nextmail.Constants; await foreach (var link in client.ShareLinks.IterateAsync(kind: ShareKinds.Form)){ if ((bool?)link["copyable"] == true) { Console.WriteLine($"{link["itemName"]} can be copied, and was {link["copies"]} times"); }}Notes
The walk is lazy, so an abandoned loop costs only the pages you consumed.
Also available in
ShareLinks.GetAsync
Read the public link of a template, form or automation
Task<JsonObject> GetAsync( string kind, string itemId, string? apiKey = null, CancellationToken cancellationToken = default)Returns the public link of one item, with how often its page was opened and how often the item was copied from it. url is the page anyone with the link can open without an account, and token, its last part, is what Shared.GetAsync and Shared.CopyAsync take.
Reading it takes the read scope of its kind: templates:read, forms:read or automations:read. A private item has no link, so it answers 404 share_link_not_found, and ShareLinks.SetAsync makes it public.
Parameters
kindstringRequiredWhat the item is:
template,formorautomation, also inNextmail.Constants.ShareKinds.itemIdstringRequiredThe id of the item, as
Templates.ListAsync,Forms.ListAsyncorAutomations.ListAsyncreturns it: atpl_,frm_oraut_id. A template is named by its id here, never by its slug.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A JsonObject with object set to share_link, id, kind, itemId, itemName, token, url, copyable, views, copies, lastViewedAt, lastCopiedAt, createdAt and updatedAt. itemName is the name the item has now, and lastViewedAt and lastCopiedAt are null until the page is first opened and the item first copied.
Example
using Nextmail.Constants; try{ var link = await client.ShareLinks.GetAsync(ShareKinds.Form, "frm_8d2f6a1c9b3e47d0a5f1c2e9"); Console.WriteLine($"{link["url"]}: {link["views"]} views, last opened {link["lastViewedAt"]?.ToString() ?? "never"}");}catch (NextmailApiException error) when (error.Code == "share_link_not_found"){ Console.WriteLine("The form is private, so it has no link");}Notes
A private item is a 404
share_link_not_found, and an item this workspace does not hold, or one an app a member connected cannot reach, is a 404resource_not_found. Both throwNextmailApiExceptionwithIsNotFoundtrue, andCodetells them apart.A key without the read scope of
kindis refused with 403insufficient_scope, and akindother than the three is a 422invalid_parameter.Read only, so the SDK retries it after a network failure like any other read.
Also available in
ShareLinks.SetAsync
Make a template, form or automation public
Task<JsonObject> SetAsync( string kind, string itemId, IReadOnlyDictionary<string, object?>? body = null, string? apiKey = null, CancellationToken cancellationToken = default)Shares one item at a public link, as Share does in the app, and returns the link. Anyone holding url can open the page without an account and try the item there: fill in the props of a template, type into a form or follow an automation step by step. With copyable on, anyone signed in can also copy it into their own workspace.
An item that is already public keeps its link and its counts, so the call is safe to repeat. copyable in the body changes whether people may copy it, and leaving it out keeps what it was, which is true for a new link, so a call with no body shares an item with the defaults.
The page shows what is live: the published version of a template, the published design of a form and the published flow of an automation, or the draft while nothing was published. A copy carries the design only, never the submissions, sends, runs or contacts the original collected, and never the audiences, addresses, forms or webhook endpoints it points at, which stay with you.
Parameters
kindstringRequiredWhat the item is:
template,formorautomation, also inNextmail.Constants.ShareKinds.itemIdstringRequiredThe id of the item, as
Templates.ListAsync,Forms.ListAsyncorAutomations.ListAsyncreturns it: atpl_,frm_oraut_id. A template is named by its id here, never by its slug.copyablebooltruelets anyone signed in copy the item into their own workspace from the page, andfalselets people only look at it. Left out, a new link is copyable and a link that already exists keeps what it had.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A JsonObject for the link, new or as it was, with copyable as it is now, in the shape ShareLinks.GetAsync returns.
Example
using Nextmail.Constants; var link = await client.ShareLinks.SetAsync(ShareKinds.Template, "tpl_3f9a1c7e5b2d48a6c0e4f1b9", new Body { ["copyable"] = false }); Console.WriteLine($"{link["url"]} {((bool?)link["copyable"] == true ? "can be copied" : "can only be looked at")}");Notes
Sharing takes the write scope of
kind:templates:write,forms:writeorautomations:write. A key without it is refused with 403insufficient_scope.An item this workspace does not hold, or one an app a member connected cannot reach, is a 404
resource_not_found, and akindother than the three is a 422invalid_parameter.The SDK retries this call after a network failure, which is safe because an item keeps one link however often it is shared.
Also available in
ShareLinks.DeleteAsync
Make a template, form or automation private
Task<JsonObject> DeleteAsync( string kind, string itemId, string? apiKey = null, CancellationToken cancellationToken = default)Takes the public link of one item down, as turning Share off does in the app, and returns the link that stopped working. The page stops working at once for everyone who has the link, and the copies already made stay in the workspaces that made them.
Making the item public again with ShareLinks.SetAsync gives it a new link with its counts at zero, so the old url never works again. Deleting the template, form or automation itself takes its link down too.
Parameters
kindstringRequiredWhat the item is:
template,formorautomation, also inNextmail.Constants.ShareKinds.itemIdstringRequiredThe id of the item, as
Templates.ListAsync,Forms.ListAsyncorAutomations.ListAsyncreturns it: atpl_,frm_oraut_id. A template is named by its id here, never by its slug.apiKeystring?Overrides the client's API key for this call only.
cancellationTokenCancellationTokenCancels the request.
Returns
A JsonObject for the link as it was, in the shape ShareLinks.GetAsync returns, with deleted set to true.
Example
using Nextmail.Constants; var removed = await client.ShareLinks.DeleteAsync(ShareKinds.Automation, "aut_5c1e9a7b3d2f48e6a0b4c7d1"); if ((bool?)removed["deleted"] == true){ Console.WriteLine($"{removed["url"]} stopped working after {removed["views"]} views");}Notes
An item that is already private is a 404
share_link_not_found. An item this workspace does not hold, or one an app a member connected cannot reach, is a 404resource_not_found.Taking a link down takes the write scope of
kind. A key without it is refused with 403insufficient_scope.The SDK does not retry a delete. A 404
share_link_not_foundon your own second attempt after a lost response means the first one worked.
Google Workspace