Mail API reference

Mail API · Integrations

post/v1/workspaces/{workspace_id}/integrations/github/connectAuth

Mint a GitHub OAuth state token and return the authorize URL.

The frontend redirects the user to `authorize_url`; GitHub bounces back to the `/callback` endpoint with a `code` + `state` pair. state is single-use, 5-minute TTL.

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

authorize_url*string · uri

Browser redirects here to start the GitHub OAuth flow.

Example: "https://github.com/login/oauth/authorize?client_id=…&state=…&redirect_uri=…"

Example

Request

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

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

Response

{
  "authorize_url": "https://github.com/login/oauth/authorize?client_id=…&state=…&redirect_uri=…"
}