# Send a fax

Emboss sends a PDF to a fax number and tells you when it arrives. Whichever
way you send it, Emboss returns a job at once and a receipt when the fax is
delivered or fails, so an agent can hand off a signed form to an agency's fax
line and move on. The destination is masked in receipts and telemetry. United
States, Canada, and Mexico are served.

## Four ways to send, one fax

- **API**: `POST /fax` with `to` and one or more PDF `files` (multipart), or
  a JSON body naming a `job_id`, `form_id`, `pdf_url`, or `pdf_base64`, then
  `GET /fax/{job_id}`. See the [reference](/docs/reference/fax).
- **MCP**: the `send_fax` tool (`to` plus a `job_id`, a `form_id`, `pdf_url`,
  or `pdf_base64`), then `get_fax`. See [MCP tools](/docs/mcp-tools).
- **A2A**: the `send_fax` skill with a `to` DataPart and PDF FileParts, or
  `job_id` / `form_id` in the DataPart; the task stays `working` until
  delivery. See [A2A](/docs/a2a).
- **Pay per call**: `POST https://api.getemboss.ai/pay/fax` with no account,
  paid per transmitted page over x402 or MPP; poll the `status_url` in the
  202. See [Pay per call](/docs/pay-per-call).

## Fax a finished form

The result of a fill is already on Emboss, so an agent never needs the
download link to fax it. With MCP: run `commit_proposal` (or
`fill_form_from_context`), poll `get_job` until `status` is `ready`, then call
`send_fax` with `to` and that `job_id`. A blank fillable form goes the same
way with `form_id`. Over the API the same call is a JSON body:

```bash
curl -X POST https://api.getemboss.ai/fax \
  -H "Authorization: Bearer $EMBOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15025551212", "job_id": "<job id from the commit>"}'
```

The shortest path is by `artifact_id`: every job and form response already
carries one, so passing it straight to `send_fax` skips resolving a `job_id`
or `form_id` at all:

```bash
curl -X POST https://api.getemboss.ai/fax \
  -H "Authorization: Bearer $EMBOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15025551212", "artifact_id": "<artifact id from the job>"}'
```

See [Artifacts and lineage](/docs/artifacts) for where an `artifact_id`
comes from and how it survives after the source documents are deleted. A
pay-per-call caller sends the `artifact_token` returned next to that
`artifact_id` alongside it, in place of an account.

To send several artifacts as one fax, replace `artifact_id` with a
`sources` list, each entry an `artifact_id` and optional `pages`:

```bash
curl -X POST https://api.getemboss.ai/fax \
  -H "Authorization: Bearer $EMBOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15025551212", "sources": [
        {"artifact_id": "<package>", "pages": "1-2"},
        {"artifact_id": "<filled form>"}]}'
```

See [Artifacts and lineage](/docs/artifacts) for the `sources` grammar and
the page-selection syntax. To assemble that packet from several artifacts
first, compose them with `compose_pdf` and fax the result by its
`artifact_id`; see [Free PDF utilities](/docs/pdf-utilities).

A job that is still processing answers `not_ready` (409 on the API); poll and
send again. A job or form that is not yours, or whose documents were already
deleted by your retention setting, answers `not_found`. Sending the same
artifact to the same destination again within ten minutes returns the same
job, with `deduplicated: true`, instead of a second fax.

## What it costs

3¢ per page on your account, metered when the fax is
delivered. Faxes have no free allowance, so an account fax needs a payment
method on file: without one, the request is refused with `402` and code
`card_required` before anything is sent. A fax that fails is not charged. On pay per call the price is in
the payment challenge; card payments carry the card minimum, stablecoins pay
the exact price, and a paid fax that fails or expires (still not delivered
about an hour after it was sent) is refunded: automatically on card, up to
three refunds a day, and through contact@getemboss.ai for stablecoins.

## The receipt

