Send a fax

post

https://api.emaktalk.com/api/v1/fax/send

Sends a fax from one of your fax servers and returns its new fax log.

Who may call it: an API key with All permissions, for every fax server of your account. A Scoped key is refused with 403.

Use it:

Find the fax server's id: fax_uuid from GET /fax/servers.
Put each PDF in documents, in the order to fax them: Base64-encoded as content_base64, or as a url we fetch. Add coversheet to put a coversheet in front, or send a coversheet alone.
Send the body as JSON, with Content-Type: application/json. Any other type is refused with 415 (curl -d without -H "Content-Type: application/json" sends a form type).
Keep row.fax_log_uuid and follow the fax with GET /fax/logs/{logId} until its status is final. There is no delivery webhook.

Response: 200 with message, row, the new fax log (fax_status queued), and scheduled_send_at, null unless the fax is held for its number's verification. A 200 means the fax is queued, not delivered.

Checked strictly: every field is checked before your documents are read or stored, and the request is refused at the first problem found. A field this page doesn't list is refused (Unknown field "files"), in the body, in coversheet and in each document. subject, to_name and the coversheet's subject take at most 255 characters, the coversheet's message 5,000; quality and language take only their listed values; timezone must be an IANA time zone.

Limits:

Inline documents: 10 MB (10,485,760 bytes) combined, decoded: 413 Inline documents are limited to 10 MB combined.
Each document by URL: 50 MB, counted as it's read: 413 documents[i] is over 50 MB.
The fax as sent, coversheet included: 50 MB and 350 pages: 400 The fax is over 50 MB or The fax is over 350 pages.
No limit on the number of documents.
The request body, as sent, is limited to 20 MB (20,971,520 bytes) on every request: 413 The request body is limited to 20 MB. Base64 is a third larger than the PDF, and JSON encoders that escape characters make it larger still: .NET's default encoder writes + as \u002B and PHP's json_encode writes / as \/. Send the Base64 unescaped when you can (for example JsonSerializer with JavaScriptEncoder.UnsafeRelaxedJsonEscaping, or JSON_UNESCAPED_SLASHES).

Documents by URL:

Every document is checked before any is read: inline ones are decoded first, then each URL is fetched once, in turn. All URLs of a send share one 60-second deadline.
https only, default port, no credentials in the URL, a host name rather than an IP address, at most 8,192 characters. Links to our own platform are refused.
Up to 3 redirects, each checked by the same rules. The final answer must be a 200 carrying the PDF, not an HTML page.
We fetch with a plain GET (user agent EMAK-Fax/1.0 (+https://docs.emak.tech)), no cookies or credentials. A signed link that expires is fine if it's valid when you send.
The URL is used once and never stored or logged: the fax keeps our copy of the document.
Some sites refuse requests from cloud networks and answer 403 (documents[i] could not be fetched: HTTP 403) even when the link works in a browser: use links from your own storage (signed S3, Google Cloud Storage or Azure links) or a host you control, or send the document as Base64.

Notes:

Each document must be a PDF, with %PDF- within its first 1,024 bytes. Nothing is converted: send other formats as PDF.
to_number takes national formats, read as North American (8553301239, (855) 330-1239, 1-855-330-1239), and is normalized to E.164 (+18553301239): the fax network accepts E.164 numbers only. A number that can't be normalized is refused before anything is stored or sent.
When the fax server's number isn't verified for faxing yet, sending starts its verification and holds the fax: it goes out about three minutes later, at scheduled_send_at. See Fax.
The fax's subject is subject, or, with coversheet, the coversheet's subject (the top-level one is then ignored). A fax sent without one gets an AI-generated subject of up to six words, written from its content before we answer, so row.fax_subject already carries it. When none can be written, fax_subject is null.
A failed attempt is retried automatically, up to four times. Retrying this request after a timeout can send the fax twice: check the fax logs first.
fax_from_number in row is your fax server's number as stored on it.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Send documents, coversheet, or both. Without either the request is refused (400 No Coversheet or File Attachments Available!). Any field not listed here is refused (400 Unknown field "files"). An optional field sent as null is the same as omitting it.

fax_server_id

uuid

required

The fax server to send from: a fax_uuid from GET /fax/servers. The fax goes out from its number (fax_caller_id_number) and name.

to_number

string

required

The destination fax number. National formats are read as North American and normalized to E.164: 5145550199, (514) 555-0199, 1-514-555-0199 and +15145550199 are the same number. Other countries need + and the country code. A number with an extension, or that isn't a valid phone number, is refused.

to_name

string | null

The recipient's name, at most 255 characters. Printed on the coversheet before the number and kept on the fax log. Control characters are removed and spaces trimmed.

documents

array

length ≥ 1

One or more PDFs, each sent inline (content_base64) or by link (url), mixed as you like. They're faxed in the order given, after the coversheet. Inline documents are limited to 10 MB (10,485,760 bytes) combined, decoded; each document by URL to 50 MB. The fax as sent, coversheet included, is limited to 50 MB and 350 pages. Omit documents for a coversheet alone: an empty array is refused.

documents

coversheet

object

Puts a one-page coversheet in front of the documents: your fax server's logo, name and number, the recipient (to_name and to_number), the date, subject and message. Both fields are optional; {} prints a coversheet with no subject or message. Any other field is refused (400 Unknown field coversheet."logo").

subject

string

length ≤ 255

The fax's subject, kept on its fax log; not printed. At most 255 characters; control characters are removed and spaces trimmed. Used only without coversheet. A fax sent without a subject gets an AI-generated one of up to six words, written from its content.

quality

string

enum

Defaults to ultra_dark

ultra_dark (Superfine Text, the default) suits text; ultra_light (Superfine Image) suits images and light scans. Any other value is refused. The fax log shows it as fax_image_resolution.

Allowed:

language

string

enum

The coversheet's language (French for fr-ca and fr-fr, else English) and the language of the delivery emails. Any other value is refused. Defaults to your account's language.

Allowed:

timezone

string

The IANA time zone of the date printed on the coversheet, such as America/Montreal; the name is not case-sensitive. A name that isn't an IANA time zone is refused. Defaults to your account's time zone, else America/Toronto.

Responses

200The fax is queued; row is its new fax log, and scheduled_send_at says when a held fax goes out.

401No usable API key: none sent, a key that doesn't exist or was revoked (a revoked key stops working within a minute), or two kinds of credentials at once.

403Unauthorized Access Unable to Send Fax, User Not Authorized!: the fax server is not one of your account's, does not exist, or the key is Scoped.

415Unsupported Media Type Send the request body as application/json: the request's Content-Type isn't application/json (parameters such as ; charset=utf-8 are fine), or is missing.

503 Service Unavailable Document storage or conversion is unavailable; try again shortly, with Retry-After: 30: your documents could not be stored just now; nothing was sent. Or your key could not be checked (see the 503 shared by every endpoint): wait Retry-After seconds.