Skip to content

Prepare Bulk CSV Upload

POST
/emails/bulk/upload
 
curl --request POST \
  --url https://api.unwrap.email/v1/emails/bulk/upload \
  --header 'Content-Type: application/json' \
  --header 'UNWRAP-EMAIL-API-TOKEN: <UNWRAP-EMAIL-API-TOKEN>' \
  --data '{ "filename": "example", "size_bytes": 1 }'

Prepare an immutable CSV upload of at most 50 MiB. Requires write authentication, an active subscription, and CSV admission. PUT the exact bytes to upload_url with the returned headers within 15 minutes. Submit upload_id to POST /emails/bulk within one hour. At most three unclaimed uploads are allowed. Idempotency-Key is scoped separately from bulk submission; matching preparation retries refresh the signature within the original one-hour window.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “ Header Parameters ”
idempotency-key
string
>= 1 characters <= 255 characters

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
filename
required

Original CSV filename, without a directory.

string
>= 1 characters <= 255 characters /^[^\u0000-\u001f\u007f/\\]+$/
size_bytes
required

Exact UTF-8 file size, at most 50 MiB.

integer
>= 1 <= 52428800
Example generated 
{
  "filename": "example",
  "size_bytes": 1
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Prepared upload and required signed headers.

Media type application/json
object
upload_id
required
string format: uuid
upload_url
required
string format: uri
headers
required
object
Content-Type
required
string
Allowed values: text/csv
Content-Length
required
string
If-None-Match
required
string
Allowed values: *
expires_at
required
string format: date-time
Example 
{
  "headers": {
    "Content-Type": "text/csv",
    "If-None-Match": "*"
  }
}

400

Section titled “ 400 ”

Invalid request envelope, pagination, identifier, or header.

401

Section titled “ 401 ”

Valid API authentication is required; submission requires write permission.

403

Section titled “ 403 ”

API-token access requires an active subscription. Submission also requires an active subscription for session and bearer callers.

404

Section titled “ 404 ”

The job does not exist or belongs to another user.

409

Section titled “ 409 ”

Idempotency-Key input mismatch, or CSV is not ready.

410

Section titled “ 410 ”

Job results have expired.

413

Section titled “ 413 ”

Request body exceeds 5 MiB.

429

Section titled “ 429 ”

Three unfinished submissions or unclaimed uploads already exist for this user.

503

Section titled “ 503 ”

Bulk admission is disabled or storage is temporarily unavailable.