docs
View as Markdown

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.
  • MCP: the send_fax tool (to plus a job_id, a form_id, pdf_url, or pdf_base64), then get_fax. See 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.
  • 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.

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:

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:

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 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:

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 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.

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:

ReasonWhat it means
BusyThe line was busy.
No answerThe line rang but nothing answered.
Call droppedThe call connected and then dropped.
TimeoutThe line answered but no fax machine responded. Check that this is a fax number.
Not a fax lineThis number is not a fax line.
Invalid numberThis number cannot be dialed.
Problem on our sideThe fax could not be sent because of a problem on our side. On the monthly-invoice route the sentence ends "Nothing was charged."
Something elseThe fax did not go through.
Still not delivered after an hourThe 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.