Skip to content

Create and manage API keys

Create an API key for a tool or a script, choose a live or a test key and the checks it runs, then revoke it the moment the tool no longer needs it.

An API key lets a tool verify addresses on your account without your password: an automation platform, a signup form, a script or your own app. Each key carries its own checks and permissions, so you can give each tool its own key and revoke one without touching the others.

To connect an AI assistant such as Claude or ChatGPT, use an agent instead: see Connect an AI assistant.

Create a key

  1. In PricklyMails

    Open the API keys page

    In the sidebar, under Developer, open API keys and click New key.

  2. In PricklyMails

    Name the key

    Give it a name that says where it is used, such as the name of the tool, then click Next. A name holds up to 64 characters: letters, digits, spaces, hyphens and underscores. Leave Expires on empty for a key that never expires, or pick a date up to 364 days ahead for a key that stops working on its own, such as a key lent to a contractor. To change it later, open the key and set a new date under Expiry: a later date brings an expired key back. Past that date the key is refused like a revoked one, and the list shows it as Expired.

  3. In PricklyMails

    Choose its environment and checks

    Pick Live or Test, as explained below. Under Enabled checks, keep the checks each request should run: each one shows its cost in tokens, and the total per email sits under the list. Under Scopes, a new key may verify one address, verify a list and read results; untick what the tool does not need. Then click Next.

  4. In PricklyMails

    Review and create

    The last step sums up the key, with its Total cost per email. Click Finish.

  5. In PricklyMails

    Copy the key

    Under Your new API key, copy the key and paste it into your tool, or store it in a password manager. Click I have saved it, which copies it once more and closes the window.

Warning

This is the only time the key is shown: we keep only a fingerprint of it, so nobody can show it to you again. If you lose it, revoke it and create a new one.

How many keys you can create, and how many requests a key may send per minute, depend on your plan: see the plans. A key's limit shows in the Rate limit column, and it follows your plan when the plan changes.

Live and test keys

A live key starts with pm_live_. It runs real verifications and spends tokens.

A test key starts with pm_test_. It never contacts a mail server and never spends a token: it answers from the start of the address, so you can check that your tool handles each kind of result before going live.

What a test key returns, by the start of the address
The address starts withVerdictReasonRecommendation
valid ValidMailbox exists Send
invalid InvalidMailbox does not exist Remove
catchall RiskyDomain accepts any address Review
disposable RiskyDisposable address Remove
role RiskyGeneric address Review
Anything else ValidMailbox exists Send

A test result has the same shape as a live one, so your tool reads both the same way. Once everything works, swap in a live key.

The checks a key runs

Every request made with a key runs the checks it enables, and costs the sum of their tokens. A check you leave out is skipped and not billed.

  • Address format always runs.
  • Ticking Mailbox exists also ticks Domain receives email, which it needs.
  • Domain accepts any address (catch-all) needs both of them.
  • A check marked Upgrade needs a higher plan.

The dashboard sets a key's checks when you create it. A developer can also ask for other checks on a single request, as the verification docs explain.

Click a key's row to open Key details: its scopes, its enabled checks, its Rate limit, how many Requests it made, and when it was Last used.

Revoke a key

Click the key's row to open Key details, click Revoke, then Revoke key. The key stops working immediately, and this cannot be undone: a tool still using it is refused. It stays in the list with the status Revoked.

Revoke a key when you stop using a tool, or as soon as you think it leaked. To replace a key without a break, create the new one first, put it in the tool, then revoke the old one.

For developers

The API keys and Authentication docs cover the requests: how to send the key, how to create and revoke keys through the API, and the test mode.

Common questions

Can I see a key again after closing the window?

No. We keep only a fingerprint of the key, never the key itself: create a new key and revoke the one you lost.

Does a test key use my tokens?

No. A test key never spends a token and never contacts a mail server, whatever address you send.

What happens to my keys if I delete my account?

They all stop working at once, along with your agents.

  • Verify your first address

    Create your PricklyMails account, confirm it with the code we email you, then verify a first address in the dashboard and read the answer it gives.

  • Read a verification result

    What the verdict, the recommendation, the score and the reason of a PricklyMails result mean, and what to do with each address before you send.

  • Verify a whole list

    Verify a list in one batch: upload or paste it, follow its progress, read and download the report, and see what happens to duplicates and invalid lines.

  • Tokens and plans

    How billing works: tokens spent check by check, what each check costs, plans and top-ups, tokens that never expire, and what is refunded or never billed.

  • Keep your account secure

    Set a strong password, turn on two-factor authentication, sign out the devices you do not recognize, and know which security emails your account sends you.

  • Connect an AI assistant

    Let Claude, ChatGPT, Cursor or another MCP client verify addresses for you: create an agent, add the PricklyMails server, approve it, and revoke it anytime.

  • Your data and how long we keep it

    What happens to the addresses you verify, what the shared cache and your own browser keep, and what remains once you delete your account, and for how long.

Check your list before your next send.

1,000 tokens free when you sign up, no credit card. After that, you only pay for answers.