Error Guide

Error: sendgrid substitutions not working

What's Causing This Error

Substitution tags will work in the Subject line, body of the email, and in Unique Arguments.

They will not function properly if:

  • Substitution tags will work in the email subject line, body, and unique arguments.
  • The number of nested substitutions exceeds four.
  • Inside your substitution tags use spaces, such as %your name%
  • Substitution tags are nested within substitutes.

Here's How To Resolve It

  • The substitute values must be a collection of key/value pairs, with all values being strings.
  • The library you use to establish your SMTP connection, the language you're writing your code in, and any intermediary mail servers through which your servers will deliver mail can all influence the way you format your substitution tags.
  • You are limited to 10,000 substitutions.
  • Dse string type only.
  • Avoid having spaces between substitution tag names.
  • Avoid nesting tags within substitutions.

Other Common SendGrid Errors (and Solutions)

View all errors

Multichannel Notifications Platform for SaaS

Products

Platform

Integrations

Customers

Blog

API Status

Subprocessors


© 2025 Courier. All rights reserved.