Over the API and MCP, poll the receipt until its `status` is `delivered`,
`failed` or `expired`. On pay per call, the job at `status_url` reads `ready`
once the carrier accepted the fax; keep checking until `result.status` is
`delivered`, `failed` or `expired`. Every receipt carries the
`artifact_id` of the transmitted copy and the `source_artifact_ids` it was
faxed from. A delivered receipt also carries `pages`, the `price`, and the
`artifact_sha256` of the transmitted file. A failed receipt carries a
`failure_category` (`destination`, `timeout`, `vendor` or `unknown`), whether
it is `retryable`, the raw carrier reason for support, and the refund
state. A failure the service retries on its own is resent automatically; `retryable` true on a final failure means sending again by hand may succeed.

A fax that fails because the line was busy, nothing answered, or the call
dropped is sent again automatically: 2, 5 and 10 minutes after each failure,
four attempts in all, with no extra charge. While it waits, the receipt stays
`working` and carries `attempts`, `max_attempts`, `next_attempt_at` and a
plain `message` such as "Attempt 2 of 4. The line was busy. Next try at
11:08 UTC." Every receipt carries `attempts`, `max_attempts`, `message` and
`created_at`; a pending resend also carries `last_failure`. A fax that fails
for any other reason, or on the last attempt, ends as `failed` or `expired` with
`failure_message` saying what happened:

| Reason | What it means |
| --- | --- |
| Busy | The line was busy. |
| No answer | The line rang but nothing answered. |
| Call dropped | The call connected and then dropped. |
| Timeout | The line answered but no fax machine responded. Check that this is a fax number. |
| Not a fax line | This number is not a fax line. |
| Invalid number | This number cannot be dialed. |
| Problem on our side | The fax could not be sent because of a problem on our side. On the monthly-invoice route the sentence ends "Nothing was charged." |
| Something else | The fax did not go through. |
| Still not delivered after an hour | The fax was still not delivered an hour after it was sent. (Or "The fax never reached the fax carrier." when it was never accepted.) |

After four attempts the message starts "Tried 4 times over 17 minutes."
On the pay-per-call API, sending the same request again with the same payment
returns the same job and never sends the same fax twice; a new fax needs a new request and a new
payment.

## Limits

If three faxes in a row from your account fail at the far end within an hour,
new faxes are paused for 30 minutes. 10 far-end failures in a day
pause faxing for 24 hours. A fax that expired never counts. A delivered fax
resets the in-a-row count; the daily count rolls over 24 hours and ignores
deliveries. A paused request is refused with `429`, code `account_paused`,
`retry_after` in seconds, `until`, `count`, `numbers` (masked) and a
sentence. For the 30-minute pause the sentence names the failure times and
the numbers tried; for the day pause it gives the count and the time the
pause ends. If those numbers are right, write to contact@getemboss.ai and we can lift the pause.

One number is dialed at most 12 times an hour by everyone combined, resends
included. Past that, the request is refused with `429`, code
`destination_busy`, with `retry_after` and `until`. Too many requests in a
short time, or past the daily sending cap, are refused with `429`, code
`rate_limited`, with `retry_after`.
Anonymous pay-per-call callers are limited together by network address.

## What to send

Unencrypted PDFs only. On the API (`POST /fax`), several PDFs are sent as one
fax, in order. The file is kept only long enough to transmit and is then deleted on a
schedule; the receipt keeps the hash so you can prove what was sent.

## See also

- [Send a fax from an agent](https://getemboss.ai/use-cases/send-a-fax-from-an-agent)
- [Pay per call](https://getemboss.ai/docs/pay-per-call)
- [Artifacts and lineage](https://getemboss.ai/docs/artifacts)
- [Free PDF utilities](https://getemboss.ai/docs/pdf-utilities)
- [What agents may do, and when to ask](https://getemboss.ai/docs/agentic-access)
- [Send a fax](https://getemboss.ai/docs/reference/fax)
- [Artifacts](https://getemboss.ai/docs/reference/artifacts)