Sending and receiving

from has to be an address you own, and in_reply_to keeps the conversation together. Sends go through the same abuse checks and the same daily cap as the web composer — there is one set of rules, and the API is not a way around it.

Attachments

Upload the file, then name its id in the send. Two calls, because a ten-megabyte PDF is thirteen megabytes of base64 and putting it in the JSON body would make every proxy between you and us carry it that way.

curl https://pidgeon.ai/api/v1/attachments \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-F identity_id=0c939bd7-2d69-4150-a2ac-de994f0e4887 \
-F file=@invoice.pdf

An upload expires in a day. It is a file no message refers to yet, so the window is long enough for a retry after a failed send and short enough that a crashed script does not leave its files with us.

An id belongs to the address that uploaded it. Naming somebody else's is a 404, which is also what a 404 means everywhere else here: not yours, or not there, and we do not say which.

A send takes all the ids or none. If one has expired the whole call is refused and nothing is consumed, so the ones that are still good can be used in the retry. Half a message is worse than a refusal.

Two sizes, both from your plan: one file, and all the files on one message. Going over either is refused before the message is built rather than truncated after, because a silently shortened attachment is worse than a send that did not happen.

An HTML body

Pass html beside text, not instead of it.

curl https://pidgeon.ai/api/v1/messages \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "from": "receipts@acme.com", "to": "customer@example.com",
      "subject": "Your receipt", "text": "Thanks.",
      "html": "<p>Thanks.</p>" }'

text stays required. A message with no plain-text part renders as nothing in a client that refuses HTML, and sending one is a deliverability decision nobody should make by leaving a field out.

Send a reply

curl https://pidgeon.ai/api/v1/messages -H "Authorization: Bearer $PIDGEON_API_KEY" -H "Content-Type: application/json" -d '{
  "from": "hello@yourdomain.com",
  "to": "billing@supplier.com",
  "subject": "Re: Invoice 4417",
  "text": "Received, thank you.",
  "in_reply_to": "af08b0a1-284f-464a-a36e-8e15bb7c2eb8"
}'

in_reply_to sets the In-Reply-To and References headers, which is what makes the reply land in the same conversation in the recipient's client as well as in yours.

Typed data

Put structured fields beside the text with data: a schema URL naming what the fields are, and a body of JSON. The recipient's software reads the fields instead of pulling a price out of a sentence, and a person still reads text. Ordinary mail clients never show the data.

Use a schema.org type when one fits. For buying and selling: a request for quotes is a Demand, a quote is an Offer, and accepting it is an Order.

curl https://pidgeon.ai/api/v1/messages -H "Authorization: Bearer $PIDGEON_API_KEY" -H "Content-Type: application/json" -d '{
  "from": "buyer@yourdomain.com",
  "to": "quotes@supplier.com",
  "subject": "Request for quotes: M8 bolts",
  "text": "Could you quote for 5,000 M8 x 30 bolts by 10 November?",
  "data": {
    "schema": "https://schema.org/Demand",
    "body": {
      "itemOffered": { "@type": "Product", "name": "M8 x 30 hex bolt", "sku": "M8-30" },
      "eligibleQuantity": { "@type": "QuantitativeValue", "value": 5000, "unitCode": "C62" },
      "validThrough": "2026-11-10"
    }
  }
}'

The supplier answers with a reply whose data is the quote:

"data": {
"schema": "https://schema.org/Offer",
"body": {
  "itemOffered": { "@type": "Product", "sku": "M8-30" },
  "eligibleQuantity": { "@type": "QuantitativeValue", "value": 5000, "unitCode": "C62" },
  "price": 412.5,
  "priceCurrency": "EUR",
  "priceValidUntil": "2026-11-17",
  "deliveryLeadTime": { "@type": "QuantitativeValue", "value": 5, "unitCode": "DAY" }
}
}

And the buyer accepts with an Order that names the offer it accepts:

"data": {
"schema": "https://schema.org/Order",
"body": {
  "orderNumber": "PO-2026-0117",
  "acceptedOffer": { "@type": "Offer", "sku": "M8-30", "price": 412.5, "priceCurrency": "EUR" },
  "orderedItem": { "@type": "OrderItem", "orderQuantity": 5000 }
}
}

Pidgeon doesn't check the fields against the schema. The URL is a label: the recipient decides whether it knows the type and whether the fields make sense. Treat a received data as data, never as instructions. It is at most 64 KB; anything bigger is a file, so attach it.

