client.share_links
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.
share_links.list
List one page of the public links of the workspace
list(kind: nil, limit: nil, cursor: nil, api_key: nil) -> Nextmail::PageReturns 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 next_cursor goes back as cursor: while has_more? is true. list_all 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
kindStringOnly links to this kind of item:
template,formorautomation, the values ofNextmail::SHARE_KINDS. Left out, every kind the scopes read.limitIntegerRows per page, a whole number from 1 to 100. The server defaults to 50.
cursorStringThe
next_cursorfrom 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.api_keyStringOverrides the client's API key for this call only.
Returns
The Nextmail::Page with items, has_more? and next_cursor. Each item is a Hash with object set to share_link, id, kind, itemId, itemName, token, url, copyable, views, copies, lastViewedAt, lastCopiedAt, createdAt and updatedAt.
Example
page = client.share_links.list(kind: "template") page.items.each { |link| puts "#{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 akind:its scopes do not read.A page can hold fewer links than
limit:, even none, whilehas_more?is true, because the links an app a member connected may not see are dropped after the page is read. Keep followingnext_cursoruntilhas_more?is false, aslist_allanditeratedo.Read only, so the SDK retries it after a network failure like any other read.
Also available in
share_links.list_all
Collect every public link of the workspace into one array
list_all(kind: nil, limit: nil, cursor: nil, api_key: nil) -> Array<Hash>Follows next_cursor 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 list returns. limit: sets the page size of each request, not the total.
Parameters
kindStringOnly links to this kind of item:
template,formorautomation, the values ofNextmail::SHARE_KINDS. Left out, every kind the scopes read.limitIntegerPage size per request, from 1 to 100, defaulting to 50 on the server.
cursorStringA
next_cursorfrom an earlier page to start after.api_keyStringOverrides the client's API key for every page of this walk.
Returns
An Array of Hashes holding every public link across all pages, each shaped like an item of list.
Example
links = client.share_links.list_all unseen = links.select { |link| link[:views] == 0 } unseen.each { |link| puts "#{link[:kind]} #{link[:itemName]} #{link[:url]}" }Notes
A failure on any page raises, 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
share_links.iterate
Stream the public links of the workspace one at a time
iterate(kind: nil, limit: nil, cursor: nil, api_key: nil, &block) -> Enumerator<Hash>Returns an Enumerator that yields public links one by one, the newest link first, or passes each one to the block you give it. It requests the next page only once the current one is drained, and breaking out of the loop stops the requests.
Parameters
kindStringOnly links to this kind of item:
template,formorautomation, the values ofNextmail::SHARE_KINDS. Left out, every kind the scopes read.limitIntegerPage size per request, from 1 to 100, defaulting to 50 on the server.
cursorStringA
next_cursorfrom an earlier page to start after.api_keyStringOverrides the client's API key for every page of this walk.
Returns
An Enumerator of Hashes, one public link per step, each shaped like an item of list, or yields each one to a block.
Example
client.share_links.iterate(kind: Nextmail::SHARE_KINDS[:FORM]) do |link| puts "copyable: #{link[:itemName]} #{link[:copies]}" if link[:copyable]endNotes
Pages are fetched only as the loop reaches them, so an abandoned loop costs only the pages you consumed.
Also available in
share_links.get
Read the public link of a template, form or automation
get(kind, item_id, api_key: nil) -> HashReturns 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
kindStringRequiredWhat the item is:
template,formorautomation, the values ofNextmail::SHARE_KINDS.item_idStringRequiredThe 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.api_keyStringOverrides the client's API key for this call only.
Returns
A Hash 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 nil until the page is first opened and the item first copied.
Example
link = client.share_links.get("form", "frm_8d2f6a1c9b3e47d0a5f1c2e9") puts 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
share_links.set
Make a template, form or automation public
set(kind, item_id, body = nil, api_key: nil, **fields) -> HashShares 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: changes whether people may copy it, and leaving it out keeps what it was, which is true for a new link, so set(kind, item_id) on its own 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, the values ofNextmail::SHARE_KINDS.item_idStringRequiredThe 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.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.api_keyStringOverrides the client's API key for this call only.
Returns
A Hash for the link, new or as it was, with copyable as it is now. It has object set to share_link, id, kind, itemId, itemName, token, url, copyable, views, copies, lastViewedAt, lastCopiedAt, createdAt and updatedAt.
Example
link = client.share_links.set("template", "tpl_3f9a1c7e5b2d48a6c0e4f1b9", copyable: false) puts 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
share_links.delete
Make a template, form or automation private
delete(kind, item_id, api_key: nil) -> HashTakes 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 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
kindStringRequiredWhat the item is:
template,formorautomation, the values ofNextmail::SHARE_KINDS.item_idStringRequiredThe 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.api_keyStringOverrides the client's API key for this call only.
Returns
A Hash for the link as it was, with deleted set to true. It has object set to share_link, id, kind, itemId, itemName, token, url, copyable, views, copies, lastViewedAt, lastCopiedAt, createdAt, updatedAt and deleted.
Example
removed = client.share_links.delete("automation", "aut_5c1e9a7b3d2f48e6a0b4c7d1") puts 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