# Recipient

!!! info
    This page was generated by extracting information from a JSON Schema
    data file for the API.  It may be missing some information, or otherwise
    suggest approximate or placeholder values based on information in the
    schema file; this is due to limitations on how that data is extracted
    from the underlying Rust code and into the JSON Schema, and then again
    from there and into these docs.


This is an object value, with the following properties:


  * `email` - required `string` (`email`). The email address of the recipient

  * `metadata` - optional `object`. Per-recipient metadata key-value pairs. When non-empty, these are
    stored on the resulting message under the `extra` metadata key,
    accessible from Lua hooks via `msg:get_meta('extra')`.

  * `name` - optional nullable `string`. The optional displayable name of the recipient.
    This field will be set as the `name` field when
    processing template expansion.

  * `substitutions` - optional `object`. When using templating, this is the map of placeholder
    name to replacement value that should be used by the
    templating engine when processing just this recipient.
    
    The following substitutions are pre-defined:
    
    |Name|Value|Version|
    |----|-----|-------|
    |email|Populated from the recipient `email` field|Always|
    |name|Populated from the recipient `name` field|Always|
    |to_header|A suitable value for use in a `To:` header, constructed from the recipient `email` and `name` fields. eg: `"John Smith" <john.smith@mailbox-example.com>`|{{since('2026.04.09-ea3b2a9b', inline=True)}}|

### Examples
```json
{
  "email": "john.smith@mailbox-example.com",
  "metadata": {
    "campaign_id": "promo-2026-q2",
    "user_segment": "premium"
  },
  "name": "John Smith",
  "substitutions": {
    "age": 42,
    "gender": "male"
  }
}
```
