Quickstart

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

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_…

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.

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

Send one

from has to be an address on a domain this account has 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.