---
title: "Prepare a one-time newsletter asset upload"
method: POST
path: "/newsletter-assets/upload-tokens"
tags: ["Newsletters"]
---

# Prepare a one-time newsletter asset upload

`POST /newsletter-assets/upload-tokens`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/newsletter-assets/upload-tokens`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

Create a five-minute direct-to-storage PUT URL and single-use completion URL bound to this API key, organization, filename, content type, byte size, and SHA-256 digest. Video preparations also include a one-time JPEG poster PUT. Idempotency-Key is forbidden because the response contains one-time URLs.

## Headers

- `X-Shipmail-Organization` string

## Request body

- PrepareNewsletterAssetUploadRequest
  - `filename` string, required
  - `content_type` 'image/gif' | 'image/jpeg' | 'image/png' | 'image/webp' | 'video/mp4' | 'video/quicktime' | 'video/webm', required
  - `size` integer, required
  - `sha256` string, required

## Response `201`

One-time newsletter asset upload prepared.

- union
  - object
    - `kind` 'image', required
    - `object` 'newsletter_asset_upload', required
    - `filename` string, required
    - `content_type` 'image/gif' | 'image/jpeg' | 'image/png' | 'image/webp' | 'video/mp4' | 'video/quicktime' | 'video/webm', required
    - `size` integer, required
    - `sha256` string, required
    - `upload_url` string, uri, required
    - `upload_method` 'PUT', required
    - `upload_headers` object, required
      - `Content-Type` 'image/gif' | 'image/jpeg' | 'image/png' | 'image/webp' | 'video/mp4' | 'video/quicktime' | 'video/webm', required
      - `If-None-Match` '*', required
    - `thumbnail_upload_url` string, uri
    - `thumbnail_upload_method` 'PUT'
    - `thumbnail_upload_headers` object
      - `Content-Type` 'image/jpeg', required
      - `If-None-Match` '*', required
    - `complete_url` string, uri, required
    - `complete_method` 'POST', required
    - `expires_at` string, date-time, required
  - object
    - `kind` 'video', required
    - `object` 'newsletter_asset_upload', required
    - `filename` string, required
    - `content_type` 'image/gif' | 'image/jpeg' | 'image/png' | 'image/webp' | 'video/mp4' | 'video/quicktime' | 'video/webm', required
    - `size` integer, required
    - `sha256` string, required
    - `upload_url` string, uri, required
    - `upload_method` 'PUT', required
    - `upload_headers` object, required
      - `Content-Type` 'image/gif' | 'image/jpeg' | 'image/png' | 'image/webp' | 'video/mp4' | 'video/quicktime' | 'video/webm', required
      - `If-None-Match` '*', required
    - `thumbnail_upload_url` string, uri, required
    - `thumbnail_upload_method` 'PUT', required
    - `thumbnail_upload_headers` object, required
      - `Content-Type` 'image/jpeg', required
      - `If-None-Match` '*', required
    - `complete_url` string, uri, required
    - `complete_method` 'POST', required
    - `expires_at` string, date-time, required

## Other responses

- `400`: Validation failed.
- `401`: Authentication failed.
- `403`: Insufficient permissions.
- `422`: Validation failed.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/shipmail/apis/shipmail-api.md) · [All operations](https://skmtc.dev/shipmail/apis/shipmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shipmail/apis/shipmail-api/revisions/2c23e59d7e30?raw)