Sending files from your own code comes down to three steps: create a transfer, upload the bytes, and finalise it so the link goes live and recipients are told. The step that decides whether the whole thing works in production is the upload, and the property to check before you commit to any provider is whether an interrupted upload resumes or starts again.
Most consumer file transfer services have no public API at all, so that is the first thing to establish. This is a guide to building the pipeline once you have found one that does.
The shape of every file delivery API
Whatever the provider, an API-first delivery flow looks like this:
- Create a transfer. You get an id and per-file upload credentials.
- Upload each file's bytes. This is the part that takes hours and fails.
- Finalise. Tell the service you are done. This is when the link goes live and recipients are emailed.
The mistake worth avoiding is treating step three as optional because step two finished. Uploaded bytes and a live transfer are different states in most designs, and stopping after the upload leaves you with something that looks sent and notifies nobody, with no error anywhere to find.
Questions to ask before you choose
Do uploads resume? A 100 GB upload will be interrupted. If the answer is no, the advertised size limit is fiction. Why it is harder than it sounds.
Is the API on every plan, or only the expensive one? In this category, it is usually the latter.
Is there an OpenAPI document? A generated client is only as good as the spec, and hand-maintained specs drift. A spec generated from the same schemas the server validates with is worth more than a prettier one that is wrong.
What is metered? Calls, upload gigabytes, download gigabytes, storage? Metering downloads is the one to watch: when the limit hits, the refusal lands in front of your customer's client rather than in front of you.
Which calls are safe to retry? Networks fail, and you will send some requests twice.
A worked example
Using the Yungle API, because I built it and can show real calls.
1. Create a draft. Nothing is live and nobody is emailed yet. Sizes are exact bytes and must match what you upload.
curl -X POST https://yungle.co/api/v1/transfers \
-H "Authorization: Bearer $YUNGLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"files":[{"name":"render.mov","size":42000000000}]}'The response carries the transfer's id, a tusEndpoint, and one uploadToken per file.
2. Upload with any tus client. The protocol is the resumability, which is why it is worth using a standard rather than a bespoke multipart scheme. In JavaScript:
import * as tus from 'tus-js-client'
const upload = new tus.Upload(stream, {
endpoint: tusEndpoint,
uploadSize: file.size,
headers: { 'x-yungle-upload-token': file.uploadToken },
metadata: { fileId: file.id, token: file.uploadToken, filename: file.name },
retryDelays: [0, 1000, 3000, 5000, 10000],
})
upload.start()3. Finalise. This makes the link live and emails the recipients. Leave recipients out to get a link only.
curl -X POST "https://yungle.co/api/v1/transfers/$TRANSFER_ID/finalize" \
-H "Authorization: Bearer $YUNGLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"recipients":["client@example.com"],"message":"Final grade attached."}'Finalising is idempotent — retrying a request whose response you lost is safe. A draft that is never finalised is cleared away after 24 hours, so an abandoned script leaves nothing behind.
If you would rather not write any of it, the CLI does all three steps in one command:
npx yungle-cli send render.mov --to client@example.com --message "Final grade attached."The reference is at docs.yungle.co, and the OpenAPI document at /api/v1/openapi.json is generated from the same schemas the handlers validate with.
Decisions that are painful to change later
Where the retry lives. Retrying a whole upload at the job level is easy and wrong for large files. Retry per chunk, which means using a protocol that has chunks.
What identifies a file. Name plus size is not unique — a folder of exports collides constantly. When matching created rows to local files, match by position or by an id the API gave you, never by filename.
Where credentials live. An API key is a machine credential that belongs to a workspace, not to the person who created it. Give it the narrowest scope that works, and treat rotation as routine rather than an incident.
What happens when billing lapses. Does the API stop, or do existing links keep working? Both are defensible; only one breaks your customer's delivery quietly.
Metering: read the fine print
Providers meter uploads, downloads, calls or storage, and the choice says something about the product.
Metering downloads is the one to be wary of. They are unbounded and unpredictable — you cannot know how often a client will fetch a file — and when the limit hits, the failure surfaces to the person you sent the link to.
Metering uploads is predictable: you know what you are about to send.
For what it is worth, Yungle meters API uploads and never downloads. There are 10 GB of API uploads a month included on every plan, free included, and beyond that it is charged from credit you top up yourself — the numbers are on the pricing page.
Where to go next
- Resumable uploads — the property that decides whether large files work at all.
- Large uploads in the browser — if the upload starts on a web page.
- Sending build artifacts from CI — the most common first integration.
- Giving an AI agent file access safely — if a model will hold the credential.
- Yungle for developers — the API, webhooks, the CLI and the MCP server, all on the free tier for transfers; collections need a plan.
The API key takes a minute to create, and the free tier's 10 GB of API uploads a month is enough to wire up a real pipeline and see whether the shape fits before any money changes hands.