# Overview

> What your own software can do with Reggio Digital: send email, keep a newsletter list in step, and hear about what happened.

Source: https://reggiodigital.com/developers

If someone who runs a business with us has sent you this link, this is where their software meets our platform. Everything here is plain HTTPS and JSON, with a key that belongs to their account.

## What you can build

**Send email from your own application.** Receipts, password resets, booking confirmations and anything else your software sends one person at a time. You post a message, we send it from the business's own verified domain, and you can ask afterwards what happened to it. Start with the [transactional email API](https://reggiodigital.com/developers/email). If the software you are connecting cannot make HTTP calls but has an SMTP setting, [send over SMTP](https://reggiodigital.com/developers/smtp) instead.

**Keep a newsletter list in step.** Add someone the moment they sign up in your shop or booking system, update their details, and take them off when they leave. Consent and confirmation emails work exactly as they do for the business's own signup forms. See the [subscriber API](https://reggiodigital.com/developers/newsletter), or [embed a signup form](https://reggiodigital.com/developers/signup-forms) if you only need the form.

**Hear about what happened.** Instead of asking over and over whether a message arrived, give us an address and we will tell your application when an email is delivered or bounces, when someone joins or leaves a list, and when mail arrives in the business's inbox. See [webhooks](https://reggiodigital.com/developers/webhooks).

**Make a WordPress site faster.** The [image optimizer plugin](https://reggiodigital.com/developers/image-optimizer) makes smaller copies of every image and serves them to browsers that can read them. There are also step by step guides for sending email from [Laravel](https://reggiodigital.com/developers/guides/laravel), [Node.js](https://reggiodigital.com/developers/guides/node) and [WordPress](https://reggiodigital.com/developers/guides/wordpress).

**Reading this with an AI coding tool?** Every page is also available as plain Markdown with its code written out. Start from [llms.txt](https://reggiodigital.com/llms.txt), or load [the whole set in one file](https://reggiodigital.com/llms-full.txt).

## For the business owner

You do not need to read the rest of this page. Forward the link to whoever builds or looks after your software, and let them know they will need a key from your dashboard. If you would rather we did the work, [get in touch](https://reggiodigital.com/contact) and we will make the change for you.

## Getting a key

1. Log in to the account the integration is for. If you do not have access, ask the account owner to invite you.
2. Open [Connected apps](https://reggiodigital.com/email/api/keys) and connect your application. Give it only the abilities it needs, and limit it to one sending domain if it only sends from one.
3. Copy the key into your application's environment, never into code that runs in a browser.

Each page here uses `rgo_your_key_here` and `hello@yourdomain.com` as stand-ins. The dashboard versions of these pages show the same examples filled in with the account's own key and verified sender:

- [Send API](https://reggiodigital.com/email/api) in the dashboard
- [Subscriber API](https://reggiodigital.com/newsletter/api) in the dashboard
- [Notify my app](https://reggiodigital.com/email/webhooks), where webhook addresses and signing secrets live

## The shortest possible example

This sends one email to a test address that never reaches a real inbox, so it is safe to run as it is once the from address is on a verified domain.

cURL:

```bash
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"
      ],
      "subject": "Your receipt",
      "html": "<p>Thanks for your order.</p>",
      "text": "Thanks for your order.",
      "tags": {
          "kind": "receipt",
          "order": "1042"
      }
  }'
```

Laravel:

```php
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',
        ],
        'subject' => 'Your receipt',
        'html' => '<p>Thanks for your order.</p>',
        'text' => 'Thanks for your order.',
        'tags' => [
            'kind' => 'receipt',
            'order' => '1042',
        ],
    ]);

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

$body = $response->json();
```

PHP:

```php
$payload = [
    'from' => 'hello@yourdomain.com',
    'to' => [
        'success@simulator.amazonses.com',
    ],
    'subject' => 'Your receipt',
    'html' => '<p>Thanks for your order.</p>',
    'text' => 'Thanks for your order.',
    'tags' => [
        'kind' => 'receipt',
        'order' => '1042',
    ],
];

$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']);
}
```

Node.js:

```js
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"
      ],
      "subject": "Your receipt",
      "html": "<p>Thanks for your order.</p>",
      "text": "Thanks for your order.",
      "tags": {
          "kind": "receipt",
          "order": "1042"
      }
  }),
});

const body = await response.json();

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

A `202` with an `id` means we accepted it. Read [errors, limits and headers](https://reggiodigital.com/developers/conventions) before you ship, so your code handles the answers that are not a `202`.

## Base address

Every call in these docs goes to:

```
https://reggiodigital.com/api/v1
```

The `v1` in the path is a promise: nothing under it will change in a way that breaks an integration written against these docs. New fields and new event types can appear, so write code that ignores what it does not recognise. A change that would break you ships under a new version instead of changing `v1`. Changes are listed in the [changelog](https://reggiodigital.com/developers/changelog).