nextmail.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.list()
List one page of the public links of the workspace
list(options?: ShareLinkListOptions): Promise<Page<ShareLinkResource>>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: options.limit takes 1 to 100 and defaults to 50, and nextCursor goes back as options.cursor while hasMore is true. listAll and iterate do that walk for you.
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
options.kindShareKindOnly links to this kind of item:
template,formorautomation. Left out, every kind the scopes read.options.limitnumberRows per page, a whole number from 1 to 100. The server defaults to 50.
options.cursorstringThe
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.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
Returns
Page<ShareLinkResource> with items, hasMore and nextCursor. Each item has id, kind, itemId, itemName, token, url, copyable, views, copies, lastViewedAt, lastCopiedAt, createdAt and updatedAt.
Example
const page = await nextmail.shareLinks.list({ kind: 'template' }) for (const link of page.items) console.log(link.itemName, link.url, `${link.views} views, ${link.copies} copies`)Notes
A key with none of the three read scopes is refused with 403
insufficient_scope, and so is akindits 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, aslistAllanditeratedo.Read only, so the SDK retries it after a network failure like any other read.
Also available in
shareLinks.listAll()
Collect every public link of the workspace into one array
listAll(options?: ShareLinkListOptions): Promise<Array<ShareLinkResource>>Follows nextCursor from page to page and resolves with 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 list returns. limit sets the page size of each request, not the total.
Parameters
options.kindShareKindOnly links to this kind of item:
template,formorautomation. Left out, every kind the scopes read.options.limitnumberPage size per request, from 1 to 100, defaulting to 50 on the server.
options.cursorstringA
nextCursorfrom an earlier page to start after.options.signalAbortSignalCancels the request in flight and rejects the whole walk.
options.apiKeystringOverrides the client's API key for every page of this walk.
Returns
Array<ShareLinkResource> holding every public link across all pages.
Example
const links = await nextmail.shareLinks.listAll() const unseen = links.filter((link) => link.views === 0) for (const link of unseen) console.log(link.kind, link.itemName, link.url)Notes
A failure on any page rejects the whole call, and that includes a 400
invalid_cursorwhen the last link of the page before was made private in between. Start the walk again then.
Also available in
shareLinks.iterate()
Stream the public links of the workspace one at a time
iterate(options?: ShareLinkListOptions): AsyncGenerator<ShareLinkResource, void, undefined>Returns an async generator that yields public links one by one, the newest link first, and requests the next page only once the current one is drained. Breaking out of the loop stops the requests.
Parameters
options.kindShareKindOnly links to this kind of item:
template,formorautomation. Left out, every kind the scopes read.options.limitnumberPage size per request, from 1 to 100, defaulting to 50 on the server.
options.cursorstringA
nextCursorfrom an earlier page to start after.options.signalAbortSignalCancels the request in flight and rejects the whole walk.
options.apiKeystringOverrides the client's API key for every page of this walk.
Returns
AsyncGenerator<ShareLinkResource, void, undefined> yielding one link per step.
Example
for await (const link of nextmail.shareLinks.iterate({ kind: 'form' })) { if (link.copyable) console.log('copyable:', link.itemName, link.copies)}Notes
The generator is lazy, so an abandoned loop costs only the pages you consumed.
Also available in
shareLinks.get()
Read the public link of a template, form or automation
get(kind: ShareKind, itemId: string, options?: RequestScope): Promise<ShareLinkResource>Resolves with 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.get and shared.copy 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 set makes it public.
Parameters
kindShareKindRequiredWhat the item is:
template,formorautomation.itemIdstringRequiredThe id of the item, as
templates.list,forms.listorautomations.listreturns it: atpl_,frm_oraut_id. A template is named by its id here, never by its slug.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
Returns
ShareLinkResource: { object: 'share_link', id, kind, itemId, itemName, token, url, copyable, views, copies, lastViewedAt, lastCopiedAt, createdAt, 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
const link = await nextmail.shareLinks.get('form', 'frm_8d2f6a1c9b3e47d0a5f1c2e9') console.log(link.url, link.copyable, link.views, link.lastViewedAt)Notes
A private item 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.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.set()
Make a template, form or automation public
set(kind: ShareKind, itemId: string, body?: ShareLinkSet, options?: RequestScope): Promise<ShareLinkResource>Shares one item at a public link, as Share does in the app, and resolves with 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. body.copyable 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
kindShareKindRequiredWhat the item is:
template,formorautomation.itemIdstringRequiredThe id of the item, as
templates.list,forms.listorautomations.listreturns it: atpl_,frm_oraut_id. A template is named by its id here, never by its slug.body.copyablebooleantruelets 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.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
Returns
ShareLinkResource, the link new or as it was, with copyable as it is now: { object: 'share_link', id, kind, itemId, itemName, token, url, copyable, views, copies, lastViewedAt, lastCopiedAt, createdAt, updatedAt }.
Example
const link = await nextmail.shareLinks.set('template', 'tpl_3f9a1c7e5b2d48a6c0e4f1b9', { copyable: false }) console.log(link.url, link.copyable)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.delete()
Make a template, form or automation private
delete(kind: ShareKind, itemId: string, options?: RequestScope): Promise<DeletedShareLinkResource>Takes the public link of one item down, as turning Share off does in the app, and resolves with 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 set 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
kindShareKindRequiredWhat the item is:
template,formorautomation.itemIdstringRequiredThe id of the item, as
templates.list,forms.listorautomations.listreturns it: atpl_,frm_oraut_id. A template is named by its id here, never by its slug.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client's API key for this call only.
Returns
DeletedShareLinkResource, the link as it was with deleted: true: { object: 'share_link', id, kind, itemId, itemName, token, url, copyable, views, copies, lastViewedAt, lastCopiedAt, createdAt, updatedAt, deleted }.
Example
const removed = await nextmail.shareLinks.delete('automation', 'aut_5c1e9a7b3d2f48e6a0b4c7d1') console.log(removed.url, removed.views, removed.deleted)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