Search the docs

Find a page, a section, or an endpoint.

Sign inGet started

Quickstart

A key, an address and a sent message, in about five minutes.

An address is a resource. Mail arriving is an HTTP request. Everything here works on a free account.

You already have an address. Signing up gives you one on our shared domain, with a welcome message in it — no DNS, no card, nothing to wait for. Use it for everything below.

A domain of your own is an upgrade rather than a first step: it is what makes mail come from you, and it is its own page when you want it.

Get a key

Keys are created in Developers → API keys inside the app. A key is shown once; afterwards the list holds a prefix and nothing else, so store it where you store the rest of your secrets.

export PIDGEON_API_KEY=pgn_live_…

Install a client

cURL needs nothing. The TypeScript client runs on Node 18 or later, and the Python one on Python 3.11 or later; both are generated from the same API, so an operation has the same name in each.

# Nothing to install.

Ask what you own

The shortest call that proves the key works. It lists the addresses on the account, which is also how you find the id you will need later — including the one signup gave you.

curl https://pidgeon.ai/api/v1/identities -H "Authorization: Bearer $PIDGEON_API_KEY"

Send one

from has to be an address this account owns — the one signup gave you, or one on a domain you have since verified. Everything else is what you would expect.

curl https://pidgeon.ai/api/v1/messages -H "Authorization: Bearer $PIDGEON_API_KEY" -H "Content-Type: application/json" -d '{
  "from": "hello@yourdomain.com",
  "to": "someone@example.com",
  "subject": "First one",
  "text": "It works."
}'

A 201 comes back with the message id and the thread it landed in. Recipients that fail the send guard are returned in rejected rather than raised — one bad address does not lose the other four.

Then receive one

Sending is the half most APIs do. Webhooks are the other half, and they are the reason this product exists: mail arriving at hello@yourdomain.com becomes an HTTP request to your code within seconds, with nothing to poll.

That is the next page, and it is the one worth reading.