Skip to content
clearance.rest

Create an authorization link

POST
/emails/auth-links
curl --request POST \
  --url https://api.clearance.rest/emails/auth-links \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "expires_in": 604800, "max_uses": 1, "providers": [ "gmail" ], "locale": "en", "return_url": "example", "metadata": { "additionalProperty": "example" }, "branding": { "name": "example", "logo_url": "example", "description": "example", "primary_color": "example" } }'

A public, expiring link that lets anyone connect a Gmail or Outlook mailbox to the project without an account. Share url. metadata is written to the metadata of every connected mailbox and delivered in the email_account.connected event. Free of charge.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Settings of a new authorization link.

object
expires_in

Lifetime in seconds (default 7 days, min 1 hour, max 30 days).

integer
default: 604800 >= 3600 <= 2592000
max_uses

How many mailboxes can be connected with the link; 0 = unlimited.

integer
default: 1 <= 1000000
providers

Providers offered on the link page (default: gmail and outlook).

Array<string>
>= 1 items
Allowed values: gmail outlook
locale

Language of the link page.

string
default: en
Allowed values: en tr
return_url

Where the link page sends the user afterwards; its origin must be in the project’s allowed return origins.

string
<= 2048 characters
metadata

Written to the metadata of every mailbox connected with the link.

object
key
additional properties
branding

Overrides the project’s branding field by field.

object
name
string
>= 1 characters <= 100 characters
logo_url
string
<= 2048 characters
description
string
>= 1 characters <= 500 characters
primary_color
string
/^#[0-9a-fA-F]{6}$/

Responses

Section titled “Responses”

201

Section titled “201”

Default Response

Media typeapplication/json
object
success
required
boolean
id
required
string
url
required

The page to share, e.g. https://links.clearance.rest/.

string
status
required
string
Allowed values: active expired revoked exhausted
expires_at
required

UTC timestamp (ISO 8601).

string
max_uses
required
integer
>= -9007199254740991 <= 9007199254740991
use_count
required
integer
>= -9007199254740991 <= 9007199254740991
providers
required
Array<string>
Allowed values: gmail outlook
locale
required
string
Allowed values: en tr
return_url
required
string | null
branding
required

Branding of the link page (project defaults overridden by the link); null fields use the default look.

object
name
required
string | null
logo_url
required
string | null
description
required
string | null
primary_color
required
string | null
metadata
required

Free-form JSON object (at most 16 KB, 5 levels deep, keys up to 64 characters).

object
key
additional properties
project_id
required
string
created_by
required
string | null
created_at
required

UTC timestamp (ISO 8601).

string
last_used_at
required
Any of:

UTC timestamp (ISO 8601).

string
revoked_at
required
Any of:

UTC timestamp (ISO 8601).

string
Example
{
  "success": true,
  "status": "active",
  "providers": [
    "gmail"
  ],
  "locale": "en"
}

400

Section titled “400”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

401

Section titled “401”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}

403

Section titled “403”

Default Response

Media typeapplication/json

Error envelope returned by every JSON endpoint.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code (snake_case).

string
message
required

Human-readable message.

string
details

Extra context for the error.

object
key
additional properties
Example
{
  "success": false
}