Warning
You are viewing the technical documentation for the Sharetribe Developer Platform. If you are looking for our no-code documentation, see our help center.

Last updated

Email templates

Reference documentation for editing built-in or transaction email templates.

Table of Contents

Sharetribe supports customizing the contents of all the emails that are sent from the platform.

The platform sends two types of emails:

  • built-in emails on events like email changed or user joined
  • transaction emails as notifications as part of the transaction process.

The built-in emails can be customized using the Built-in email notifications editor in the Sharetribe Console. You find the editor in Console under Build > Advanced > Email notifications section.

To change the transaction emails, follow the Edit email templates with Sharetribe CLI tutorial.

Best practices

In addition to the basic branding of the emails to follow your marketplace brand and visual guidelines, we recommend that you follow these best practises for email branding to avoid spam folders:

  • Make the email personal, add a starting line with the name of the recipient and other distinct elements like the title of the listing.
  • Add a common footer to the emails with basic information about your marketplace.
  • Currently, the emails sent from the platform are purely notifications on actions in the marketplace, there isn't a way to unsubscribe from these emails, so make sure your users have given consent to receiving these emails when registering to the platform.
  • Design your emails so that they encourage users to navigate to the marketplace and continue the actions there - we don't support e.g. responding to messages in the platform through email.

Sharetribe’s email system handles SPF (Sender Policy Framework) and DKIM (DomainKeys Identified Mail) automatically to improve your email deliverability.

Handlebars

The template language used to build the email templates is called Handlebars.

With Handlebars you get direct access to the HTML that will be sent to your users. The Handlebars template defined by you will be applied to the email context, that contains the data for the email, e.g. recipient name, marketplace name and all the transaction details such as booking dates, line items etc. if the email is related to a transaction. The result of applying the email context to the template is the rendered HTML that will be sent to your users.

Please read through the Handlebars documentation for more information about the templating language.

Helpers

Sharetribe email templating supports a subset of Handlebars built in helpers.

In addition to the built-in helpers, we have implemented a small set of custom helpers that make e.g. comparisons and number formatting possible.

The helpers may support positional parameters, hash parameters or both.

For example: {{helper param-1 param-2 hash-param=value}}.

Some documentation on the syntax and how to use them can be found in the documentation for Handlebars expressions.

Built-in helpers

We support the following built-in helpers:

  • each
  • with
  • if
  • unless

Have a look at the Handlebars built-in helpers documentation to see examples how to use them.

In addition to those, we also support inline partials.

Custom helpers

This paragraph lists all the custom helpers we provide, including the parameters they take and example how to use them:

Can't find a helper you are looking for? Let us know!

t

Params:

  • message key
  • fallback message

Hash:

  • list of hash parameters and their respective values used with the messages

Example usage:

{{t "BookingNewRequest.Description" "{customerDisplayName} requested to book {listingTitle}
in {marketplaceName}." customerDisplayName=customer.display-name
listingTitle=listing.title marketplaceName=marketplace.name}}

Inline helper that makes it possible to modify the email template texts without making changes in the template code. This helper uses the ICU message format to render messages and parameters into a string.

The helper renders the message corresponding to the key, if the key exists in the email text asset. If the key does not exist, the helper renders the fallback message.

Any hash parameters used inside either message must be wrapped in single curly brackets, and the values for those hash parameters need to be defined after the message key and the fallback message.

format-text

Params:

  • message

Hash:

  • list of hash parameters and their respective values used with the messages

Example usage:

{{format-text "{amount,number,::.00} {currency}" amount=money.amount currency=money.currency}}

Inline helper that formats a text string using the ICU message format. This helper works similarly to the t helper, but instead of accepting a message key and a fallback message, it accepts a single string.

Any hash parameters used inside either message must be wrapped in single curly brackets, and the values for those hash parameters need to be defined after the message.

contains

Params:

  • collection
  • value

Example usage:

