$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->list
List one page of the public links of the workspace
list(?string $kind = null, ?int $limit = null, ?string $cursor = null, ?string $apiKey = null): 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 nextCursor goes back as cursor: while hasMore is true. shareLinks->listAll and shareLinks->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, as inNextmail\Constants\ShareKinds. Left out, every kind the scopes read.limitintRows per page, a whole number from 1 to 100. The server defaults to 50.
cursorstringThe
nextCursorof 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.apiKeystringOverrides the client's API key for this call only.
Returns
A Page of share link arrays, with items, hasMore and nextCursor. Each item has id, kind, itemId, itemName, token, url, copyable, views, copies, lastViewedAt, lastCopiedAt, createdAt and updatedAt.
Example
use Nextmail\Constants\ShareKinds; $page = $client->shareLinks->list(kind: ShareKinds::TEMPLATE); foreach ($page as $link) { echo $link['itemName'], ' ', $link['url'], ': ', $link['views'], ' views, ', $link['copies'], ' copies', PHP_EOL;} if ($page->hasMore) { $next = $client->shareLinks->list(kind: ShareKinds::TEMPLATE, cursor: $page->nextCursor); echo count($next), ' more', PHP_EOL;}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->listAllandshareLinks->iteratedo.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( ?string $kind = null, ?int $limit = null, ?string $cursor = null, ?string $apiKey = null,): arrayFollows 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->list returns. limit: sets the page size of each request, not the total.
Parameters
kindstringOnly links to this kind of item:
template,formorautomation, as inNextmail\Constants\ShareKinds. Left out, every kind the scopes read.limitintPage size for each request, from 1 to 100. The server defaults to 50.
cursorstringStarts the walk after this cursor instead of the first page.
apiKeystringOverrides the client's API key for every page of this walk.
Returns
A list of share link arrays holding every public link across all pages.
Example
$links = $client->shareLinks->listAll(); $unseen = array_filter($links, static fn(array $link): bool => $link['views'] === 0); foreach ($unseen as $link) { echo $link['kind'], ' ', $link['itemName'], ' has not been opened yet: ', $link['url'], PHP_EOL;}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->iterate
Stream the public links of the workspace one at a time
iterate( ?string $kind = null, ?int $limit = null, ?string $cursor = null, ?string $apiKey = null,): GeneratorReturns a Generator that yields public links one at a time, the newest link first, and requests the next page only once the current one is drained. Nothing is fetched until the loop starts, and breaking out of the foreach stops the requests.
Parameters
kindstringOnly links to this kind of item:
template,formorautomation, as inNextmail\Constants\ShareKinds. Left out, every kind the scopes read.limitintPage size for each request, from 1 to 100. The server defaults to 50.
cursorstringStarts the walk after this cursor instead of the first page.
apiKeystringOverrides the client's API key for every page of this walk.
Returns
A Generator that yields one share link array per step.
Example
use Nextmail\Constants\ShareKinds; foreach ($client->shareLinks->iterate(kind: ShareKinds::FORM) as $link) { if ($link['copyable']) { echo $link['itemName'], ' was copied ', $link['copies'], ' times', PHP_EOL; }}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(string $kind, string $itemId, ?string $apiKey = null): arrayReturns 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 shareLinks->set makes it public.
Parameters
kindstringRequiredWhat the item is:
template,formorautomation, as inNextmail\Constants\ShareKinds.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.apiKeystringOverrides the client's API key for this call only.
Returns
An array 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
use Nextmail\Constants\ShareKinds;use Nextmail\Exception\NotFoundException; try { $link = $client->shareLinks->get(ShareKinds::FORM, 'frm_8d2f6a1c9b3e47d0a5f1c2e9'); echo $link['url'], $link['copyable'] ? ' can be copied' : ' can only be viewed', PHP_EOL; echo $link['views'], ' views, the last at ', $link['lastViewedAt'] ?? 'no time yet', PHP_EOL;} catch (NotFoundException $error) { echo $error->errorCode === 'share_link_not_found' ? 'The form is private' : 'No such form', PHP_EOL;}Notes
A private item throws a
NotFoundExceptionwhoseerrorCodeisshare_link_not_found. An item this workspace does not hold, or one an app a member connected cannot reach, throws one whoseerrorCodeisresource_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(string $kind, string $itemId, ?array $body = null, ?string $apiKey = null): arrayShares 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, as inNextmail\Constants\ShareKinds.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.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.apiKeystringOverrides the client's API key for this call only.
Returns
The same array as shareLinks->get, the link new or as it was, with copyable as it is now.
Example
use Nextmail\Constants\ShareKinds; $link = $client->shareLinks->set(ShareKinds::TEMPLATE, 'tpl_3f9a1c7e5b2d48a6c0e4f1b9'); echo 'Anyone with ', $link['url'], ' can open it', PHP_EOL; $viewOnly = $client->shareLinks->set(ShareKinds::TEMPLATE, 'tpl_3f9a1c7e5b2d48a6c0e4f1b9', ['copyable' => false]); echo $viewOnly['url'], $viewOnly['copyable'] ? ' can be copied' : ' can only be viewed', PHP_EOL;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(string $kind, string $itemId, ?string $apiKey = null): arrayTakes 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->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, as inNextmail\Constants\ShareKinds.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.apiKeystringOverrides the client's API key for this call only.
Returns
An array, the link as it was with deleted set to true: object set to share_link, id, kind, itemId, itemName, token, url, copyable, views, copies, lastViewedAt, lastCopiedAt, createdAt, updatedAt and deleted.
Example
use Nextmail\Constants\ShareKinds; $removed = $client->shareLinks->delete(ShareKinds::AUTOMATION, 'aut_5c1e9a7b3d2f48e6a0b4c7d1'); if ($removed['deleted']) { echo $removed['url'], ' stopped working after ', $removed['views'], ' views and ', $removed['copies'], ' copies', PHP_EOL;}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