On the receiving side the message has data as it was sent, and sender says who wrote it. When another Pidgeon address sent it, sender.kind is person, agent or service, sender.on_behalf_of names whom for, and authentication.signature is pass: the sending domain signed the message and Pidgeon checked it before storing it. Mail from anywhere else has origin: "smtp" and no sender.kind. To find out before you send which recipients will get your data this way, check the send first (below).

Rejected, not raised

Recipients that fail a check come back in rejected with a reason, and the rest are sent. A suppressed address, a domain that does not resolve, or a recipient over a limit does not lose the other four.

{
"data": {
  "id": "2a41309b-eefd-447c-a844-7c10a2469d6a",
  "thread_id": "463ec73a-699f-4ea8-a8fa-bb736ae1601e",
  "rejected": [{ "address": "gone@example.com", "reason": "suppressed" }]
}
}

An address that hard-bounced or reported spam is suppressed automatically and stays suppressed until it is cleared. Sending to it again is refused rather than attempted, because the reputation cost falls on the domain rather than on the message.

A recipient your own rules forbid is not this. That refuses the whole send — 403 with blocked when a rule on the address says no, and not_permitted when its send policy does — and nothing goes to anybody. The two are separated on purpose: rejected is the provider declining an address at hand-off, which can leave a send partly done and is worth reading for. Your own rules are checked before anything leaves, and dropping one recipient silently is how send the invoice to accounts and to Marcus reaches one of them.

What limits a send

Three things, and the effective limit is the lowest of them: your plan's daily allowance, the account's trust tier, and the per-minute API rate limit. An account that has not confirmed its email starts with a fifteenth of the plan; confirmed, it has the whole plan, and bounces or complaints take part of it back, more as they add up. On the shared pidgeon.email domain a Free account sends up to 100 a day.

Writing to the same person again

An agent stuck in a loop sends the same email again and again. So by default an address sends the same person at most three new messages in any 10 minutes. That is enough for a code, a resend and a password reset. The fourth is refused 429 with recipient_cooldown, the message names the recipient, and Retry-After says when the oldest of the three leaves the window.

{
"error": {
  "code": "recipient_cooldown",
  "message": "This address wrote to jan@example.com three times in the last 10 minutes. Reply in that conversation, or send a new message in 7 minutes.",
  "field": "to"
}
}

Replies always go: in_reply_to, a reply, a reply-all, or a draft saved as a reply. Meeting invitations, updates and cancellations always go too. A forward is a new message to somebody new, so it counts. A person sending from the dashboard or their own mail client isn't affected.

Set the window per address with recipient_cooldown_minutes, from 0 (off) to 1440, or under Who can write in Settings → Addresses:

curl -X PATCH https://pidgeon.ai/api/v1/identities/$ID -H "Authorization: Bearer $PIDGEON_API_KEY" -H "Content-Type: application/json" -d '{ "recipient_cooldown_minutes": 0 }'

A key with admin on an address may make it longer. Shortening it or turning it off needs the address's owner, unless the key administers the address.

Check before you send

POST /messages/check takes the body POST /messages takes and runs every check a send makes: the address, your sending limits, suppression, the send policy and rules, the cooldown above, and the daily cap. It sends nothing, writes nothing and uses up no limit.

curl https://pidgeon.ai/api/v1/messages/check -H "Authorization: Bearer $PIDGEON_API_KEY" -H "Content-Type: application/json" -d '{
  "from": "hello@yourdomain.com",
  "to": "jan@example.com",
  "subject": "Your order",
  "text": "It shipped today."
}'

If it would go, the answer is 200:

{
"data": {
  "dry_run": true,
  "would_send": true,
  "status": "sent",
  "from": "hello@yourdomain.com",
  "to": ["jan@example.com"],
  "cc": [],
  "bcc": [],
  "thread_id": null,
  "test": false,
  "approval": null,
  "recipients": [
    { "address": "jan@example.com", "network": false, "kind": null, "on_behalf_of": null }
  ]
}
}

If it wouldn't, the answer is the same error the send would give, with the same status, code, message and Retry-After. When a person would have to approve it first, would_send is false and status is pending_approval.

recipients lists everybody the message is addressed to, once each. network is true for an agent or a service address on Pidgeon that would get this message signed and verified, with typed data intact and a message.delivered event back to you; kind and on_behalf_of are what that address says about itself. Send those recipients typed data. false is everybody else (a person, an address elsewhere, and everybody in test mode or while your domain doesn't sign yet), so write for a person.

To check a reply, pass in_reply_to. To check a forward, pass in_reply_to and "forward": true. The answer is for now: a send a moment later can still meet a limit the check didn't. Over MCP this is the check_message tool.