Templates | Reggio Digital developer docs

Send a saved email template through the Reggio Digital API and fill in its variables from your own data.

A template keeps the wording and design of a message in the dashboard, so the business can change a receipt without anyone touching code. Your application sends the template's identifier and the values to fill in.

Creating one

Templates are built and published in Email templates in the dashboard. Each template has an identifier, a UUID, which you copy from its page. Only the published version sends: saving a draft changes nothing for live sends until someone chooses Publish.

Sending a template

Send template_id and variables in place of subject, html and text:

curl -X POST https://reggiodigital.com/api/v1/emails \
  -H "Authorization: Bearer $REGGIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "from": "hello@yourdomain.com",
      "to": [
          "success@simulator.amazonses.com"
      ],
      "template_id": "COPY_YOUR_TEMPLATE_IDENTIFIER",
      "variables": {
          "customer_name": "Alex",
          "order_number": "1042",
          "total": "$42.00"
      }
  }'

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.reggio.key'))
    ->acceptJson()
    ->post('https://reggiodigital.com/api/v1/emails', [
        'from' => 'hello@yourdomain.com',
        'to' => [
            'success@simulator.amazonses.com',
        ],
        'template_id' => 'COPY_YOUR_TEMPLATE_IDENTIFIER',
        'variables' => [
            'customer_name' => 'Alex',
            'order_number' => '1042',
            'total' => '$42.00',
        ],
    ]);

if ($response->failed()) {
    throw new RuntimeException($response->json('error.message'));
}

$body = $response->json();

$payload = [
    'from' => 'hello@yourdomain.com',
    'to' => [
        'success@simulator.amazonses.com',
    ],
    'template_id' => 'COPY_YOUR_TEMPLATE_IDENTIFIER',
    'variables' => [
        'customer_name' => 'Alex',
        'order_number' => '1042',
        'total' => '$42.00',
    ],
];

$ch = curl_init('https://reggiodigital.com/api/v1/emails');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('REGGIO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body = json_decode((string) curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

if ($status >= 400) {
    throw new RuntimeException($body['error']['message']);
}

const response = await fetch("https://reggiodigital.com/api/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REGGIO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "from": "hello@yourdomain.com",
      "to": [
          "success@simulator.amazonses.com"
      ],
      "template_id": "COPY_YOUR_TEMPLATE_IDENTIFIER",
      "variables": {
          "customer_name": "Alex",
          "order_number": "1042",
          "total": "$42.00"
      }
  }),
});

const body = await response.json();

if (!response.ok) {
  throw new Error(body.error.message);
}

The template supplies the subject and both bodies. Sending subject, html or text alongside template_id is refused with a 422, and so is sending variables without a template.

Templates work in batches and scheduled sends too. When we accept a scheduled or batch send, we fill the template in and keep that finished message, so publishing a new version afterwards does not change mail you have already handed us.

Variables

In the template, a variable is written as {{ customer_name }}. In the request, it is a key in variables:

"variables": { "customer_name": "Alex", "order_number": "1042", "total": "$42.00" }

Names are case sensitive. Up to 50 per message.
Each variable has a type set in the template. Text takes text or a number, Number takes a number, and Web address takes a complete http:// or https:// address.
A variable can be required, or optional with a default. A missing optional value uses its default. The preview values in the editor are never used for real sends.
Values are always treated as text, never as markup, so a value cannot inject HTML into the message.
The finished subject is limited to 255 characters and cannot contain a line break.

A missing required value, a name the template does not define, or a value of the wrong type is refused with a 422. error.fields names the variable, as in variables.order_number, or emails.0.variables.order_number in a batch.

Errors you are likely to see

Status	Why
`422`	The template does not exist on this account, has never been published, or a variable is missing or invalid.
`402`	The account no longer has a transactional email plan.

Everything else behaves as for any send. See errors, limits and headers.