A fallback value is the text that appears in place of a merge tag when the corresponding variable is not provided in the send request. Without fallback values, an unprovided variable renders literally — so a recipient would see "Hi {{first_name}}," instead of a natural greeting. This article explains how to set fallbacks at multiple levels and how to choose good fallback values.
Why Missing Variables Happen
- Incomplete data in your database — some users may not have provided their first name during sign-up.
- API integration gaps — a new developer forgot to include a variable in the send payload.
- Partial data for some recipients — you are sending to a mix of old and new subscribers where old records lack certain fields.
- Optional variables — a variable that only applies to some recipients (e.g. a discount code that not everyone qualifies for).
Levels of Fallback Values
| Level | Where Set | Priority | Best For |
|---|---|---|---|
| Template default | MigoSMTP template settings → Variable Defaults | Lowest — used when no value provided anywhere | Common variables used in many templates (first_name, currency) |
| API-level default | In the send request alongside recipient-specific variables | Middle — overrides template default; used when recipient has no value | Campaign-specific defaults (e.g. default discount amount for a campaign) |
| Recipient-level value | In the variables object per recipient in the send request |
Highest — always wins over defaults | Actual personalised data for each recipient |
Setting Template-Level Fallbacks
- Open your template in the MigoSMTP editor.
- Click Template Settings or Variables tab.
- MigoSMTP automatically lists all variables detected in your template.
- For each variable, enter a Default Value in the provided field.
- Save the template.
Setting API-Level Fallbacks
Use the default_variables field in your bulk send request to provide fallbacks that apply to any recipient who does not have that variable set:
POST /v1/email/send/bulk
{
"from": "newsletter@yourcompany.com",
"template_id": "weekly-digest",
"default_variables": {
"first_name": "there",
"currency": "₹",
"discount_percent": "10",
"cta_text": "View Offer"
},
"recipients": [
{
"to": "rahul@example.com",
"variables": { "first_name": "Rahul", "discount_percent": "15" }
},
{
"to": "unknown@example.com"
// No variables — will use default_variables for all fields
}
]
}
In this example, Rahul gets "Hi Rahul," and a 15% discount. The recipient with no variables gets "Hi there," and a 10% discount from the default.
Choosing Good Fallback Values
| Variable | Good Fallback | Poor Fallback | Why |
|---|---|---|---|
| {{first_name}} | there | Customer / User | "Hi there," reads naturally; "Hi Customer," feels cold and robotic |
| {{company_name}} | your company | N/A | "We'd love to help your company grow" works; "N/A" looks like a bug |
| {{discount_percent}} | 10 | [discount] | A real number maintains the email's credibility; a placeholder looks unfinished |
| {{delivery_date}} | within 5–7 business days | TBD | Informative fallback is still useful to the recipient; "TBD" is meaningless |
| {{cta_url}} | https://yourcompany.com | # | A broken # link frustrates users; a homepage URL is at least functional |
Validating Variables Before Sending
Add a pre-send validation step in your application to catch missing critical variables before they reach recipients:
// Validation helper — Python
REQUIRED_VARS = ['first_name', 'order_id', 'order_total', 'tracking_url']
def validate_send_payload(recipients):
errors = []
for i, recipient in enumerate(recipients):
variables = recipient.get('variables', {})
missing = [v for v in REQUIRED_VARS if not variables.get(v)]
if missing:
errors.append({
'index': i,
'email': recipient['to'],
'missing': missing
})
if errors:
raise ValueError(f"Missing required variables: {errors}")
return True