Letterby Docs

Connect your newsletter

Connect Beehiiv, Kit, Mailchimp or Ghost so Letterby can add subscribers and check engagement.

Letterby adds new subscribers to your list and reads opens and clicks to check that they are real readers. For that it needs an API key from your email provider.

You need the owner or admin role. Open Publication settings, then Email provider.

A publication has one provider and it cannot be changed later. To switch, contact support.

What to paste

FieldWhere to find it
Beehiiv API KeyAn API key from your Beehiiv account.
Beehiiv Publication IDThe v2 id. It starts with pub_.

Select Connect. Letterby checks the key right away and tells you if it is wrong.

Keep open tracking on

Screening relies on opens and clicks. If open tracking is off in your provider, Letterby cannot tell whether a new subscriber reads your emails.

When tracking is off on your recent sends, your offers pause and you get an email. They resume once tracking is back on.

Status

BadgeMeaning
ConnectedThe key works. Letterby checks it every day.
UnverifiedThe key has not been checked yet.
Credential invalidThe key stopped working. Your offers are paused.

When a key stops working

Your active offers pause, and owners and admins get an email.

Subscribers who already confirmed are held for up to 30 days.

Select the connected provider tile and enter a new key for the same account and list.

Your offers resume and the held subscribers are added to your list.

A provider outage does not count as a broken key. Letterby waits and retries.

Live updates

When you connect, Letterby registers a webhook in your provider so unsubscribes reach us at once. Every day it checks that the webhook still exists and sets it up again if it was removed. If that fails, owners and admins get an email asking to enter the API key again. Billing is not affected: subscribers are always checked before a charge.

Errors

MessageFix
This API key is not validCopy the key again. Check that it was not revoked.
Publication not found for this API keyUse the v2 publication id from the same Beehiiv account.
Audience ID not found for this API keyCheck the audience id and that the key can read it.
API key is missing its data-center suffixCopy the whole Mailchimp key, including the -us21 part.
Admin URL rejectedUse your site's public https:// address.
Use the same list as beforeA new key must belong to the same account and list.

On this page