---
title: "client.shareLinks()"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://nextmail.sh/docs/java/reference/share-links"
area: "Java"
category: "Reference"
---

# 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

```java
Page list(RequestOptions options)
```

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. `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. `RequestOptions.of("kind", ShareKinds.FORM)` lists one kind only. An app a member connected lists the templates of the workspace and the forms and automations that member made.

Scopes: `templates:read`.

**Parameters**

- `options.kind` (`String`): Only links to this kind of item: `template`, `form` or `automation`, all three in `sh.nextmail.constants.ShareKinds`. Left out, every kind the scopes read.
- `options.limit` (`int`): Rows per page, a whole number from 1 to 100. The server defaults to 50.
- `options.cursor` (`String`): The `nextCursor` from 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 400 `invalid_cursor`, and so is one whose link was made private since.
- `options.apiKey` (`String`): Overrides the client's API key for this call only.

**Returns**

A `Page` of share link maps, with `items`, `hasMore` and `nextCursor`. Each item has `object` set to `share_link`, `id`, `kind`, `itemId`, `itemName`, `token`, `url`, `copyable`, `views`, `copies`, `lastViewedAt`, `lastCopiedAt`, `createdAt` and `updatedAt`, and its `kind` is one of `sh.nextmail.constants.ShareKinds`.

**Example**

```java
Page page = client.shareLinks().list(RequestOptions.of("kind", ShareKinds.TEMPLATE));

for (Map<String, Object> link : page) {
    System.out.println(link.get("itemName") + " " + link.get("url") + " " + link.get("views") + " views, " + link.get("copies") + " copies");
}

if (page.hasMore()) {
    System.out.println("Next page: " + page.nextCursor());
}
```

**Notes**

- A key with none of the three read scopes is refused with 403 `insufficient_scope`, and so is a `kind` its scopes do not read.
- A page can hold fewer links than `limit`, even none, while `hasMore` is true, because the links an app a member connected may not see are dropped after the page is read. Keep following `nextCursor` until `hasMore` is false, as `listAll` and `iterate` do.
- Read only, so the SDK retries it after a network failure like any other read.

Also available in: API [`GET /share-links`](https://nextmail.sh/docs/api/reference/sharing#get-share-links); TypeScript [`shareLinks.list()`](https://nextmail.sh/docs/sdk/reference/share-links#list); Python [`share_links.list()`](https://nextmail.sh/docs/python/reference/share-links#list); Ruby [`share_links.list`](https://nextmail.sh/docs/ruby/reference/share-links#list); PHP [`shareLinks->list`](https://nextmail.sh/docs/php/reference/share-links#list); Go [`ShareLinks.List`](https://nextmail.sh/docs/go/reference/share-links#list); C# [`ShareLinks.ListAsync`](https://nextmail.sh/docs/csharp/reference/share-links#list); CLI [`nextmail share-links list`](https://nextmail.sh/docs/cli/reference/share-links#share-links-list).

### `shareLinks().listAll`

Collect every public link of the workspace into one list

```java
List<Map<String, Object>> listAll(RequestOptions options)
```

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 `list` returns. `limit` sets the page size of each request, not the total.

Scopes: `templates:read`.

**Parameters**

- `options.kind` (`String`): Only links to this kind of item: `template`, `form` or `automation`, all three in `sh.nextmail.constants.ShareKinds`. Left out, every kind the scopes read.
- `options.limit` (`int`): Page size per request, from 1 to 100, defaulting to 50 on the server.
- `options.cursor` (`String`): A `nextCursor` from an earlier page to start after.
- `options.apiKey` (`String`): Overrides the client's API key for every page of this walk.

**Returns**

A list of share link maps holding every public link across all pages, each shaped like an item of `list`.

**Example**

```java
List<Map<String, Object>> links = client.shareLinks().listAll();

for (Map<String, Object> link : links) {
    if (link.get("views") instanceof Number views && views.longValue() == 0) {
        System.out.println(link.get("kind") + " " + link.get("itemName") + " " + link.get("url"));
    }
}
```

**Notes**

- A failure on any page throws out of the whole call, and that includes a 400 `invalid_cursor` when the last link of the page before was made private in between. Start the walk again then.

Also available in: API [`GET /share-links`](https://nextmail.sh/docs/api/reference/sharing#get-share-links); TypeScript [`shareLinks.listAll()`](https://nextmail.sh/docs/sdk/reference/share-links#listAll); Python [`share_links.list_all()`](https://nextmail.sh/docs/python/reference/share-links#listAll); Ruby [`share_links.list_all`](https://nextmail.sh/docs/ruby/reference/share-links#listAll); PHP [`shareLinks->listAll`](https://nextmail.sh/docs/php/reference/share-links#listAll); Go [`ShareLinks.ListAll`](https://nextmail.sh/docs/go/reference/share-links#listAll); C# [`ShareLinks.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/share-links#listAll).

