# Share a folder

`POST https://api.mailmasker.org/api/v1/drive/folders/:id/share`

Make a link to one of your folders, for one person or for anyone.

- Who can use it: Any signed-in account
- Area: Drive
- Answers 201 Created when it works
- Page: https://developer.mailmasker.org/drive-share-folder

The link opens the whole folder, subfolders included, to browse and download, but nothing outside it. As with a file, a public link opens for anyone who has it, and naming a person in `shared_with` makes it open only for them, signed in, lists it for them and emails them the link.

## Parameters

| Name | In | Required | What it is | Example |
|---|---|---|---|---|
| `id` | path | yes | The folder's id. | `7` |
| `shared_with` | query | no | The address of the person to share with. Leave it out for a public link. |  |
| `expires_days` | query | no | The link stops working after this many days (1 to 9999). Leave it out for a link that lasts until you revoke it. | `7` |

## Good to know

- What you add to the folder later is shared too, and anything inside it you move to Trash drops out of the share.
- You can't share with yourself (400). A folder that isn't yours, or is in Trash, answers 404.

## Examples

cURL:

```bash
curl -s -X POST 'https://api.mailmasker.org/api/v1/drive/folders/7/share?expires_days=7' \
  -H "Authorization: Bearer $TOKEN"
```

Perl:

```perl
use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->post('https://api.mailmasker.org/api/v1/drive/folders/7/share',
    { Authorization => "Bearer $ENV{TOKEN}" },
    form => { expires_days => 7 })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";
```

homelab-cli:

There is no homelab-cli command for this yet.

## Response

201 Created:

```json
{
  "ok": true,
  "id": 16,
  "token": "0ddba11e0ddba11e0ddba11e0ddba11e0ddba11e0ddba11e0ddba11e0ddba11e",
  "url": "https://drive.example.com/s/0ddba11e0ddba11e0ddba11e0ddba11e0ddba11e0ddba11e0ddba11e0ddba11e",
  "target": "folder",
  "label": "Photos",
  "shared_with": null,
  "public": true,
  "notice": "Public link created. Anyone with the link can open it."
}
```