akadmin/chatwoot
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: add branded email layout API reference (#15023)

Browse Source 
## Description

Adds Swagger API documentation for branded email layouts, including the
account-level layout endpoint, Email inbox update field, and generated
API schemas. This stacked PR keeps the implementation review in #14936
focused on the product change.

Related:
[CW-7514](https://linear.app/chatwoot/issue/CW-7514/branded-html-email-templates-per-inboxbrand)
Depends on #14936

## Type of change

- [x] This change requires a documentation update

## How to test

1. Run `bundle exec rake swagger:build`.
2. Start Chatwoot locally and open `http://localhost:3000/swagger`.
3. Verify the branded email layout account endpoint and Email inbox
`branded_email_layout` field appear in the API reference.

## Checklist

- [x] I have performed a self-review of my changes
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
This commit is contained in:
Sony Mathew
2026-07-17 16:20:00 +05:30
committed by GitHub
parent 90861f8809
commit 259187e1fd
12 changed files with 503 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
swagger/definitions/index.yml
+4
View File
@@ -46,6 +46,8 @@ agent:
$ref: ./resource/agent.yml $ref: ./resource/agent.yml
inbox: inbox:
$ref: ./resource/inbox.yml $ref: ./resource/inbox.yml
branded_email_layout:
$ref: ./resource/branded_email_layout.yml
inbox_contact: inbox_contact:
$ref: ./resource/inbox_contact.yml $ref: ./resource/inbox_contact.yml
agent_bot: agent_bot:
@@ -145,6 +147,8 @@ inbox_create_payload:
$ref: ./request/inbox/create_payload.yml $ref: ./request/inbox/create_payload.yml
inbox_update_payload: inbox_update_payload:
$ref: ./request/inbox/update_payload.yml $ref: ./request/inbox/update_payload.yml
account_branded_email_layout_payload:
$ref: ./request/account/branded_email_layout_payload.yml
inbox_create_web_widget_channel_payload: inbox_create_web_widget_channel_payload:
$ref: ./request/inbox/channels/create_web_widget_channel_payload.yml $ref: ./request/inbox/channels/create_web_widget_channel_payload.yml
inbox_create_api_channel_payload: inbox_create_api_channel_payload:
swagger/definitions/request/account/branded_email_layout_payload.yml
+8
View File
@@ -0,0 +1,8 @@
type: object
properties:
branded_email_layout:
type:
- string
- 'null'
description: Account-scoped Liquid HTML layout for branded email replies. Blank or null removes the account override.
example: '<html><body>{{ content_for_layout }}</body></html>'
swagger/definitions/request/inbox/update_payload.yml
+9
View File
@@ -109,6 +109,15 @@ properties:
Available for: `Website` `Email` Available for: `Website` `Email`
example: 'My Business' example: 'My Business'
branded_email_layout:
type:
- string
- 'null'
description: |
Liquid HTML layout for outbound email replies. Must include `{{ content_for_layout }}`.
Available for: `Email`
example: '<html><body>{{ content_for_layout }}</body></html>'
channel: channel:
anyOf: anyOf:
- $ref: '#/components/schemas/inbox_update_web_widget_channel_payload' - $ref: '#/components/schemas/inbox_update_web_widget_channel_payload'
swagger/definitions/resource/branded_email_layout.yml
+8
View File
@@ -0,0 +1,8 @@
type: object
properties:
branded_email_layout:
type:
- string
- 'null'
description: Account-scoped Liquid HTML layout for branded email replies.
example: '<html><body>{{ content_for_layout }}</body></html>'
swagger/definitions/resource/inbox.yml
+5
View File
@@ -122,6 +122,11 @@ properties:
- string - string
- 'null' - 'null'
description: Business name associated with the inbox description: Business name associated with the inbox
branded_email_layout:
type:
- string
- 'null'
description: Liquid HTML layout for branded email replies. Available to administrators for Email inbox show/update responses.
hmac_mandatory: hmac_mandatory:
type: boolean type: boolean
description: Whether HMAC verification is mandatory description: Whether HMAC verification is mandatory
swagger/paths/application/branded_email_layout.yml
+58
View File
@@ -0,0 +1,58 @@
get:
tags:
- Inboxes
operationId: getAccountBrandedEmailLayout
summary: Get account branded email layout
security:
- userApiKey: []
description: Get the account-scoped Liquid HTML layout used as the fallback for branded email replies.
parameters:
- $ref: '#/components/parameters/account_id'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/branded_email_layout'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
patch:
tags:
- Inboxes
operationId: updateAccountBrandedEmailLayout
summary: Update account branded email layout
security:
- userApiKey: []
description: Update or clear the account-scoped Liquid HTML layout used as the fallback for branded email replies.
parameters:
- $ref: '#/components/parameters/account_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/account_branded_email_layout_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/branded_email_layout'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'422':
description: Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
swagger/paths/index.yml
+2
View File
@@ -411,6 +411,8 @@
$ref: ./application/conversation/reporting_events.yml $ref: ./application/conversation/reporting_events.yml
# Inboxes # Inboxes
/api/v1/accounts/{account_id}/branded_email_layout:
$ref: ./application/branded_email_layout.yml
/api/v1/accounts/{account_id}/inboxes: /api/v1/accounts/{account_id}/inboxes:
$ref: ./application/inboxes/index.yml $ref: ./application/inboxes/index.yml
/api/v1/accounts/{account_id}/inboxes/{id}: /api/v1/accounts/{account_id}/inboxes/{id}:
swagger/swagger.json
+143
View File
@@ -5374,6 +5374,108 @@
} }
} }
}, },
"/api/v1/accounts/{account_id}/branded_email_layout": {
"get": {
"tags": [
"Inboxes"
],
"operationId": "getAccountBrandedEmailLayout",
"summary": "Get account branded email layout",
"security": [
{
"userApiKey": []
}
],
"description": "Get the account-scoped Liquid HTML layout used as the fallback for branded email replies.",
"parameters": [
{
"$ref": "#/components/parameters/account_id"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/branded_email_layout"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
},
"patch": {
"tags": [
"Inboxes"
],
"operationId": "updateAccountBrandedEmailLayout",
"summary": "Update account branded email layout",
"security": [
{
"userApiKey": []
}
],
"description": "Update or clear the account-scoped Liquid HTML layout used as the fallback for branded email replies.",
"parameters": [
{
"$ref": "#/components/parameters/account_id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/account_branded_email_layout_payload"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/branded_email_layout"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
}
},
"/api/v1/accounts/{account_id}/inboxes": { "/api/v1/accounts/{account_id}/inboxes": {
"get": { "get": {
"tags": [ "tags": [
@@ -10465,6 +10567,13 @@
], ],
"description": "Business name associated with the inbox" "description": "Business name associated with the inbox"
}, },
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Liquid HTML layout for branded email replies. Available to administrators for Email inbox show/update responses."
},
"hmac_mandatory": { "hmac_mandatory": {
"type": "boolean", "type": "boolean",
"description": "Whether HMAC verification is mandatory" "description": "Whether HMAC verification is mandatory"
@@ -10510,6 +10619,19 @@
} }
} }
}, },
"branded_email_layout": {
"type": "object",
"properties": {
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Account-scoped Liquid HTML layout for branded email replies.",
"example": "<html><body>{{ content_for_layout }}</body></html>"
}
}
},
"inbox_contact": { "inbox_contact": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -12677,6 +12799,14 @@
"description": "Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n", "description": "Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n",
"example": "My Business" "example": "My Business"
}, },
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Liquid HTML layout for outbound email replies. Must include `{{ content_for_layout }}`.\n\nAvailable for: `Email`\n",
"example": "<html><body>{{ content_for_layout }}</body></html>"
},
"channel": { "channel": {
"anyOf": [ "anyOf": [
{ {
@@ -12704,6 +12834,19 @@
} }
} }
}, },
"account_branded_email_layout_payload": {
"type": "object",
"properties": {
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Account-scoped Liquid HTML layout for branded email replies. Blank or null removes the account override.",
"example": "<html><body>{{ content_for_layout }}</body></html>"
}
}
},
"inbox_create_web_widget_channel_payload": { "inbox_create_web_widget_channel_payload": {
"type": "object", "type": "object",
"title": "Website channel", "title": "Website channel",
swagger/tag_groups/application_swagger.json
+143
View File
@@ -3917,6 +3917,108 @@
} }
} }
}, },
"/api/v1/accounts/{account_id}/branded_email_layout": {
"get": {
"tags": [
"Inboxes"
],
"operationId": "getAccountBrandedEmailLayout",
"summary": "Get account branded email layout",
"security": [
{
"userApiKey": []
}
],
"description": "Get the account-scoped Liquid HTML layout used as the fallback for branded email replies.",
"parameters": [
{
"$ref": "#/components/parameters/account_id"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/branded_email_layout"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
},
"patch": {
"tags": [
"Inboxes"
],
"operationId": "updateAccountBrandedEmailLayout",
"summary": "Update account branded email layout",
"security": [
{
"userApiKey": []
}
],
"description": "Update or clear the account-scoped Liquid HTML layout used as the fallback for branded email replies.",
"parameters": [
{
"$ref": "#/components/parameters/account_id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/account_branded_email_layout_payload"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/branded_email_layout"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/bad_request_error"
}
}
}
}
}
}
},
"/api/v1/accounts/{account_id}/inboxes": { "/api/v1/accounts/{account_id}/inboxes": {
"get": { "get": {
"tags": [ "tags": [
@@ -8972,6 +9074,13 @@
], ],
"description": "Business name associated with the inbox" "description": "Business name associated with the inbox"
}, },
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Liquid HTML layout for branded email replies. Available to administrators for Email inbox show/update responses."
},
"hmac_mandatory": { "hmac_mandatory": {
"type": "boolean", "type": "boolean",
"description": "Whether HMAC verification is mandatory" "description": "Whether HMAC verification is mandatory"
@@ -9017,6 +9126,19 @@
} }
} }
}, },
"branded_email_layout": {
"type": "object",
"properties": {
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Account-scoped Liquid HTML layout for branded email replies.",
"example": "<html><body>{{ content_for_layout }}</body></html>"
}
}
},
"inbox_contact": { "inbox_contact": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -11184,6 +11306,14 @@
"description": "Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n", "description": "Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n",
"example": "My Business" "example": "My Business"
}, },
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Liquid HTML layout for outbound email replies. Must include `{{ content_for_layout }}`.\n\nAvailable for: `Email`\n",
"example": "<html><body>{{ content_for_layout }}</body></html>"
},
"channel": { "channel": {
"anyOf": [ "anyOf": [
{ {
@@ -11211,6 +11341,19 @@
} }
} }
}, },
"account_branded_email_layout_payload": {
"type": "object",
"properties": {
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Account-scoped Liquid HTML layout for branded email replies. Blank or null removes the account override.",
"example": "<html><body>{{ content_for_layout }}</body></html>"
}
}
},
"inbox_create_web_widget_channel_payload": { "inbox_create_web_widget_channel_payload": {
"type": "object", "type": "object",
"title": "Website channel", "title": "Website channel",
swagger/tag_groups/client_swagger.json
+41
View File
@@ -1882,6 +1882,13 @@
], ],
"description": "Business name associated with the inbox" "description": "Business name associated with the inbox"
}, },
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Liquid HTML layout for branded email replies. Available to administrators for Email inbox show/update responses."
},
"hmac_mandatory": { "hmac_mandatory": {
"type": "boolean", "type": "boolean",
"description": "Whether HMAC verification is mandatory" "description": "Whether HMAC verification is mandatory"
@@ -1927,6 +1934,19 @@
} }
} }
}, },
"branded_email_layout": {
"type": "object",
"properties": {
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Account-scoped Liquid HTML layout for branded email replies.",
"example": "<html><body>{{ content_for_layout }}</body></html>"
}
}
},
"inbox_contact": { "inbox_contact": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -4094,6 +4114,14 @@
"description": "Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n", "description": "Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n",
"example": "My Business" "example": "My Business"
}, },
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Liquid HTML layout for outbound email replies. Must include `{{ content_for_layout }}`.\n\nAvailable for: `Email`\n",
"example": "<html><body>{{ content_for_layout }}</body></html>"
},
"channel": { "channel": {
"anyOf": [ "anyOf": [
{ {
@@ -4121,6 +4149,19 @@
} }
} }
}, },
"account_branded_email_layout_payload": {
"type": "object",
"properties": {
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Account-scoped Liquid HTML layout for branded email replies. Blank or null removes the account override.",
"example": "<html><body>{{ content_for_layout }}</body></html>"
}
}
},
"inbox_create_web_widget_channel_payload": { "inbox_create_web_widget_channel_payload": {
"type": "object", "type": "object",
"title": "Website channel", "title": "Website channel",
swagger/tag_groups/other_swagger.json
+41
View File
@@ -1297,6 +1297,13 @@
], ],
"description": "Business name associated with the inbox" "description": "Business name associated with the inbox"
}, },
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Liquid HTML layout for branded email replies. Available to administrators for Email inbox show/update responses."
},
"hmac_mandatory": { "hmac_mandatory": {
"type": "boolean", "type": "boolean",
"description": "Whether HMAC verification is mandatory" "description": "Whether HMAC verification is mandatory"
@@ -1342,6 +1349,19 @@
} }
} }
}, },
"branded_email_layout": {
"type": "object",
"properties": {
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Account-scoped Liquid HTML layout for branded email replies.",
"example": "<html><body>{{ content_for_layout }}</body></html>"
}
}
},
"inbox_contact": { "inbox_contact": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -3509,6 +3529,14 @@
"description": "Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n", "description": "Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n",
"example": "My Business" "example": "My Business"
}, },
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Liquid HTML layout for outbound email replies. Must include `{{ content_for_layout }}`.\n\nAvailable for: `Email`\n",
"example": "<html><body>{{ content_for_layout }}</body></html>"
},
"channel": { "channel": {
"anyOf": [ "anyOf": [
{ {
@@ -3536,6 +3564,19 @@
} }
} }
}, },
"account_branded_email_layout_payload": {
"type": "object",
"properties": {
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Account-scoped Liquid HTML layout for branded email replies. Blank or null removes the account override.",
"example": "<html><body>{{ content_for_layout }}</body></html>"
}
}
},
"inbox_create_web_widget_channel_payload": { "inbox_create_web_widget_channel_payload": {
"type": "object", "type": "object",
"title": "Website channel", "title": "Website channel",
swagger/tag_groups/platform_swagger.json
+41
View File
@@ -2058,6 +2058,13 @@
], ],
"description": "Business name associated with the inbox" "description": "Business name associated with the inbox"
}, },
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Liquid HTML layout for branded email replies. Available to administrators for Email inbox show/update responses."
},
"hmac_mandatory": { "hmac_mandatory": {
"type": "boolean", "type": "boolean",
"description": "Whether HMAC verification is mandatory" "description": "Whether HMAC verification is mandatory"
@@ -2103,6 +2110,19 @@
} }
} }
}, },
"branded_email_layout": {
"type": "object",
"properties": {
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Account-scoped Liquid HTML layout for branded email replies.",
"example": "<html><body>{{ content_for_layout }}</body></html>"
}
}
},
"inbox_contact": { "inbox_contact": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -4270,6 +4290,14 @@
"description": "Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n", "description": "Business name for outbound email replies.\n\nAvailable for: `Website` `Email`\n",
"example": "My Business" "example": "My Business"
}, },
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Liquid HTML layout for outbound email replies. Must include `{{ content_for_layout }}`.\n\nAvailable for: `Email`\n",
"example": "<html><body>{{ content_for_layout }}</body></html>"
},
"channel": { "channel": {
"anyOf": [ "anyOf": [
{ {
@@ -4297,6 +4325,19 @@
} }
} }
}, },
"account_branded_email_layout_payload": {
"type": "object",
"properties": {
"branded_email_layout": {
"type": [
"string",
"null"
],
"description": "Account-scoped Liquid HTML layout for branded email replies. Blank or null removes the account override.",
"example": "<html><body>{{ content_for_layout }}</body></html>"
}
}
},
"inbox_create_web_widget_channel_payload": { "inbox_create_web_widget_channel_payload": {
"type": "object", "type": "object",
"title": "Website channel", "title": "Website channel",