{"openapi":"3.1.0","info":{"title":"MailReveal API","version":"0.4.0","description":"Single-workspace email tracking, Gmail sending/drafts, and activity. Image loads do not prove reading. SMTP/Gmail sending submits an existing prepared message once."},"servers":[{"url":"https://mailreveal.com/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Scoped MailReveal API key or workspace owner token."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"SignatureInput":{"type":"object","required":["label","name","email"],"properties":{"label":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string","minLength":1,"maxLength":100},"title":{"type":"string","maxLength":150},"email":{"type":"string","format":"email"},"website":{"type":"string","format":"uri","description":"HTTPS only"}}},"Signature":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"email":{"type":"string"},"website":{"type":["string","null"]},"paused":{"type":"integer","enum":[0,1]},"signal_count":{"type":"integer"},"last_event_at":{"type":["string","null"]},"pixelUrl":{"type":"string","format":"uri"},"html":{"type":"string"},"trackingMode":{"const":"aggregate"},"limitation":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/Signal"}}}},"AgentRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"claim_token":{"type":"string","description":"Private. Keep until approval; never share with owner."},"code":{"type":"string"},"status":{"const":"pending"},"expires_at":{"type":"string","format":"date-time"},"approval_url":{"type":"string","format":"uri"},"claim_url":{"type":"string","format":"uri"},"poll_interval_seconds":{"const":5}}},"AgentClaim":{"type":"object","properties":{"status":{"enum":["pending","denied","claimed"]},"poll_interval_seconds":{"type":"integer"},"key":{"type":"object","description":"Returned once after owner approval.","properties":{"id":{"type":"string"},"name":{"type":"string"},"token":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}},"base_url":{"type":"string","format":"uri"},"mcp_url":{"type":"string","format":"uri"}}},"Message":{"type":"object","required":["id","recipient","subject","body","status","created_at","signal_count"],"properties":{"id":{"type":"string","format":"uuid"},"token":{"type":"string"},"recipient":{"type":"string","format":"email"},"subject":{"type":"string"},"body":{"type":"string"},"status":{"enum":["prepared","sending","sent","send_unknown","draft_creating","draft","draft_unknown"]},"created_at":{"type":"string","format":"date-time"},"sent_at":{"type":["string","null"]},"provider_id":{"type":["string","null"]},"last_event_at":{"type":["string","null"]},"signal_count":{"type":"integer"},"gmail_draft_id":{"type":["string","null"]},"gmail_account":{"type":["string","null"]},"gmail_thread_id":{"type":["string","null"]}}},"MessageInput":{"type":"object","required":["recipient","subject","body"],"properties":{"recipient":{"type":"string","format":"email","maxLength":254},"subject":{"type":"string","minLength":1,"maxLength":300},"body":{"type":"string","minLength":1,"maxLength":40000}}},"MessageDetail":{"allOf":[{"$ref":"#/components/schemas/Message"},{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Signal"}},"pixelUrl":{"type":"string","format":"uri"},"html":{"type":"string"},"signatureHtml":{"type":"string"}}}]},"Signal":{"type":"object","required":["id","message_id","occurred_at","kind","source","confidence"],"properties":{"id":{"type":"string","format":"uuid"},"message_id":{"type":["string","null"],"format":"uuid"},"signature_id":{"type":["string","null"],"format":"uuid"},"occurred_at":{"type":"string","format":"date-time"},"kind":{"enum":["email.image_loaded","signature.image_loaded"]},"source":{"type":"string"},"confidence":{"enum":["unknown","proxy","automated"]}}},"GmailStatus":{"type":"object","properties":{"configured":{"type":"boolean"},"connected":{"type":"boolean"},"email":{"type":["string","null"]},"redirectUri":{"type":"string","format":"uri"},"lastSyncAt":{"type":"string"},"lastError":{"type":"string"}}},"SyncResult":{"type":"object","properties":{"matched":{"type":"integer"},"scanned":{"type":"integer"},"truncated":{"type":"boolean"},"windowDays":{"const":30}}},"DraftResult":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/MessageDetail"},"draft":{"type":"object","properties":{"id":{"type":"string"},"alreadyCreated":{"type":"boolean"}}},"gmailUrl":{"type":"string","format":"uri"}}}}},"paths":{"/agent-requests":{"post":{"summary":"Request owner-approved agent access; no permissions until approved","description":"API key scope: public. Workspace owner tokens also work.","responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRequest"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"At most 20 requests per ten minutes per workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","purpose"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"purpose":{"type":"string","minLength":3,"maxLength":500}}}}}},"security":[]}},"/agent-requests/{id}/claim":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Claim a key once after owner approval","description":"API key scope: private claim token. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentClaim"}}}},"404":{"description":"Unknown request or wrong token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Request expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claim_token"],"properties":{"claim_token":{"type":"string"}}}}}},"security":[]}},"/signatures":{"get":{"summary":"List reusable aggregate signature profiles","description":"API key scope: signatures:read. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Signature"}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a reusable HTML signature; no recipient or message attribution","description":"API key scope: signatures:write. Workspace owner tokens also work.","responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signature"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignatureInput"}}}}}},"/signatures/{id}/export":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Download reusable signature HTML","description":"Requires signatures:read or owner credentials.","responses":{"200":{"description":"HTML attachment","headers":{"Content-Disposition":{"schema":{"type":"string"}}},"content":{"text/html":{"schema":{"type":"string"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/signatures/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Read signature HTML and latest 100 aggregate signals","description":"API key scope: signatures:read. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signature"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Pause or resume future signature recording","description":"API key scope: signatures:write. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signature"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["paused"],"properties":{"paused":{"type":"boolean"}}}}}}}},"/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"summary":"Remove a webhook and its delivery records","description":"Requires webhooks:write. Other webhooks are unaffected.","responses":{"204":{"description":"Webhook removed"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/capabilities":{"get":{"summary":"Inspect current credentials’ scopes","description":"API key scope: any valid key. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"scopes":{"type":"array","items":{"type":"string"}},"owner":{"type":"boolean"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages":{"get":{"summary":"List tracked emails","description":"API key scope: messages:read. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"search","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]},"post":{"summary":"Prepare unique tracking HTML; does not send","description":"API key scope: messages:write. Workspace owner tokens also work.","responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetail"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageInput"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":1,"maxLength":128}}]}},"/messages/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get full email activity history","description":"API key scope: messages:read. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetail"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/{id}/send":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Submit a prepared email once","description":"API key scope: email:send. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetail"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"enum":["auto","gmail","smtp"],"default":"auto"}}}}}}}},"/messages/{id}/draft":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Save a tracked Gmail draft; does not send","description":"API key scope: gmail:draft. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftResult"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/addon/track":{"post":{"summary":"Prepare a Gmail add-on tracker","description":"API key scope: messages:write. Workspace owner tokens also work.","responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetail"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipient","subject"],"properties":{"recipient":{"type":"string","format":"email","maxLength":254},"subject":{"type":"string","minLength":1,"maxLength":300},"body":{"type":"string","minLength":1,"maxLength":40000}}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":1,"maxLength":128}}]}},"/events":{"get":{"summary":"Read latest 100 signals or full per-message history","description":"API key scope: events:read. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Signal"}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"message_id","in":"query","schema":{"type":"string","format":"uuid"}}]}},"/gmail/status":{"get":{"summary":"Read Gmail status without secrets","description":"API key scope: messages:read. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GmailStatus"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/gmail/sync":{"post":{"summary":"Reconcile recent tracked sent emails","description":"API key scope: gmail:sync. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncResult"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/connection-status":{"get":{"summary":"Read provider status","description":"API key scope: messages:read. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"gmail":{"$ref":"#/components/schemas/GmailStatus"},"smtpConfigured":{"type":"boolean"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"post":{"summary":"Create a webhook on an operator-approved HTTPS host; secret shown once","description":"API key scope: webhooks:write. Workspace owner tokens also work.","responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"secret":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}}},"get":{"summary":"List webhook endpoints without secrets","description":"API key scope: webhooks:read. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"created_at":{"type":"string"}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deliveries":{"get":{"summary":"Read latest 100 webhook outcomes","description":"API key scope: webhooks:read. Workspace owner tokens also work.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event_id":{"type":"string"},"status":{"enum":["pending","delivered","failed"]},"attempts":{"type":"integer"},"last_status":{"type":["integer","null"]},"url":{"type":"string","format":"uri"}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provider request failed or outcome unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}