> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pramaan.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# References

> Act on something an earlier call created: send an email, then check its status.

Some capabilities create something you come back to later: an email you sent, a post you
published, a monitor you set up. Those calls return a `ref`. Pass that `ref` to the follow-up
capability to act on the same thing.

## Send, then check

```ts theme={null}
const sent = await p.email.send(
  { from: "shop@example.com", to: "buyer@example.com", subject: "Your receipt", text: "Thanks!" },
  { idempotencyKey: "order-1042-receipt" },
);
// { status: "queued", ref: "ref_01ARZ3NDEKTSV4RRFFQ69G5FAV" }

const delivery = await p.email.status({ ref: sent.ref });
// { status: "delivered", updatedAt: "2026-10-06T10:00:00.000Z" }
```

The same over HTTP:

```bash theme={null}
curl https://api.pramaan.dev/v1/capabilities/email.status \
  -H "Authorization: Bearer $PRAMAAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref": "ref_01ARZ3NDEKTSV4RRFFQ69G5FAV"}'
```

Store the `ref` next to your own record (the order, the message) so you can look it up later.

## Which capabilities use a ref

| This call returns a `ref` | Pass it to |
| - | - |
| `email.send` | `email.status` |
| `sms.send` | `sms.status` |
| `social.post.publish` | `social.post.get`, `social.post.analytics` |
| `web.monitor.create` | `web.monitor.delete` |
| `deploy.deployment.create` | `deploy.deployment.get` (which also takes the deployment `id`) |

Each capability's reference page shows the `ref` field in its request or result.

## Refs on list rows

Some lists return a `ref` on every row, so you can act on a row you did not create in this
API call by call (a draft you list, then send). These start with `rh_` and are passed exactly
like any other `ref`. The same row gives the same `ref` each time you list it.

## Rules

* A `ref` is an opaque string that starts with `ref_` or `rh_`. Don't parse it or build one
  yourself. It can be up to 1,027 characters long.
* A `ref` belongs to your account. Nobody else can use it.
* A `ref` only works with the follow-ups of the call that returned it. An email's `ref` passed
  to `sms.status` is refused.
* A `ref_` reference does not expire. A row's `rh_` reference normally does not either; where
  one does, the list's reference page says so. If the thing behind it is gone (a deleted monitor), the follow-up
  fails with `not_found`.
* Retrying a call with the same [Idempotency-Key](https://docs.pramaan.dev/guides/idempotency.md) returns the same `ref`.
* `ref` is optional in results: a call that fails returns none, and in rare cases a successful
  call has nothing to refer to. Check for it before you store it.
* A follow-up on your own connected account still needs that
  [connection](https://docs.pramaan.dev/guides/connections.md) to be in place.

## Errors

| Status | Code | When |
| - | - | - |
| `400` | `invalid_request` | `ref` is missing or not a reference, or it refers to a different kind of thing |
| `404` | `not_found` | No such reference in your account ("Reference not found.") |

See [errors](https://docs.pramaan.dev/guides/errors.md) for the full list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.