Search the docs

Find a page, a section, or an endpoint.

Sign inGet started

Test mode

Every test mode endpoint, generated from the API's own schemas.

Simulate an inbound message (test keys only)

post/api/v1/test/inbound

Delivers a message to one of this **test key**’s addresses as though it had arrived from outside, through the real inbound pipeline — routing, sender rules, spam, the Firewall, threading, `message.received` and its webhooks — marked `test`. Pass `in_reply_to` with a message id to have it arrive as a reply in that thread, which is how a test plays the customer answering your agent. A live key gets `403`. The address must be one the key reaches at `send`. Nothing is sent to `from`, and the message counts against nothing on your plan.

Parameters

  • Idempotency-Keystring

    Any string unique to this attempt, reused on its retries. A repeat with the same key and the same request returns the first answer with `Idempotent-Replay: true` and does nothing — no second email. The same key with a different request is a `409`. Kept for 24 hours; a failure is not kept, so a retry after one runs.

Body

  • toemailrequired

    One of the addresses this test key reaches, at `send`.

  • fromemailrequired

    Who it is from. Any address: nothing is sent to it.

  • from_namestring
  • subjectstring

    Left off a reply, where the thread already has one.

  • textstring

    The plain-text body. Send this even when you send `html` — some clients only read it.

  • htmlstring

    The rich body. Sanitised on the way in; scripts and remote content are removed.

  • dataobject

    Typed data: structured JSON sent beside the text, for software at the other end to read as fields. Travels as its own part; it is never mixed into the text.

  • in_reply_touuid | null

    A message id: this arrives as a reply to it, in its thread.

Responses

  • 201Where it landed.
  • 400The request is not valid. `error.field` names the input at fault when there is one.
  • 401No API key, or one that is not valid.
  • 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
  • 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
  • 409This `Idempotency-Key` was used with a different request, or that request is still running. Nothing was sent by this call.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
  • 500Something went wrong on our side. Retry; if it keeps happening, tell us.
  • 503Something this needs is not answering right now. Retry in a moment.
bash
curl https://pidgeon.ai/api/v1/test/inbound \
  -X POST \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json