How to Create a Custom BeeHiiv Subscription Form with PHP

If you’re using BeeHiiv for email newsletters and want full control over how users subscribe from your WordPress site, you can skip third-party plugins and create your own custom solution.

This is exactly how I use it on my site, with a lightweight custom form and a direct connection to BeeHiiv’s API using PHP and cURL. It keeps things fast, flexible, and fully under my control.

In this post, we’ll walk you through creating a lightweight subscription form that communicates directly with the BeeHiiv API using PHP and cURL.

This guide is designed for developers who want a simple, secure, and fully customizable integration with BeeHiiv. No JavaScript dependencies. No plugins. Just clean PHP.

Step 1: Create the Subscription Form

Start by creating a file named subscribe-form.php in your theme folder. This will hold the HTML form used to collect the user’s email address:

<?php
$form_html = '<div class="home_form">
    <form class="subscribeForm" action="/wp-content/themes/your-theme/functions/subscribe.php" method="post">
        <input type="text" name="hp_email" style="display:none;">
        <input type="email" name="email" autocomplete="on" placeholder="youremail@gmail.com" required>
        <input type="submit" name="subscribe" value="Subscribe">
    </form>
</div>';

echo $form_html;
?>

This form includes a hidden honeypot field called hp_email to deter spam bots, along with the email input and a submit button.

Step 2: Handle the Form Submission

Now let’s create the script that receives the form data and sends it to BeeHiiv. This script should be placed in your theme’s functions directory (or another appropriate location) and named subscribe.php.

Its role is to validate the data, filter out bots, and send the email address to BeeHiiv’s API.

<?php
$apiKey = 'YOUR_BEEHIIV_API_KEY_HERE'; // Your private BeeHiiv API key

// Log errors to a file for debugging
function log_error($message) {
    file_put_contents('error_log.txt', date('Y-m-d H:i:s') . " - " . $message . "\n", FILE_APPEND);
}

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $email     = $_POST['email']    ?? null;
    $hp_email  = $_POST['hp_email'] ?? '';
    $publicationId = 'your-publication-id-here'; // Your BeeHiiv publication ID

    // Block bot submissions via honeypot field
    if (!empty($hp_email)) {
        log_error('Spam detected: honeypot field filled.');
        echo 'Failed!';
        exit;
    }

    // Check if email field is empty
    if (empty($email)) {
        log_error('Missing email address.');
        echo 'Missing email.';
        exit;
    }

    // BeeHiiv API endpoint for subscriptions
    $url = "https://api.beehiiv.com/v2/publications/$publicationId/subscriptions";
    $data = json_encode(['email' => $email]);

    // Initialize and configure cURL
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $apiKey
    ]);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

    // Send the request and read the response
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    // Handle API response
    if ($httpCode === 200 || $httpCode === 201) {
        echo 'Subscription successful!';
    } else {
        log_error("Subscription failed. HTTP code: $httpCode");
        echo 'Subscription failed. Please try again later.';
    }
} else {
    echo 'Invalid request method.';
}
?>

This script does the following:

• Checks if the request is POST: Prevents direct access or accidental GET requests.
• Validates the email: Skips empty or spammy submissions using a hidden honeypot field.
• Builds and sends a JSON request to BeeHiiv: Using cURL and the appropriate API headers.
• Handles the response: Outputs a success message or logs the issue to error_log.txt.

This server-side approach ensures your BeeHiiv API key stays secure and prevents spam with minimal overhead.

Step 3: Add the Form to Your Theme

To render the subscription form anywhere in your theme (such as your homepage or footer), include the subscribe-form.php file like this:

<?php get_template_part('subscribe-form'); ?>

Make sure the path to your subscribe-form.php file is correct. You can also include it directly into a template if you prefer.

Step 4: Test It

To test the form:

• Enter a valid email address in the input field.
• Submit the form.
• If successful, you’ll see the “Subscription successful!” message.
• If there’s an issue, it will be logged in error_log.txt in the same directory as subscribe.php.

Make sure your hosting server allows outbound requests to BeeHiiv’s API domain and has cURL enabled for this script to work correctly.

Final Notes

• Don’t forget to replace 'YOUR_BEEHIIV_API_KEY_HERE' and 'your-publication-id-here' with your actual BeeHiiv credentials.
• Ensure that subscribe.php is not publicly accessible or indexable via search engines.
• You can expand this further by adding AJAX submission or tracking user interactions.

For better performance and integration, you may also consider rate-limiting or logging IP addresses to further reduce bot spam. If you find a way to improve this method or have suggestions, feel free to share them in the comments of this post, I’d love to hear your thoughts.