# Mailchimp Transactional (Mandrill) — PHP Integration Demo

A guided walkthrough of the Mailchimp Transactional API in PHP.
Each page performs one API call, shows the code that made it, and
prints the raw request / response so you can learn the endpoint by
running it.

Target URL: https://dev.systems.elegantwork.co.za/test/

## Quick start

1. Upload every file in this folder to `/test/` on your server.
2. Open `setup.php` in a browser — it walks through getting an API key.
3. Paste the key into `config.php`.
4. Visit `01-ping.php` — if it returns `{"PING":"PONG!"}` you're wired up.
5. Walk through pages 2 → 8 in order.

## Files

| File | Purpose |
|------|---------|
| `config.php` | API key + default sender + optional recipient whitelist. |
| `lib.php` | The one `mandrill_call()` wrapper every page uses. |
| `header.php` / `footer.php` | Shared HTML shell and navigation. |
| `style.css` | Styling. No dependencies. |
| `index.php` | Landing page with step-by-step nav. |
| `setup.php` | How to enable Transactional and get an API key. |
| `01-ping.php` | `POST /users/ping` — validate the key. |
| `02-allowlist-list.php` | `POST /allowlists/list` — view allowlist. |
| `03-allowlist-add.php` | `POST /allowlists/add` — add an email. |
| `04-allowlist-delete.php` | `POST /allowlists/delete` — remove an email. |
| `05-send.php` | `POST /messages/send` — send a transactional email. |
| `06-templates-list.php` | `POST /templates/list` — list templates. |
| `07-templates-add.php` | `POST /templates/add` + `POST /messages/send-template`. |
| `08-stats.php` | `POST /users/info` + `POST /tags/all-time-series`. |

## Requirements

- PHP 7.4+ (uses typed function signatures and `curl_setopt_array`).
- cURL extension enabled (standard on virtually all hosts).
- A Mailchimp account with the Transactional add-on enabled (paid).
- A verified sending domain in the Mandrill dashboard if you want to
  actually send email (Step 5 onwards). You can manage the allowlist
  without this.

## Safety notes

- `config.php` contains your API key in plaintext. Don't commit it to
  a public repo. For production, move it into an environment variable
  or a file outside the web root.
- If you leave the demo on a public URL, set the
  `ALLOWED_TEST_RECIPIENTS` array in `config.php` so strangers can't
  use your verified domain to send mail to arbitrary recipients.
- All forms are POST-only and every API-key value is redacted in the
  displayed debug output, but the rendered JSON still echoes whatever
  you type — don't put real customer data into the forms.

## How the client wrapper works

The whole integration lives in one function in `lib.php`:

```php
function mandrill_call(string $endpoint, array $params = []): array {
    $params['key'] = MANDRILL_API_KEY;
    $ch = curl_init(MANDRILL_API_BASE . $endpoint);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS     => json_encode($params),
        CURLOPT_TIMEOUT        => 30,
    ]);
    // ...captures response, timing, errors, redacts key...
}
```

Every endpoint is the same pattern: `POST https://mandrillapp.com/api/1.0/<endpoint>`
with a JSON body that includes `"key"`. No headers, no OAuth, no query string.

## Further reading

- Full API reference: https://mailchimp.com/developer/transactional/api/
- Webhooks (for delivery/open/click/bounce events):
  https://mailchimp.com/developer/transactional/api/webhooks/
- Quick-start guide:
  https://mailchimp.com/developer/transactional/guides/quick-start/