Skip to content

// email marketing and newsletters

Via API

EmailOctopus email verification with pingutil

EmailOctopus sends through your own Amazon SES or its own infrastructure, and either way bounces from fake signups count against you. A contact.created webhook delivers new contacts in batches, your endpoint checks them with pingutil's batch endpoint, and the EmailOctopus API unsubscribes invalid contacts and tags risky ones.

Where it connects: EmailOctopus webhooks (contact.created event, signed with EmailOctopus-Signature) plus the API PUT /lists/{list_id}/contacts/{contact_id} endpoint

What goes wrong without it

  • We send through our own SES account, and a few bad signups pushed our bounce rate close to the level where AWS starts asking questions.
  • Our form has no captcha and random addresses keep appearing in the list.
  • We want contacts tagged by quality so campaigns can skip the doubtful ones.

What you can do with EmailOctopus and pingutil

  • Verify webhook batches together

    EmailOctopus buffers events for up to a minute and sends up to 1,000 per request, so the handler verifies addresses 50 at a time with /v1/verify/batch.

  • Unsubscribe invalid contacts

    Invalid and disposable addresses are set to unsubscribed on the list, so no campaign goes to them.

  • Tag risky contacts

    Catch-all and unknown results get a pingutil-risky tag that you can exclude when you build a campaign.

Set it up

  1. 1

    Create an EmailOctopus API key and a pingutil API key.

  2. 2

    Deploy the endpoint below on HTTPS.

  3. 3

    In the EmailOctopus dashboard, create a webhook for contact.created events, optionally excluding events from imports, and copy its secret.

  4. 4

    Add a test contact through a form and check the tag or status on the contact.

PHP endpoint for EmailOctopus contact.created webhooks
<?php
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('EO_WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_EMAILOCTOPUS_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

http_response_code(200);
if (function_exists('fastcgi_finish_request')) fastcgi_finish_request();

// The body is a JSON array of up to 1000 events.
$contacts = [];
foreach (json_decode($raw, true) ?: [] as $e) {
    if (($e['type'] ?? '') === 'contact.created') {
        $contacts[$e['contact_email_address']] = [$e['list_id'], $e['contact_id']];
    }
}

function http_json(string $method, string $url, array $headers, array $body, int $timeout): ?array {
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => $timeout,
        CURLOPT_HTTPHEADER => array_merge($headers, ['Content-Type: application/json']),
        CURLOPT_POSTFIELDS => json_encode($body),
    ]);
    $out = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    return ($out !== false && $code < 300) ? json_decode($out, true) : null;
}

foreach (array_chunk(array_keys($contacts), 50) as $chunk) {
    $res = http_json('POST', 'https://pingutil.com/v1/verify/batch',
        ['Authorization: Bearer ' . getenv('PINGUTIL_KEY')], ['emails' => $chunk], 60);
    if ($res === null) break; // quota or outage: fail open, leave contacts as they are

    foreach ($res['results'] as $v) {
        [$listId, $contactId] = $contacts[$v['input']];
        $update = ['tags' => ['pingutil-' . $v['status'] => true]];
        if ($v['status'] === 'invalid') $update['status'] = 'unsubscribed';
        http_json('PUT', "https://api.emailoctopus.com/lists/$listId/contacts/$contactId",
            ['Authorization: Bearer ' . getenv('EO_API_KEY')], $update, 15);
    }
}

What to do with each result

pingutil resultAction in EmailOctopus
status: "invalid"PUT status "unsubscribed" and tag pingutil-invalid.
reason: "disposable_domain"Invalid path; the tag shows how many throwaway signups the form collects.
status: "risky"Tag pingutil-risky and exclude it from campaigns where bounces matter.
status: "unknown"Tag pingutil-unknown and re-check before the next large send.

Limits to plan for

  • EmailOctopus allows 2 webhook endpoints per team and retries unreachable endpoints up to 9 times over about 10 days, so process events idempotently by their id.
  • Imports can create thousands of contact.created events. Exclude import events in the webhook settings, because pingutil checks up to 300 addresses per account per day (3,000 a month). Those are Free plan limits; Enterprise has custom limits.
  • Catch-all servers accept any address, so those contacts stay risky instead of valid.

EmailOctopus documentation

EmailOctopus is a trademark of its owner. This integration uses EmailOctopus's documented extension points; it is not an official EmailOctopus app.

Common questions

Why use the batch endpoint here?
EmailOctopus groups events into one request, so checking 50 addresses per pingutil call keeps you well under the 60 requests a minute limit.
Can I clean an existing EmailOctopus list?
Export the list, run it through /v1/verify/batch or the dashboard CSV upload, then update the invalid contacts with the same PUT call or re-import them as unsubscribed.

Stop bad addresses in EmailOctopus today

Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your EmailOctopus setup will receive.