// e-commerce and billing
Via APIRecurly email verification with pingutil
Recurly drives renewals and dunning by email, so an account created with a mistyped or throwaway address is revenue you cannot recover when the card fails. A handler for the new account webhook fetches the account, verifies its email with pingutil and stores the result in a custom field, so billing ops can fix addresses before the first failed payment.
Where it connects: Recurly JSON webhooks (new account notification) plus account custom fields via the Recurly API v3
What goes wrong without it
- Dunning emails go to an address with a typo and the subscription lapses without the customer ever hearing about it.
- Our promo-code trials get claimed again and again by temp-mail accounts.
- We cannot report which accounts have unreachable billing emails until they bounce.
What you can do with Recurly and pingutil
Store the result on the account
Create an account custom field such as pingutil_status in Recurly, then set it from your webhook handler so it shows on the account page and in exports.
Review promo abuse
Accounts with a disposable or randomized address that redeemed a coupon are easy to find and review before the trial converts.
Fix addresses before the first renewal
For invalid results or a did_you_mean suggestion, prompt the customer in your app to correct their billing email.
Set it up
- 1
Create an API key in the pingutil dashboard and a Recurly private API key.
- 2
Define an account custom field in Recurly (for example pingutil_status) so the API accepts it.
- 3
Add a JSON webhook endpoint in Recurly with the new account notification enabled.
- 4
Verify the recurly-signature header (timestamp plus HMAC-SHA256 of timestamp, a dot and the raw body), respond 200, then fetch the account by account_code.
- 5
Call pingutil /v1/verify and update the account custom field with the Recurly client.
import express from 'express';
import crypto from 'node:crypto';
import recurly from 'recurly';
const client = new recurly.Client(process.env.RECURLY_API_KEY);
const app = express();
function validSignature(header, body) {
const [timestamp, ...sigs] = (header || '').split(',');
const expected = crypto.createHmac('sha256', process.env.RECURLY_WEBHOOK_KEY)
.update(timestamp + '.' + body).digest('hex');
return sigs.some((s) => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
}
app.post('/webhooks/recurly', express.raw({ type: 'application/json' }), (req, res) => {
if (!validSignature(req.get('recurly-signature'), req.body.toString('utf8'))) return res.sendStatus(401);
res.sendStatus(200);
const n = JSON.parse(req.body.toString('utf8'));
if (n.object_type === 'account' && n.event_type === 'created') {
checkAccount(n.account_code).catch(console.error);
}
});
async function checkAccount(accountCode) {
const account = await client.getAccount('code-' + accountCode);
if (!account.email) return;
let result;
try {
const res = await fetch('https://pingutil.com/v1/verify', {
method: 'POST',
headers: { authorization: 'Bearer ' + process.env.PINGUTIL_KEY, 'content-type': 'application/json' },
body: JSON.stringify({ email: account.email }),
signal: AbortSignal.timeout(30000),
});
if (!res.ok) return; // fail open
result = await res.json();
} catch {
return;
}
await client.updateAccount(account.id, {
customFields: [{ name: 'pingutil_status', value: result.status }],
});
}
app.listen(3000);What to do with each result
| pingutil result | Action in Recurly |
|---|---|
| status: "invalid" | Set the custom field and ask the customer to update their email before the first renewal. |
| did_you_mean is set | Show the suggestion in your app account page. |
| checks.disposable: true | Review coupon redemptions on the account before the trial converts. |
| status: "risky" or "unknown" | Record only. |
Limits to plan for
- Recurly JSON webhooks identify the account but you fetch the full account, including email, from the API. That is one extra call per event.
- The custom field must exist in Recurly before the API will accept it.
- Recurly retries a webhook after an error response and stops after ten failed attempts, so respond 200 before calling pingutil.
Recurly documentation
- docs.recurly.com/recurly-subscriptions/docs/webhooks
- docs.recurly.com/recurly-subscriptions/v2.29/docs/signature-verification
- developers.recurly.com/reference/webhooks
Recurly is a trademark of its owner. This integration uses Recurly's documented extension points; it is not an official Recurly app.
Common questions
- Do I need the JSON format for this?
- Yes. Recurly signs JSON webhooks with the recurly-signature header. XML webhooks are not signed the same way.
- Can I check emails captured by Recurly.js before the account exists?
- Yes. Your form collects the email before you call the Recurly API, so call your backend, which calls pingutil, at that point.
Stop bad addresses in Recurly 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 Recurly setup will receive.