### `shareLinks().iterate`

Stream the public links of the workspace one at a time

```java
PagedIterable iterate(RequestOptions options)
```

Returns a `PagedIterable` that yields public links one by one, 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 `for` stops the requests.

Scopes: `templates:read`.

**Parameters**

- `options.kind` (`String`): Only links to this kind of item: `template`, `form` or `automation`, all three in `sh.nextmail.constants.ShareKinds`. Left out, every kind the scopes read.
- `options.limit` (`int`): Page size per request, from 1 to 100, defaulting to 50 on the server.
- `options.cursor` (`String`): A `nextCursor` from an earlier page to start after.
- `options.apiKey` (`String`): Overrides the client's API key for every page of this walk.

**Returns**

A `PagedIterable` that yields one share link map per step.

**Example**

```java
for (Map<String, Object> link : client.shareLinks().iterate(RequestOptions.of("kind", ShareKinds.FORM))) {
    if (Boolean.TRUE.equals(link.get("copyable"))) {
        System.out.println("copyable: " + link.get("itemName") + " " + link.get("copies"));
    }
}
```

**Notes**

- The `PagedIterable` is lazy, so an abandoned loop costs only the pages you consumed.

Also available in: API [`GET /share-links`](https://nextmail.sh/docs/api/reference/sharing#get-share-links); TypeScript [`shareLinks.iterate()`](https://nextmail.sh/docs/sdk/reference/share-links#iterate); Python [`share_links.iterate()`](https://nextmail.sh/docs/python/reference/share-links#iterate); Ruby [`share_links.iterate`](https://nextmail.sh/docs/ruby/reference/share-links#iterate); PHP [`shareLinks->iterate`](https://nextmail.sh/docs/php/reference/share-links#iterate); Go [`ShareLinks.Iterate`](https://nextmail.sh/docs/go/reference/share-links#iterate); C# [`ShareLinks.IterateAsync`](https://nextmail.sh/docs/csharp/reference/share-links#iterate).

### `shareLinks().get`

Read the public link of a template, form or automation

```java
Map<String, Object> get(String kind, String itemId, RequestOptions options)
```

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().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.

Scopes: `templates:read`.

**Parameters**

- `kind` (`String`, required): What the item is: `template`, `form` or `automation`, all three in `sh.nextmail.constants.ShareKinds`.
- `itemId` (`String`, required): The id of the item, as `templates().list`, `forms().list` or `automations().list` returns it: a `tpl_`, `frm_` or `aut_` id. A template is named by its id here, never by its slug.
- `options.apiKey` (`String`): Overrides the client's API key for this call only.

**Returns**

A map 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**

```java
Map<String, Object> link = client.shareLinks().get(ShareKinds.FORM, "frm_8d2f6a1c9b3e47d0a5f1c2e9");

System.out.println(link.get("url") + " " + link.get("copyable") + " " + link.get("views") + " " + link.get("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 404 `resource_not_found`.
- A key without the read scope of `kind` is refused with 403 `insufficient_scope`, and a `kind` other than the three is a 422 `invalid_parameter`.
- Read only, so the SDK retries it after a network failure like any other read.

Also available in: API [`GET /share-links/{kind}/{itemId}`](https://nextmail.sh/docs/api/reference/sharing#get-share-links-kind-itemid); TypeScript [`shareLinks.get()`](https://nextmail.sh/docs/sdk/reference/share-links#get); Python [`share_links.get()`](https://nextmail.sh/docs/python/reference/share-links#get); Ruby [`share_links.get`](https://nextmail.sh/docs/ruby/reference/share-links#get); PHP [`shareLinks->get`](https://nextmail.sh/docs/php/reference/share-links#get); Go [`ShareLinks.Get`](https://nextmail.sh/docs/go/reference/share-links#get); C# [`ShareLinks.GetAsync`](https://nextmail.sh/docs/csharp/reference/share-links#get); CLI [`nextmail share-links get`](https://nextmail.sh/docs/cli/reference/share-links#share-links-get).

### `shareLinks().set`

Make a template, form or automation public

```java
Map<String, Object> set(String kind, String itemId, Map<String, Object> body, RequestOptions options)
```

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, as in `Body.of("copyable", false)`, 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.

Scopes: `templates:write`.

**Parameters**

- `kind` (`String`, required): What the item is: `template`, `form` or `automation`, all three in `sh.nextmail.constants.ShareKinds`.
- `itemId` (`String`, required): The id of the item, as `templates().list`, `forms().list` or `automations().list` returns it: a `tpl_`, `frm_` or `aut_` id. A template is named by its id here, never by its slug.
- `body.copyable` (`boolean`): `true` lets anyone signed in copy the item into their own workspace from the page, and `false` lets people only look at it. Left out, a new link is copyable and a link that already exists keeps what it had.
- `options.apiKey` (`String`): Overrides the client's API key for this call only.

**Returns**

A map for the link, new or as it was, with `copyable` as it is now: `object` set to `share_link`, `id`, `kind`, `itemId`, `itemName`, `token`, `url`, `copyable`, `views`, `copies`, `lastViewedAt`, `lastCopiedAt`, `createdAt` and `updatedAt`.

**Example**

```java
Map<String, Object> link = client.shareLinks().set(ShareKinds.TEMPLATE, "tpl_3f9a1c7e5b2d48a6c0e4f1b9", Body.of("copyable", false));

System.out.println(link.get("url") + " " + link.get("copyable"));
```

**Notes**

- Sharing takes the write scope of `kind`: `templates:write`, `forms:write` or `automations:write`. A key without it is refused with 403 `insufficient_scope`.
- An item this workspace does not hold, or one an app a member connected cannot reach, is a 404 `resource_not_found`, and a `kind` other than the three is a 422 `invalid_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: API [`PUT /share-links/{kind}/{itemId}`](https://nextmail.sh/docs/api/reference/sharing#put-share-links-kind-itemid); TypeScript [`shareLinks.set()`](https://nextmail.sh/docs/sdk/reference/share-links#set); Python [`share_links.set()`](https://nextmail.sh/docs/python/reference/share-links#set); Ruby [`share_links.set`](https://nextmail.sh/docs/ruby/reference/share-links#set); PHP [`shareLinks->set`](https://nextmail.sh/docs/php/reference/share-links#set); Go [`ShareLinks.Set`](https://nextmail.sh/docs/go/reference/share-links#set); C# [`ShareLinks.SetAsync`](https://nextmail.sh/docs/csharp/reference/share-links#set); CLI [`nextmail share-links set`](https://nextmail.sh/docs/cli/reference/share-links#share-links-set).

### `shareLinks().delete`

Make a template, form or automation private

```java
Map<String, Object> delete(String kind, String itemId, RequestOptions options)
```

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().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.

Scopes: `templates:write`.

**Parameters**

- `kind` (`String`, required): What the item is: `template`, `form` or `automation`, all three in `sh.nextmail.constants.ShareKinds`.
- `itemId` (`String`, required): The id of the item, as `templates().list`, `forms().list` or `automations().list` returns it: a `tpl_`, `frm_` or `aut_` id. A template is named by its id here, never by its slug.
- `options.apiKey` (`String`): Overrides the client's API key for this call only.

**Returns**

A map for 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**

```java
Map<String, Object> removed = client.shareLinks().delete(ShareKinds.AUTOMATION, "aut_5c1e9a7b3d2f48e6a0b4c7d1");

System.out.println(removed.get("url") + " " + removed.get("views") + " " + removed.get("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 404 `resource_not_found`.
- Taking a link down takes the write scope of `kind`. A key without it is refused with 403 `insufficient_scope`.
- The SDK does not retry a delete. A 404 `share_link_not_found` on your own second attempt after a lost response means the first one worked.

Also available in: API [`DELETE /share-links/{kind}/{itemId}`](https://nextmail.sh/docs/api/reference/sharing#delete-share-links-kind-itemid); TypeScript [`shareLinks.delete()`](https://nextmail.sh/docs/sdk/reference/share-links#delete); Python [`share_links.delete()`](https://nextmail.sh/docs/python/reference/share-links#delete); Ruby [`share_links.delete`](https://nextmail.sh/docs/ruby/reference/share-links#delete); PHP [`shareLinks->delete`](https://nextmail.sh/docs/php/reference/share-links#delete); Go [`ShareLinks.Delete`](https://nextmail.sh/docs/go/reference/share-links#delete); C# [`ShareLinks.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/share-links#delete); CLI [`nextmail share-links delete`](https://nextmail.sh/docs/cli/reference/share-links#share-links-delete).