API · Emails

Share Email

Create a public link for a sent or received email. Defaults to 48 hours; longer or invalid durations return 422.

POST/emails/{email_id}/shareFull access

Request parameters

Parameter	Type	Description
`email_id` path · required	`string`	Opaque resource id.
`Idempotency-Key` header · optional	`string` 1–256 characters	Makes the request safe to retry. See Idempotency.
`expires_in` body · optional	`string` Default: 48h	A positive duration such as 10m, 2 hours, or 1 day; maximum 48 hours.

Request example

Set OPENSEND_BASE_URL=https://api.example.com and OPENSEND_API_KEY=os_replace_me on your server.

bash

curl -X POST "$OPENSEND_BASE_URL/emails/YOUR_email_id/share" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"expires_in":"2 hours"}'

Response

200 · application/json. Example IDs stand for IDs returned by your installation.

json

{
  "object": "email",
  "id": "YOUR_ID",
  "url": "https://api.example.com/example"
}

Behavior and errors

email_id accepts a sent email ID or a received email ID from your team. The returned url opens a public page on your installation (/shared?token=…) that needs no account and is not indexed. It shows the subject, From, To, Cc, Reply-To, date, body, and attachment names, types, and sizes. It never shows Bcc, other headers, raw MIME, download links, events, or internal IDs.

expires_in accepts durations such as 10m, 2 hours, or 1 day. The default and the maximum are 48 hours; a zero, negative, invalid, or longer duration returns 422 validation_error. A link stops working at expiry, or earlier when the email expires from retention or the team is deleted. Creating another link does not revoke earlier ones. The same link is available from Share email in the dashboard’s email detail menu.

The SDK option is expiresIn; the wire field is expires_in. Replaying the request with the same Idempotency-Key returns the same link without extending its expiry. Only a hash of the link token is stored, and the link is redacted from request logs.

Use a full-access credential; a sending-only key returns 401 restricted_api_key. Unknown or foreign resources return 404. See authentication, errors, rate limits, and pagination.