Mail API reference

Mail API · Integrations

post/v1/workspaces/{workspace_id}/integrations/github/app/installAuth

Start installing the ProductCraft Mail GitHub App for this workspace.

Returns a URL for the browser. The customer installs the App on the repositories they choose (Contents read, Metadata read, Pull requests read, Checks write; nothing else), confirms on GitHub that it is them, and lands back on `return_to` with `integration=github&status=connected` (or `migrated` when the workspace was connected through the older OAuth App: Mail then keeps the repo settings, deletes the old repo webhook and revokes the OAuth token). The state is single-use and expires in 15 minutes. Written to the audit log as `mail.integration.connected`.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.

Request body

return_to*string

URL the workspace user should land on after the GitHub OAuth flow completes. Must be a same-origin or productcraft.co URL — anything else is rejected to keep the callback from being an open-redirect.

Example: "https://console.productcraft.co/mail/workspaces/acme/integrations"

Response · 200

install_url*string · uri

Open this URL in the browser (a top-level navigation, not a fetch). It leads to the App's install page on GitHub, where the customer picks the account and the repositories; GitHub then brings them back to `return_to`.

Example

Request

POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/integrations/github/app/install
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "return_to": "https://console.productcraft.co/mail/workspaces/acme/integrations"
}

Response

{
  "install_url": "string"
}