Share Links API and MCP Guide

Share links let you deliver a Drive file outside your TrekMail account without sending a large email attachment. The API and MCP tools can create links, list links for a file, and revoke links when access should end.

Use share links for client deliverables, invoices, video files, export bundles, and any file that is too large or too temporary for an email attachment.

Required scopes

For Account Drive files, use drive:account:share. For mailbox Drive files, use drive:mailbox:share. A read scope is also helpful because most workflows need to find the file before sharing it.

Share scopes do not allow upload, rename, move, trash, restore, or purge. Keep them separate when the agent's only job is delivery.

Create a link with REST

curl -s -X POST "https://trekmail.net/api/v1/drive/files/{FILE_ID}/share-links" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: share-{FILE_ID}-client-a" \
  -d '{"expires_at":"2026-06-01T00:00:00Z","max_downloads":25}'

The response includes the public URL. The raw share token is returned only at creation. If you lose it, revoke the link and create a new one.

Create a link with MCP

drive_share_create(file_id=123, expires_at="2026-06-01T00:00:00Z", max_downloads=25)

Ask the agent to return the URL in its final answer and to note the expiry/download cap.

Listing and revoking links

Use the list endpoint or drive_share_list to see active and historical links for a file. Use revoke when a link was sent to the wrong person, a contract is no longer valid, or a temporary delivery window has closed.

drive_share_revoke(link_id=456)

Revocation is immediate. Create a new link if access should be restored.

Recommended defaults

Unlimited links are convenient, but they are harder to reason about later. If you choose no expiry, add a note in your own system explaining why.

Security behavior

A share link is public to anyone who has the URL. It is protected by an unguessable token, not by a TrekMail login. Do not send public links for files that require named-recipient access unless your organization accepts that model.

The download page does not reveal unnecessary account details. Expired, revoked, or exhausted links fail without exposing private file context.

Audit trail

Share link creation and revocation are audited with the API token identity. If an agent creates links for customers, review the audit log periodically and rotate tokens when team responsibilities change.