List an email's merge fields

Overview

See the merge fields available in an email type, such as the customer's name or the location.

Use this while editing so you know what you can insert.

You'll need the company_id and the template type.

Returns the fields. Only these tokens are accepted when you save, preview or test the template.

Prerequisites

A bearer token. See Authentication.
The account's id (company_id), with the email templates section turned on.
The email type, from List email types.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/account/white-label/email-templates/variables

Authentication

Partner or Account token

company_id must be inside your own account tree. A Partner token can use any account under the partner; an Account token only its own account.
An account outside your tree, or one that doesn't exist, is rejected with 422.
The email templates section must be turned on for the account's partner (email_templates_enabled in Get branding). When it's off, every email template call for that account returns 403 with The email template section is disabled for this account.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Description
`company_id`	integer	Yes	The account. Must exist and be inside your account tree.
`type`	string	Yes	The email type, from List email types.

Request payload

{
  "company_id": 5994,
  "type": "user_welcome"
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`data`	array of objects	The merge fields for this type.
`data[].name`	string	The field's name.
`data[].token`	string	The token to insert, in square brackets.
`data[].description`	string	What the token is replaced with.
`data[].sample`	string	The sample value used in previews and test emails.
`data[].scope`	string	What the value comes from: `recipient`, `review`, `location`, `account` or `global`.

Response payload

{
  "data": {
    "status": "success",
    "data": [
      {
        "name": "User Name",
        "token": "[customerName]",
        "description": "The recipient user's name.",
        "sample": "Jane Doe",
        "scope": "recipient"
      },
      {
        "name": "Set Password URL",
        "token": "[setPasswordUrl]",
        "description": "One-time link for the new user to set their password and sign in.",
        "sample": "https://app.example.com/reset-password?token=…",
        "scope": "recipient"
      },
      {
        "name": "Partner Title",
        "token": "[partnerTitle]",
        "description": "White-label product title shown in emails.",
        "sample": "Acme Reviews",
        "scope": "account"
      },
      {
        "name": "Primary Color",
        "token": "[primaryColor]",
        "description": "Partner brand color from theme settings (buttons, section headers).",
        "sample": "#1459c4",
        "scope": "account"
      },
      {
        "name": "Account Name",
        "token": "[accountName]",
        "description": "The brand/account name.",
        "sample": "Bright Smile Dental",
        "scope": "account"
      },
      {
        "name": "Current Year",
        "token": "[currentYear]",
        "description": "The current four-digit year.",
        "sample": "2026",
        "scope": "global"
      },
      {
        "name": "Unsubscribe URL",
        "token": "[unsubscribeUrl]",
        "description": "Link the recipient can use to unsubscribe.",
        "sample": "https://app.example.com/unsubscribe/...",
        "scope": "recipient"
      },
      {
        "name": "Reconnect URL",
        "token": "[reconnectUrl]",
        "description": "Partner portal root URL (white-label app URL). On Account Disconnected emails, send overrides this with the location's review-site connection page when available.",
        "sample": "https://app.example.com",
        "scope": "global"
      }
    ]
  }
}

Examples

Success payload

See Response payload.

Error payload

403 Email templates section is off

{
  "message": "The email template section is disabled for this account.",
  "status": "error",
  "errors": []
}

422 type isn't a known email type

{
  "message": "The selected type is invalid.",
  "errors": {
    "type": [
      "The selected type is invalid."
    ]
  }
}

422 type is missing

{
  "message": "The type field is required.",
  "errors": {
    "type": [
      "The type field is required."
    ]
  }
}

422 Account outside your tree

{
  "message": "The selected company id does not belong to your company hierarchy.",
  "errors": {
    "company_id": [
      "The selected company id does not belong to your company hierarchy."
    ]
  }
}

Status	Meaning
`200`	The merge fields.
`401`	The token is missing, expired or invalid.
`403`	The email templates section is off for this account.
`422`	`company_id` or `type` is missing or invalid, or the account is outside your tree.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/white-label/email-templates/variables" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"company_id": 5994, "type": "user_welcome"}'