{"openapi":"3.1.0","info":{"title":"Relay API","version":"1.0.0","description":"App send uses Bearer keys (`POST /v1/messages`). Console resources (apps, mailbox, campaigns, people lists, automations, tags, team, templates, status updates) use the operator session cookie. OpenAPI here is the source for Scalar, Swagger UI, and later SDKs."},"servers":[{"url":"http://localhost:3010","description":"Local Relay"},{"url":"https://relay.example","description":"Example production host"}],"tags":[{"name":"Discovery"},{"name":"Messages"},{"name":"Apps"},{"name":"Mailbox"},{"name":"Campaigns"},{"name":"People"},{"name":"Automations"},{"name":"Tags"},{"name":"Team"},{"name":"Templates"},{"name":"Status updates"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"App API key. Copied once when the app is created."},"cookieAuth":{"type":"apiKey","in":"cookie","name":"better-auth.session_token","description":"Operator console session. Sign in at /login, then call from the same browser or with the cookie."}},"schemas":{"Problem":{"type":"object","required":["title","status"],"properties":{"title":{"type":"string"},"status":{"type":"integer"}}},"Accepted":{"type":"object","required":["accepted"],"properties":{"accepted":{"type":"boolean","enum":[true]}}},"MessageTo":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}},"CreateMessage":{"type":"object","required":["title","body","to"],"properties":{"title":{"type":"string","minLength":1},"body":{"type":"string","minLength":1},"to":{"$ref":"#/components/schemas/MessageTo"},"event":{"type":"string"},"kind":{"type":"string","enum":["transactional","marketing"]},"channels":{"type":"array","items":{"type":"string","enum":["email","in_app","sms","whatsapp"]}},"href":{"type":"string"},"vars":{"type":"object","additionalProperties":true},"idempotencyKey":{"type":"string"},"sendAt":{"type":"integer","description":"Unix ms"}}},"PublicId":{"type":"object","properties":{"publicId":{"type":"string"}}}}},"paths":{"/v1":{"get":{"operationId":"listPublicApi","summary":"List docs URLs and operations","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/openapi.json":{"get":{"operationId":"getOpenApi","summary":"OpenAPI 3.1 document","tags":["Discovery"],"security":[],"responses":{"200":{"description":"OpenAPI","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/messages":{"post":{"operationId":"createMessage","summary":"Queue a notification","tags":["Messages"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMessage"},"example":{"event":"order.paid","title":"Order paid","body":"Thanks — we have your order.","to":{"email":"ops@example.com"},"channels":["email"]}}}},"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unknown key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Channel not on this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Monthly limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/notifications/apps":{"get":{"operationId":"listApps","summary":"List apps","tags":["Apps"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Apps","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}}}},"post":{"operationId":"createApp","summary":"Create an app and return its API secret once","tags":["Apps"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","slug"],"properties":{"name":{"type":"string"},"slug":{"type":"string"},"mailingCountry":{"type":"string"},"physicalAddress":{"type":"string"},"monthlyMessageQuota":{"type":"integer"}}}}}},"responses":{"201":{"description":"Created; copy secret now","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/notifications/mailbox":{"get":{"operationId":"listMailbox","summary":"List mailbox conversations (no HTML bodies)","tags":["Mailbox"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Letters","content":{"application/json":{"schema":{"type":"array"}}}}}}},"/api/notifications/mailbox/{id}":{"get":{"operationId":"readMailboxLetter","summary":"Read a letter including HTML","tags":["Mailbox"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Letter","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/notifications/mailbox/send":{"post":{"operationId":"sendMailboxLetter","summary":"Compose or reply from Mailbox","tags":["Mailbox"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","subject","text","fromId"],"properties":{"to":{"type":"string","format":"email"},"subject":{"type":"string"},"text":{"type":"string"},"fromId":{"type":"string","description":"`operator` or a verified From public id"},"replyToId":{"type":"string"}}}}}},"responses":{"200":{"description":"Sent","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/notifications/campaigns":{"get":{"operationId":"listCampaigns","summary":"List campaigns","tags":["Campaigns"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Campaigns","content":{"application/json":{"schema":{"type":"array"}}}}}},"post":{"operationId":"createCampaign","summary":"Create a campaign for an app","tags":["Campaigns"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenantPublicId","name","channels"],"properties":{"tenantPublicId":{"type":"string","description":"App public id"},"name":{"type":"string"},"channels":{"type":"array","items":{"type":"string"}},"audience":{"type":"object"},"scheduledAt":{"type":"integer","nullable":true}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicId"}}}}}}},"/api/notifications/campaigns/{id}/content":{"post":{"operationId":"saveCampaignContent","summary":"Save campaign copy","tags":["Campaigns"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel","locale","subject"],"properties":{"channel":{"type":"string"},"locale":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"providerTemplateId":{"type":"string"}}}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/notifications/campaigns/{id}/send":{"post":{"operationId":"sendCampaign","summary":"Queue a campaign to its audience","tags":["Campaigns"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirmedCount"],"properties":{"confirmedCount":{"type":"integer"}}}}}},"responses":{"200":{"description":"Queued count","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/notifications/contact-lists":{"get":{"operationId":"listPeopleLists","summary":"List people lists","tags":["People"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Lists","content":{"application/json":{"schema":{"type":"array"}}}}}},"post":{"operationId":"createPeopleList","summary":"Create a people list","tags":["People"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","consentSource","consentAt"],"properties":{"name":{"type":"string"},"consentSource":{"type":"string","enum":["purchase","express_optin","event_signup","import_other"]},"consentAt":{"type":"integer"},"consentNote":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicId"}}}}}}},"/api/notifications/contact-lists/{id}/import":{"post":{"operationId":"importPeopleList","summary":"Import CSV members","tags":["People"],"security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"mapping":{"type":"string","description":"JSON: email, phone, name column names"}}}}}},"responses":{"200":{"description":"Imported","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/notifications/automations":{"get":{"operationId":"listAutomations","summary":"List automations","tags":["Automations"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Rules","content":{"application/json":{"schema":{"type":"array"}}}}}},"post":{"operationId":"createAutomation","summary":"Create an automation","tags":["Automations"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenantPublicId","name","triggerEvent","listPublicId"],"properties":{"tenantPublicId":{"type":"string","description":"App public id"},"name":{"type":"string"},"triggerEvent":{"type":"string"},"listPublicId":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicId"}}}}}}},"/api/notifications/tags":{"get":{"operationId":"listTags","summary":"List app message tags","tags":["Tags"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Tags","content":{"application/json":{"schema":{"type":"array"}}}}}},"post":{"operationId":"createTag","summary":"Add a tag to an app","tags":["Tags"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenantPublicId","label"],"properties":{"tenantPublicId":{"type":"string","description":"App public id"},"label":{"type":"string"}}}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"operationId":"deleteTag","summary":"Remove a tag from an app","tags":["Tags"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenantPublicId","slug"],"properties":{"tenantPublicId":{"type":"string"},"slug":{"type":"string"}}}}}},"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/notifications/team":{"get":{"operationId":"listTeam","summary":"List people who can sign in to the console","tags":["Team"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Team","content":{"application/json":{"schema":{"type":"array"}}}}}}},"/api/notifications/templates":{"get":{"operationId":"listTemplates","summary":"List templates","tags":["Templates"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"array"}}}}}},"post":{"operationId":"saveTemplate","summary":"Create or update a template","tags":["Templates"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenantPublicId","event","channel","subject"],"properties":{"tenantPublicId":{"type":"string"},"event":{"type":"string"},"channel":{"type":"string","enum":["email","in_app","sms","whatsapp"]},"locale":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"providerTemplateId":{"type":"string"},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/notifications/webhooks":{"get":{"operationId":"listStatusUpdates","summary":"List status-update endpoints","tags":["Status updates"],"security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Endpoints","content":{"application/json":{"schema":{"type":"array"}}}}}},"post":{"operationId":"createStatusUpdate","summary":"Add a status-update URL","tags":["Status updates"],"security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenantPublicId","url","events"],"properties":{"tenantPublicId":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["message.queued","message.sent","message.failed","message.bounced","message.complained"]}}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}