MCPTool reference
Email Templates tools
Arguments, results, errors, and access, confirmation, and retry policy for each Email Templates tool in FloPay MCP, from the reviewed API contract.
Email Templates tools
Generated from the FloPay MCP contract version 1, revision ebaa9d32d80f46bd8ebf1745c98a59606b57a81fca72005cb4508fcbad9f2d00.
EmailTemplate_get
Get an email template
The client's template for one message type: its draft, the published version that is sent, when it was last reset and Flo's current default. A type the client never edited has no draft, no published version and the default source; reading it stores nothing.
| Policy | Value |
|---|---|
| Operation | GET /v1/email-templates/{type} |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
type | path | string | Yes | The message type, as GET /email-templates lists it. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
defaultBody | object | Yes | Flo's current default for the type: what is sent when the client has nothing published. |
defaultBody.content | object | Yes | The slots: subject, heading and paragraphs (required), and optionally preheader, brandedSubject, highlight, button, buttons, closing and variableDefaults. A text slot is one wording or a list of { text, requires? } wordings. Each text is at most 100 KB. |
defaultBody.mode | string | Yes | Allowed values: structured. |
draft | object or object | Yes | The unpublished draft, or null when there is none. |
lastReset | object or null | Yes | |
lastReset.at | string (date-time) | Yes | |
lastReset.by | string | Yes | Who reset the template. |
published | object or null | Yes | The version that is sent. |
published.basedOnDefault | string | Yes | Fingerprint of Flo's default the template was started from. |
published.body | object or object | Yes | The content of the version. |
published.mode | string | Yes | Allowed values: structured, html. |
published.publishedAt | string (date-time) | Yes | |
published.publishedBy | string | Yes | Who published it: the user for OAuth calls, the API credential for Basic. |
published.version | number | Yes | |
publishedVersion | number or null | Yes | The version that is sent, or null for the default. |
source | string | Yes | What is sent: the client's published version, or Flo's default. Allowed values: default, published. |
type | string | Yes | The message type. |
Errors
| Status | Description |
|---|---|
401 | Client Basic or OAuth2 bearer authentication is required. |
404 | No client email template exists for this message type. |
EmailTemplate_getVersion
Get an email template version
One published version with its content.
| Policy | Value |
|---|---|
| Operation | GET /v1/email-templates/{type}/versions/{version} |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
type | path | string | Yes | The message type, as GET /email-templates lists it. |
version | path | number | Yes | The version number. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
basedOnDefault | string | Yes | Fingerprint of Flo's default the template was started from. |
body | object or object | Yes | The content of the version. |
mode | string | Yes | Allowed values: structured, html. |
publishedAt | string (date-time) | Yes | |
publishedBy | string | Yes | Who published it: the user for OAuth calls, the API credential for Basic. |
version | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The version is not a number. |
401 | Client Basic or OAuth2 bearer authentication is required. |
404 | The client has no such version of this template. |
EmailTemplate_list
List email templates
Every email the client can have its own template for, with whether it is sent (enabled, the switch of its emailType in /emails/settings), what is sent (source: default or published, with the publishedVersion and when it was published, publishedAt) and whether there is an unpublished draft.
| Policy | Value |
|---|---|
| Operation | GET /v1/email-templates |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
page | query | integer | No | 1-based page number for paginated list endpoints. Default: 1. Minimum: 1. |
limit | query | integer | No | Maximum number of records to return per page. Default: 20. Minimum: 1. Maximum: 100. |
sort | query | string | No | Sort by one allowed field. Use exactly one of sort[asc] or sort[desc]. Allowed fields: type. Default: type ASC. Allowed values: type. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
emailType | query | string | No | The email type of /emails/settings that switches the message on or off. A message no switch controls has none, so it matches no emailType. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: order_confirmation, payment_receipt, subscription_activation, dunning_first_failure, dunning_retry_failed, dunning_final, payment_declined, refund_confirmation, cancellation_confirmation. |
enabled | query | string | No | Whether the client sends the email. Equality filter. Pass without operator for exact match. Allowed values: true, false. |
source | query | string | No | What is sent: Flo's default, or the client's published version. Equality filter. Pass without operator for exact match. Allowed values: default, published. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].emailType | string or null | Yes | The email type of /emails/settings that switches this message on or off, or null when none does. |
data[].enabled | boolean | Yes | Whether the client sends this email. A message no switch controls is always sent, so it is on. |
data[].hasDraft | boolean | Yes | |
data[].publishedAt | string (date-time) or null | Yes | When the version that is sent was published: the same value as published.publishedAt of GET /email-templates/{type}. Null exactly when publishedVersion is null, while the default of Flo is sent. |
data[].publishedVersion | number or null | Yes | |
data[].source | string | Yes | Allowed values: default, published. |
data[].type | string | Yes | The message type. |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | A query parameter the list does not support, or a page, limit, sort or filter value it cannot use. |
401 | Client Basic or OAuth2 bearer authentication is required. |
EmailTemplate_listVersions
List email template versions
One page of the client's published versions of the template, without their content: newest first unless sort asks for another order.
| Policy | Value |
|---|---|
| Operation | GET /v1/email-templates/{type}/versions |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
type | path | string | Yes | The message type, as GET /email-templates lists it. |
page | query | integer | No | 1-based page number for paginated list endpoints. Default: 1. Minimum: 1. |
limit | query | integer | No | Maximum number of records to return per page. Default: 20. Minimum: 1. Maximum: 100. |
sort | query | string | No | Sort by one allowed field. Use exactly one of sort[asc] or sort[desc]. Allowed fields: publishedAt, version. Default: version DESC. Allowed values: publishedAt, version. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
publishedBy | query | string | No | Who published the version: the user for OAuth calls, the API credential for Basic. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | Newest first, unless sort asks for another order. |
data[].basedOnDefault | string | Yes | Fingerprint of Flo's default the template was started from. |
data[].mode | string | Yes | Allowed values: structured, html. |
data[].publishedAt | string (date-time) | Yes | |
data[].publishedBy | string | Yes | Who published it: the user for OAuth calls, the API credential for Basic. |
data[].version | number | Yes | |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | A query parameter the list does not support, or a page, limit, sort or filter value it cannot use. |
401 | Client Basic or OAuth2 bearer authentication is required. |
404 | No client email template exists for this message type. |
EmailTemplate_preview
Preview an email template
Renders the draft, or the content currently sent when there is no draft, through the send pipeline with the type's sample data and the client's brand. Problems come back in the body (status: invalid), never as an error. Previewing with a recent email (source: recent) is not available yet: it answers 200 with status: recent_unavailable and a message. A preview changes nothing.
| Policy | Value |
|---|---|
| Operation | POST /v1/email-templates/{type}/preview |
| Class | read-only |
| Risk | medium |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | restricted |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
type | path | string | Yes | The message type, as GET /email-templates lists it. |
source | body | string | No | The data to render with: the type's sample. recent, the client's most recent real email, is not available yet: a preview answers recent_unavailable and a test send 422 not_renderable. Allowed values: sample, recent. Default: sample. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
html | string | Yes | |
message | string | No | A readable reason, given with recent_unavailable, to show as it is. |
problems | array of object | Yes | What publishing the same content would refuse. |
problems[].code | string | Yes | Why: liquid_parse_error, unknown_variable, missing_required_link, render_error (preview only) or invalid_template. |
problems[].column | number | No | |
problems[].line | number | No | |
problems[].message | string | Yes | A readable reason. |
problems[].path | string | No | The variable or slot the reason is about. |
status | string | Yes | recent_unavailable: previewing with a recent email is not available yet; message says so and nothing is rendered. Preview with source: sample instead. Allowed values: rendered, invalid, no_recent_record, recent_unavailable. |
subject | string | Yes | |
text | string | Yes |
Errors
| Status | Description |
|---|---|
400 | The source is not sample or recent. |
401 | Client Basic or OAuth2 bearer authentication is required. |
404 | No client email template exists for this message type. |
EmailTemplate_publish
Publish an email template
Validates the draft and publishes it as the next version: from then on it is what customers receive. A draft that fails validation is refused with every reason, and no version is created.
| Policy | Value |
|---|---|
| Operation | POST /v1/email-templates/{type}/publish |
| Class | mutating |
| Risk | medium |
| Confirmation | required |
| Retry | same-idempotency-key |
| Rate-limit tier | mutation |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
type | path | string | Yes | The message type, as GET /email-templates lists it. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
basedOnDefault | string | Yes | Fingerprint of Flo's default the template was started from. |
body | object or object | Yes | The content of the version. |
mode | string | Yes | Allowed values: structured, html. |
publishedAt | string (date-time) | Yes | |
publishedBy | string | Yes | Who published it: the user for OAuth calls, the API credential for Basic. |
version | number | Yes |
Errors
| Status | Description |
|---|---|
401 | Client Basic or OAuth2 bearer authentication is required. |
404 | No client email template exists for this message type. |
409 | There is no draft to publish. |
422 | The draft fails validation; reasons lists every problem. |
EmailTemplate_reset
Reset an email template to the default
Discards the draft and unpins the published version, so customers receive Flo's default again. Every published version is kept, and who reset it is recorded.
| Policy | Value |
|---|---|
| Operation | POST /v1/email-templates/{type}/reset |
| Class | mutating |
| Risk | medium |
| Confirmation | required |
| Retry | same-idempotency-key |
| Rate-limit tier | mutation |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
type | path | string | Yes | The message type, as GET /email-templates lists it. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
defaultBody | object | Yes | Flo's current default for the type: what is sent when the client has nothing published. |
defaultBody.content | object | Yes | The slots: subject, heading and paragraphs (required), and optionally preheader, brandedSubject, highlight, button, buttons, closing and variableDefaults. A text slot is one wording or a list of { text, requires? } wordings. Each text is at most 100 KB. |
defaultBody.mode | string | Yes | Allowed values: structured. |
draft | object or object | Yes | The unpublished draft, or null when there is none. |
lastReset | object or null | Yes | |
lastReset.at | string (date-time) | Yes | |
lastReset.by | string | Yes | Who reset the template. |
published | object or null | Yes | The version that is sent. |
published.basedOnDefault | string | Yes | Fingerprint of Flo's default the template was started from. |
published.body | object or object | Yes | The content of the version. |
published.mode | string | Yes | Allowed values: structured, html. |
published.publishedAt | string (date-time) | Yes | |
published.publishedBy | string | Yes | Who published it: the user for OAuth calls, the API credential for Basic. |
published.version | number | Yes | |
publishedVersion | number or null | Yes | The version that is sent, or null for the default. |
source | string | Yes | What is sent: the client's published version, or Flo's default. Allowed values: default, published. |
type | string | Yes | The message type. |
Errors
| Status | Description |
|---|---|
401 | Client Basic or OAuth2 bearer authentication is required. |
404 | No client email template exists for this message type. |
EmailTemplate_saveDraft
Save an email template draft
Saves the draft: structured slots (mode: structured) or custom HTML (mode: html). Nothing that is sent changes until the draft is published. Each template text is at most 100 KB.
| Policy | Value |
|---|---|
| Operation | PUT /v1/email-templates/{type}/draft |
| Class | mutating |
| Risk | low |
| Confirmation | required |
| Retry | same-idempotency-key |
| Rate-limit tier | mutation |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
type | path | string | Yes | The message type, as GET /email-templates lists it. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
defaultBody | object | Yes | Flo's current default for the type: what is sent when the client has nothing published. |
defaultBody.content | object | Yes | The slots: subject, heading and paragraphs (required), and optionally preheader, brandedSubject, highlight, button, buttons, closing and variableDefaults. A text slot is one wording or a list of { text, requires? } wordings. Each text is at most 100 KB. |
defaultBody.mode | string | Yes | Allowed values: structured. |
draft | object or object | Yes | The unpublished draft, or null when there is none. |
lastReset | object or null | Yes | |
lastReset.at | string (date-time) | Yes | |
lastReset.by | string | Yes | Who reset the template. |
published | object or null | Yes | The version that is sent. |
published.basedOnDefault | string | Yes | Fingerprint of Flo's default the template was started from. |
published.body | object or object | Yes | The content of the version. |
published.mode | string | Yes | Allowed values: structured, html. |
published.publishedAt | string (date-time) | Yes | |
published.publishedBy | string | Yes | Who published it: the user for OAuth calls, the API credential for Basic. |
published.version | number | Yes | |
publishedVersion | number or null | Yes | The version that is sent, or null for the default. |
source | string | Yes | What is sent: the client's published version, or Flo's default. Allowed values: default, published. |
type | string | Yes | The message type. |
Errors
| Status | Description |
|---|---|
400 | The body is not a template: an unknown mode, no subject, or over 100 KB. |
401 | Client Basic or OAuth2 bearer authentication is required. |
404 | No client email template exists for this message type. |
EmailTemplate_testSend
Send a test email
Sends the draft, or the content currently sent when there is no draft, to one address as a test. The template, its versions and the switches do not change. Test sends are limited per client. Sending a test with a recent email (source: recent) is not available yet: it answers 422 with status: not_renderable.
| Policy | Value |
|---|---|
| Operation | POST /v1/email-templates/{type}/test-send |
| Class | mutating |
| Risk | medium |
| Confirmation | required |
| Retry | same-idempotency-key |
| Rate-limit tier | mutation |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
type | path | string | Yes | The message type, as GET /email-templates lists it. |
source | body | string | No | The data to render with: the type's sample. recent, the client's most recent real email, is not available yet: a preview answers recent_unavailable and a test send 422 not_renderable. Allowed values: sample, recent. Default: sample. |
to | body | string | Yes | The one address the test email goes to. |
Result
Returns 202 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
reason | string or null | Yes | Why the send was refused. |
retryAfterSeconds | number or null | Yes | Seconds until the client may test-send again. |
status | string | Yes | Allowed values: sent, invalid_address, suppressed, rate_limited, not_renderable. |
Errors
| Status | Description |
|---|---|
400 | The address is missing or is not exactly one valid address. |
401 | Client Basic or OAuth2 bearer authentication is required. |
404 | No client email template exists for this message type. |
422 | The content cannot be rendered (not_renderable, also for source: recent, which is not available yet), or the address is on the client's suppression list (suppressed). |
429 | The test-send limit is reached; Retry-After and retryAfterSeconds say when to try again. |
503 | Email delivery is not enabled for the API, so no test email can be sent. Nothing is sent. |
EmailTemplateSchema_get
Get the variable schema of one email type
Returns the variables a template of this email type may use, with their types, descriptions, nullability and sample values, the links it must contain, and a preview sample.
| Policy | Value |
|---|---|
| Operation | GET /v1/email-templates/schemas/{type} |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
type | path | string | Yes | The email type. Allowed values: customer.order_confirmation, customer.payment_receipt, customer.subscription_activated, customer.subscription_dunning, customer.payment_declined, customer.refund_confirmation, customer.subscription_cancelled, customer.abandoned_cart, customer.subscription_renewal_reminder, customer.trial_ending, customer.dunning_first_failure, customer.dunning_retry_failed, customer.dunning_final. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
sample | object | Yes | A preview sample for the whole email: each group's sample, keyed by group. |
type | string | Yes | The email type. Allowed values: customer.order_confirmation, customer.payment_receipt, customer.subscription_activated, customer.subscription_dunning, customer.payment_declined, customer.refund_confirmation, customer.subscription_cancelled, customer.abandoned_cart, customer.subscription_renewal_reminder, customer.trial_ending, customer.dunning_first_failure, customer.dunning_retry_failed, customer.dunning_final. |
variables | object | Yes | The variables a template of this type may use, by group (client, customer, items, payment, subscription, checkout_session, links). items is a list; every other group is an object. |
version | integer | Yes | The schema version. Adding a variable keeps it; removing a deprecated variable raises it by one. Minimum: 1. |
Errors
| Status | Description |
|---|---|
401 | Client Basic or OAuth2 bearer authentication is required. |
404 | No email type with this name has a variable schema. |
EmailTemplateSchema_list
List email variable schemas
Returns the variable schema of every email type: the variables a template may use, with their types, descriptions, nullability and sample values, the links a template must contain, and a preview sample.
| Policy | Value |
|---|---|
| Operation | GET /v1/email-templates/schemas |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
This tool takes no arguments.
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | The variable schema of every email type. |
data[].sample | object | Yes | A preview sample for the whole email: each group's sample, keyed by group. |
data[].type | string | Yes | The email type. Allowed values: customer.order_confirmation, customer.payment_receipt, customer.subscription_activated, customer.subscription_dunning, customer.payment_declined, customer.refund_confirmation, customer.subscription_cancelled, customer.abandoned_cart, customer.subscription_renewal_reminder, customer.trial_ending, customer.dunning_first_failure, customer.dunning_retry_failed, customer.dunning_final. |
data[].variables | object | Yes | The variables a template of this type may use, by group (client, customer, items, payment, subscription, checkout_session, links). items is a list; every other group is an object. |
data[].version | integer | Yes | The schema version. Adding a variable keeps it; removing a deprecated variable raises it by one. Minimum: 1. |
Errors
| Status | Description |
|---|---|
401 | Client Basic or OAuth2 bearer authentication is required. |
Webhooks tools
Arguments, results, errors, and access, confirmation, and retry policy for each Webhooks tool in FloPay MCP, from the reviewed API contract.
Other tools
Arguments, results, errors, and access, confirmation, and retry policy for each Other tool in FloPay MCP, from the reviewed API contract.