# Share a file

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

Make a link to one of your files, 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-file

Every share is a link. Leave out `shared_with` for a public link that anyone who has it can open, to pass on yourself. Name a person and the link opens only for them, signed in as that address (and for you); it also shows in their list of shares, and they are emailed the link. `notice` says plainly what happened, including when no email went out.

## Parameters

| Name | In | Required | What it is | Example |
|---|---|---|---|---|
| `id` | path | yes | The file's id. | `42` |
| `shared_with` | query | no | The address of the person to share with. Leave it out for a public link. | `friend@example.com` |
| `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. |  |

## Good to know

- Sharing with an address that has no account still makes the share, but sends no email (emailed is false), and the link opens only once someone signs in as that address. For anyone without an account, make a public link.
- You can't share with yourself (400). A file that isn't yours, or is in Trash, answers 404.
- While the file is in Trash its link stops working, and deleting it for good ends the share.

## Examples

cURL:

```bash
curl -s -X POST 'https://api.mailmasker.org/api/v1/drive/files/42/share?shared_with=friend%40example.com' \
  -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/files/42/share',
    { Authorization => "Bearer $ENV{TOKEN}" },
    form => { shared_with => 'friend@example.com' })->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": 15,
  "token": "5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e",
  "url": "https://drive.example.com/s/5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e",
  "target": "file",
  "label": "notes.txt",
  "shared_with": "friend@example.com",
  "public": false,
  "emailed": true,
  "notice": "Shared with friend@example.com and emailed them the link."
}
```