/v1/workspaces/{workspace_id}/integrations/github/app/installAuthStart 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 · uuidId of the workspace.
Headers
Idempotency-KeystringOpaque 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*stringURL 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 · uriOpen 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"
}