<?php
$page_title = 'Step 3 — Add email to allowlist';
require 'header.php';
?>

<p>
    This is <strong>the endpoint from the docs page you shared</strong>:
    <span class="endpoint">POST /allowlists/add</span>. It takes an email
    address and an optional free-text comment, and allowlists that address
    so it can't be auto-rejected. If the address is currently on the
    <em>denylist</em>, the add call removes it from there automatically.
</p>

<h2>Try it</h2>

<form method="post">
    <label>Email address <small>(required)</small></label>
    <input type="email" name="email" required value="<?= h($_POST['email'] ?? '') ?>" placeholder="user@example.com">

    <label>Comment <small>(optional — note to yourself about why it's allowlisted)</small></label>
    <input type="text" name="comment" value="<?= h($_POST['comment'] ?? '') ?>" placeholder="VIP customer, previously bounced on a typo">

    <button type="submit" name="run">Add to allowlist</button>
</form>

<?php
if (isset($_POST['run']) && is_configured() && !empty($_POST['email'])) {

    // --- Build the params ------------------------------------
    // "email" is required. "comment" is optional — only include it
    // if the user actually typed something, to keep the request clean.
    $params = ['email' => trim($_POST['email'])];
    if (!empty($_POST['comment'])) {
        $params['comment'] = trim($_POST['comment']);
    }

    $result = mandrill_call('/allowlists/add', $params);
    // ---------------------------------------------------------

    if (!mandrill_is_error($result)) {
        $added = $result['decoded']['added'] ?? false;
        if ($added) {
            echo '<div class="callout ok"><strong>Added.</strong> '
               . h($params['email']) . ' is now on the allowlist.</div>';
        } else {
            echo '<div class="callout info"><strong>Already on the allowlist.</strong> '
               . 'The API returned <code>added: false</code>, which means the address '
               . 'was already allowlisted — not an error.</div>';
        }
    }

    render_debug($result);
}
?>

<h2>The call</h2>

<pre><code>$result = mandrill_call('/allowlists/add', [
    'email'   =&gt; 'user@example.com',
    'comment' =&gt; 'VIP customer',      // optional
]);

if ($result['decoded']['added']) {
    echo 'Newly added';
} else {
    echo 'Was already on the list';
}</code></pre>

<h2>Request parameters</h2>

<table>
<tr><th>Field</th><th>Required</th><th>Notes</th></tr>
<tr><td><code>key</code></td><td>yes</td><td>Your API key. Added automatically by the wrapper.</td></tr>
<tr><td><code>email</code></td><td>yes</td><td>The address to allowlist.</td></tr>
<tr><td><code>comment</code></td><td>no</td><td>Free-text note. Shown in the <code>detail</code> field when you list the allowlist.</td></tr>
</table>

<h2>Response shape</h2>

<pre><code>{
    "email": "user@example.com",
    "added": true
}</code></pre>

<p>
    <code>added: true</code> means it's new. <code>added: false</code> means it
    was already there — both are successful HTTP 200 responses, so check the
    <code>added</code> field specifically if you care which it was.
</p>

<p><a href="04-allowlist-delete.php">→ Next: remove an email from the allowlist</a></p>

<?php require 'footer.php'; ?>
