Canary API Docs

# Gmail

These are a collection of endpoints that allow you to insert Canarytoken Mails into every selected G Suite Gmail address in your organisation.

Endpoints
POST /api/v1/canarytoken/gmail/users/list
POST /api/v1/canarytoken/gmail/create
POST /api/v1/canarytoken/gmail/email
GET /api/v1/canarytoken/gmail/email
GET /api/v1/canarytoken/gmail/status

TIP

These endpoints are recommended to be used via your Canary Console UI. The Canary Console UI will handle all the different flows and parameters needed, making your life a lot easier.

# List Gmail email addresses

POST /api/v1/canarytoken/gmail/users/list

Lists the gmail users in the auth'ed G Suite organisation.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id
domain string
The G Suite organisation's domain (eg. thinkstcorp.om)
email string
The G Suite organisation's admin email.

Response

A JSON structure with the users information and a result indicator

# Insert Canarytokens into Gmail accounts

POST /api/v1/canarytoken/gmail/create

Inserts the Gmail Canarytoken into specified Gmail addresses.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Optional Parameters

emails string
A comma separated list of the Gmail addresses to insert the Canarytoken into.
users string
Defaults to: false
JSON encoded string of comma separated array of user objects i.e. [{'email':'jay@thinkst.com', 'name':'jay'}, ..]

Response

A JSON structure with a result indicator

# Get email template for Gmail Canarytoken

GET /api/v1/canarytoken/gmail/email

Gets the Gmail template to be used when tokening Gmail mailboxes.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with the html, sender and subject information with a result indicator

# Save email template for Gmail Canarytoken

POST /api/v1/canarytoken/gmail/email

Saves the Gmail mail template to be used when tokening Gmail mailboxes.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id
email_html string
The HTML of the email template
email_subject string
The subject of the email

Optional Parameters

email_sender string
The from address of the Canarytoken'ed email

Response

A JSON structure with the html, subject, sender information and the used G Suite organisation domain with a result indicator

TIP

We will embed a Canarytoken in the mail template. We will place the Canarytoken'ed URL in the placeholder {url}. We will also check for {user} and replace that with the user's name of each Gmail address.

# Get the status of the Gmail Canarytoken process

GET /api/v1/canarytoken/gmail/status

Gets the status of the Gmail tokening process.

Required Parameters

auth_token string
A valid auth token
flock_id string
A valid flock_id

Response

A JSON structure with a result indicator, successful, failed and total users.

← Google Documents and Sheets →