{{#contains collection value}}true{{else}}false{{/contains}}

Block helper that renders the block if collection has the given value, otherwise the else block is rendered (if specified).

eq

Params:

  • value
  • test

Example usage:

{{#eq value 1}}true{{else}}false{{/eq}}

Block helper that renders a block if value is equal to test. If an else block is specified it will be rendered when falsy.

inflect

Params

  • count
  • singular
  • plural

Example usage:

{{inflect quantity "day" "days"}}

Returns either the singular or plural inflection of a word based on the given count.

date

Params:

  • time

Hash:

  • format
  • lang: optional, default: "en-US"
  • tz: optional, default "UTC"

Example usage:

{{date d format="d. MMM, YYYY" lang="fi-FI" tz="Europe/Helsinki"}}

Renders a properly localized time based on the format, lang and tz hash parameters.

The format supports Joda-Time formatting.

The lang supports IETF BCP 47 language tag strings. More info about language tags can be found in the W3C Internationalization article for language tags. E.g. "en-US" is a valid string.

The tz supports Joda-Time timezones.

date-day-before

Params:

  • time

Hash:

  • format
  • lang: optional, default en-US
  • tz: optional, default "UTC"

Example usage:

{{date-day-before d format="d. MMM, YYYY" lang="fi-FI" tz="Europe/Helsinki"}}

Renders a properly localized time, one day before the given date, based on the format and lang hash parameters.

The format supports Joda-Time formatting.

The lang supports IETF BCP 47 language tag strings. More info about language tags can be found W3C Internationalization article for language tags. E.g. "en-US" is a valid string.

The tz supports Joda-Time timezones.

date-transform

Params:

  • date

Hash:

  • days

Example usage:

{{format-text "{date,date,::EE}" date=(date-transform date days=-1)}}

Can be used with the format-text helper to transform a date value to past or future days according to the days hash parameter:

  • negative values for transforming to the past of the date
  • positive values for transforming to the future of the date

money-amount

Params:

  • money

Hash:

  • lang: optional, default "en-US"

Example usage:

{{money-amount m lang="fi-FI"}}

Takes money and formats the amount according to the currency.

For example:

  • EUR amounts are formatted with 2 decimals
  • JPY amounts are formatted with no decimals

Does not output the currency code or symbol, only the amount.

The lang supports IETF BCP 47 language tag strings. More info about language tags can be found W3C Internationalization article for language tags. E.g. "en-US" is a valid string.

number

Params:

  • number

Hash:

  • lang: optional, default "en-US"
  • max-fraction-digits: optional
  • min-fraction-digits: optional

Example usage:

{{number n lang="fi-FI"}}

Formats the given number. lang, max-fraction-digits and min-fraction-digits can be given as hash params."

The lang supports IETF BCP 47 language tag strings. More info about language tags can be found W3C Internationalization article for language tags. E.g. "en-US" is a valid string.

url-encode

Params:

  • str

Example usage:

{{url-encode "Share & Tribe"}}

URL encodes the given string. Should be used for encoding all user input. E.g. a link to user profile with the user name in the link should be encoded.

form-encode

Params:

  • str

Example usage:

{{form-encode "Share & Tribe"}}

Encode the given string as application/x-www-form-urlencoded. Should be used for query string components.

asset

Params:

  • asset path
  • (optional) JSON key or dot-separated nested keys
  • (optional) default value

The helper is used to retrieve data from assets. It can locate values within nested fields by providing a sequence of keys, separated by dots, to traverse the JSON structure. For example, the colour of a button in the email template can be assigned dynamically by accessing the design/branding.json asset. The use of this helper is not limited to the branding asset – any asset data can be used in the templates.

{{asset "design/branding.json" "marketplaceColors.notificationPrimaryButton" "#007DF2"}}

In addition, in the email templates, this helper is used to define the correct localization settings in the email templates without modifying the template structure itself:

{{set-translations (asset "content/email-texts.json")}}
{{set-locale (asset "general/localization.json" "locale" "en_US")}}

Editing email content

For both built-in emails and transaction process emails, you can edit content with the email text editor under Build > Content > Email texts.

Editing built-in emails

The built-in emails can be customized using the Built-in email notifications editor in the Sharetribe Console. You find the editor in the Console under Build > Advanced > Email notifications section.

In addition to the code editor that allows you to edit the template, the editor also contains a context viewer that shows you a sample of the context that will be used with that particular email.

The editor also let's you to see a preview of the email before and let's you send test emails to your own email address.

These built-in email notifications can be disabled through Console:

  • Listing approved
  • New message
  • User approved
  • User joined
  • User permissions changed
  • Verify email address

Built-in email context variables

Next to the built-in email editor in Console, you can see the different context variables and sample values that are available for the built-in email you are editing. Different email templates have different context variables available. The context variables available for each built-in template are under the following links.

Email address changed

recipient: user {
  id: UUID
  first-name: string
  last-name: string
  display-name: string
  private-data: extended-data
  public-data: extended-data
  protected-data: extended-data
  metadata: extended-data
},
marketplace: marketplace {
  name: string
  url: string
}

Listing approved

recipient: user {
  id: UUID
  first-name: string
  last-name: string
  display-name: string
  private-data: extended-data
  public-data: extended-data
  protected-data: extended-data
  metadata: extended-data
}
marketplace: marketplace {
  name: string
  url: string
}
listing: listing {
  id: UUID
  title: string
  private-data: extended-data
  public-data: extended-data 0 items
  metadata: extended-data 0 items
  availability-plan: availability-plan {
    type: string
    timezone: string
  }
  current-stock: stock {
    quantity: int
  }
}

New message

recipient: user {
  id: UUID
  first-name: string
  last-name: string
  display-name: string
  private-data: extended-data
  public-data: extended-data
  protected-data: extended-data
  metadata: extended-data
}
marketplace: marketplace {
  name: string
  url: string
}
message: message {
  sender: user {
    id: UUID 5a680a01-a281-4e7a-a276-786280fda2b8
    first-name: string "Alice"
    last-name: string "Smith"
    display-name: string "Alice S"
    private-data: extended-data 0 items
    public-data: extended-data 0 items
    protected-data: extended-data 0 items
    metadata: extended-data 0 items
  }
  content: string
  transaction: transaction {
    booking: booking {
      start: date {
        year: int
        month: int
        day: int
        hours: int
        minutes: int
        seconds: int
        milliseconds: int
      }
      end: date {
        year: int
        month: int
        day: int
        hours: int
        minutes: int
        seconds: int
        milliseconds: int
      }
      displayStart: date {
        year: int
        month: int
        day: int
        hours: int
        minutes: int
        seconds: int
        milliseconds: int
      }
      displayEnd: date {
        year: int
        month: int
        day: int
        hours: int
        minutes: int
        seconds: int
        milliseconds: int

      }
      state: string
      seats: int
    }
    listing: listing {
      id: UUID
      title: string
      private-data: extended-data
      public-data: extended-data
      metadata: extended-data
      availability-plan: availability-plan {
        timezone: string
        type: string
      }
      current-stock: stock {
        quantity: int 10
      }
    }
    delayed-transition: delayed-transition {
      run-at: date {
        year: int 2018
        month: int 9
        day: int 27
        hours: int 18
        minutes: int 30
        seconds: int 30
        milliseconds: int 0
      }
    }
    payout-total: money {
      amount: decimal 32.13
      currency: string "USD"
    }
    protected-data: extended-data
    customer: user {
      id: UUID
      first-name: string
      last-name: string
      display-name: string
      private-data: extended-data
      public-data: extended-data
      protected-data: extended-data
      metadata: extended-data
    }
    payin-total: money {
      amount: decimal
      currency: string
    }
    id: UUID 3df61814-6b0c-4652-bbc6-869a1d911150
    reviews: reviews [
      0: review {
        content: string "Sample review of customer"
        subject: user {
          id: UUID 5a680a01-a281-4e7a-a276-786280fda2b8
          first-name: string "Alice"
          last-name: string "Smith"
          display-name: string "Alice S"
          private-data: extended-data 0 items
          public-data: extended-data 0 items
          protected-data: extended-data 0 items
          metadata: extended-data 0 items
        }
      }
      1: review {
        content: string "Sample review of provider"
        subject: user {
          id: UUID 2b44e4fd-ec24-4730-a3ff-9af3a07d6751
          first-name: string "John"
          last-name: string "Doe"
          display-name: string "John D"
          private-data: extended-data 0 items
          public-data: extended-data 0 items
          protected-data: extended-data 0 items
          metadata: extended-data 0 items
        }
      }
    ]
    tx-line-items: tx-line-items [
    0: tx-line-item {
      code: string
      unit-price: money {
        amount: decimal
        currency: string
      }
      line-total: money {
        amount: decimal
        currency: string
      }
      include-for: include-for [
        0: transaction-role "customer"
        1: transaction-role "provider"
      ]
      quantity: decimal
      percentage: decimal
      units: decimal
      seats: int
    }
    1: tx-line-item {
      code: string
      unit-price: money {
        amount: decimal
        currency: string
      }
      line-total: money {
        amount: decimal
        currency: string
      }
      include-for: include-for [
        0: transaction-role "provider"
      ]
      quantity: decimal
      percentage: decimal
      units: decimal
      seats: int
      }
    ]
    provider: user {
      id: UUID
      first-name: string
      last-name: string
      display-name: string
      private-data: extended-data
      public-data: extended-data
      protected-data: extended-data
      metadata: extended-data
    }
    stock-reservation: stock-reservation {
      quantity: int
    }
    state: string
    metadata: extended-data
  }
}
recipient-role: transaction-role

Password changed

recipient: user {
  id: UUID
  first-name: string
  last-name: string
  display-name: string
  private-data: extended-data
  public-data: extended-data
  protected-data: extended-data
  metadata: extended-data
}
marketplace: marketplace {
  name: string
  url: string
}

Reset password

recipient: user {
  id: UUID
  first-name: string
  last-name: string
  display-name: string
  private-data: extended-data
  public-data: extended-data
  protected-data: extended-data
  metadata: extended-data
}
marketplace: marketplace {
  name: string
  url: string
}
password-reset: password-reset {
  token: string
  email-address: string
}

User approved

recipient: user {
  id: UUID
  first-name: string
  last-name: string
  display-name: string
  private-data: extended-data
  public-data: extended-data
  protected-data: extended-data
  metadata: extended-data
}
marketplace: marketplace {
  name: string
  url: string
}

User joined

recipient: user {
  id: UUID
  first-name: string
  last-name: string
  display-name: string
  private-data: extended-data
  public-data: extended-data
  protected-data: extended-data
  metadata: extended-data
}
marketplace: marketplace {
  name: string
  url: string
}

User permissions changed

recipient: user {
  id: UUID
  first-name: string
  last-name: string
  display-name: string
  private-data: extended-data
  public-data: extended-data
  protected-data: extended-data
  metadata: extended-data
}
marketplace: marketplace {
  name: string
  url: string
}
changed-permissions: changed-permissions {
  read: permission-value
  postListings: permission-value
  initiateTransactions: permission-value
}

Verify changed email address

recipient: user {
  id: UUID
  first-name: string
  last-name: string
  display-name: string
  private-data: extended-data
  public-data: extended-data
  protected-data: extended-data
  metadata: extended-data
}
marketplace: marketplace {
  name: string
  url: string
}
email-verification: email-verification {
  token: string
}

Verify email address

recipient: user {
  id: UUID
  first-name: string
  last-name: string
  display-name: string
  private-data: extended-data
  public-data: extended-data
  protected-data: extended-data
  metadata: extended-data
}
marketplace: marketplace {
  name: string
  url: string
}
email-verification: email-verification {
  token: string
}

Editing transaction emails

To understand how to change the transaction emails, see the Edit email templates with Sharetribe CLI tutorial.

Transaction email context

Context for transaction emails:

{
  "recipient": {
    "id": "uuid",
    "first-name": "string",
    "last-name": "string",
    "display-name": "string",
    "private-data": "extended-data",
    "public-data": "extended-data",
    "protected-data": "extended-data",
    "metadata": "extended-data"
  },
  "marketplace": {
    "name": "string",
    "url": "string"
  },
  "recipient-role": "string", // either "provider" or "customer"
  "other-party": {
    "id": "uuid",
    "first-name": "string",
    "last-name": "string",
    "display-name": "string",
    "private-data": "extended-data",
    "public-data": "extended-data",
    "protected-data": "extended-data",
    "metadata": "extended-data"
  },
  "transaction": {
    "id": "uuid",
    "tx-line-items": [
      {
        "code": "string",
        "unit-price": {
          "amount": "decimal",
          "currency": "string"
        } ,
        "line-total":
        {
          "amount": "decimal",
          "currency": "string"
        } ,
        "include-for": {"any-of": ["provider", "customer"]},
        "quantity": "decimal",
        "percentage": "decimal"}
    ],
    "payout-total": {
      "amount": "decimal",
      "currency": "string"
    },
    "booking": {
      "start": "date",
      "end": "date",
      "displayStart": "date",
      "displayEnd": "date",
      "seats": "integer",
      "state": "string"
    },
    "stock-reservation": {
      "quantity": "integer",
      "state": "string"
    },
    "reviews": [
      {
        "content": "string",
        "subject": {
          "id": "uuid",
          "first-name": "string",
          "last-name": "string",
          "display-name": "string",
          "private-data": "extended-data",
          "public-data": "extended-data",
          "protected-data": "extended-data",
          "metadata": "extended-data"
        }
      }
    ],
    "provider": {
      "id": "uuid",
      "first-name": "string",
      "last-name": "string",
      "display-name": "string",
      "private-data": "extended-data",
      "public-data": "extended-data",
      "protected-data": "extended-data",
      "metadata": "extended-data"
    },
    "payin-total": {
      "amount": "decimal",
      "currency": "string"
    },
    "listing": {
      "id": "uuid",
      "title": "string,"
      "availability-plan": {
        "type": "string", // either availability-plan/time or availability-plan/day
        "timezone": "string"
      },
      "current-stock": {
        "quantity": "integer"
      },
      "private-data": "extended-data",
      "public-data": "extended-data",
      "metadata": "extended-data"
    },
    "customer": {
      "id": "uuid",
      "first-name": "string",
      "last-name": "string",
      "display-name": "string",
      "private-data": "extended-data",
      "public-data": "extended-data",
      "protected-data": "extended-data",
      "metadata": "extended-data"
    },
    "delayed-transition": {
      "run-at": "date"
    },
    "protected-data": "extended-data",
    "metadata": "extended-data"
  }
}

Inside the templates there are number of properties that you can utilize when customizing the templates. What properties are available is email specific and the following data structure describes what resources are available for each email template.

How to read the data structure

  • The type and content of the property can be deducted from the value of the property. E.g. {"marketplace": {"name": "string", "url": "string"}, is an object with properties name and url that are strings.
  • An object with property "any-of" describe an array of elements. For example, {"any-of": ["customer", "provider"]} is an array containing one of the values or both.
  • Properties of type "date" define a date object with properties "year", "month", "day", "hours", "minutes", "seconds" and "milliseconds". It's higly recommended that you use the available helpers described above to display dates.
  • Objects with the exact two propeties of "amount" and "currency" are of type money, and can be passed as is to money-amount helper.
  • Properties of type "extended-data" define an extended data object. Properties in such an object can have any valid JSON values, including JSON data structures.
  • The listing availability-plan property timezone is in TZ time zone database format, for example "Europe/Berlin". It is only available for plans with type availability-plan/time.
  • Remember to traverse the context properly. For example, in "transaction-transition" "payin-total" is nested under "transaction". This means that the correct way to refer to that is transaction.payin-total or using the builtin with helper.

Can't find what you're looking for?

Reach out to our support team by email, or consult the Sharetribe Developer Community at Sharetribe Developers Slack Channel. You can also contact our support team through the chat widget in Console.