Attachments and stickers

There are two media payload shapes in the message.send schema — attachment and sticker — and neither can be used from /v1 today. Both are documented here so you know what they will look like, followed by the half of the media story that does work: receiving attachments and downloading their bytes.

Why sending does not work

Both payloads identify their media by transferId, a reference to a file already staged in Mapier storage. A Mac-local file path never crosses the wire, and neither do raw bytes in the command body.

That leaves one question — how do you get a transferId? — and /v1 has no answer. There is no upload endpoint. Nothing in the public API accepts a file, so nothing in the public API can produce the identifier both payloads require.

The schemas, for when they land

attachment

sticker

Receiving attachments — this part works

When someone sends you a photo, a video or a voice memo, the inbound message event on the response stream carries an attachmentIds array. It is ordered oldest first and empty when the message has no media.

{
  "conversationId": "a0000000-0000-4000-8000-000000000001",
  "from": "+14155550100",
  "text": "here's the damage",
  "externalId": "guid-2",
  "replyToExternalId": null,
  "occurredAt": "2026-08-29T18:11:02Z",
  "attachmentIds": ["att-a1b2", "att-c3d4"]
}

Each id is fetched on its own from GET /v1/attachments/:id. The response is the raw bytes — there is no JSON envelope and no metadata endpoint, so everything you learn about the file comes from the response headers.

curl -sS -D - -o photo.bin \
  $MAPIER_BASE_URL/v1/attachments/att-a1b2 \
  -H "Authorization: Bearer $MAPIER_API_KEY"

The path takes a single id segment and nothing else. There are no sub-paths: /v1/attachments/att-a1b2/original is not a route, and there is no size, format or thumbnail parameter to ask for a different rendition.

Conditional requests

The etag is a content hash, so it never changes for a given id. Send it back as If-None-Match and an unchanged attachment answers 304 with no body, which is worth doing if you re-fetch on a retry path.

curl -sI $MAPIER_BASE_URL/v1/attachments/att-a1b2 \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H 'If-None-Match: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"'

Because the hash is stable, most integrations skip conditional requests entirely and store the bytes on first fetch, keyed by attachment id.

The HEIC problem

A worked download

This fetches one attachment, keeps whatever the sniffed type says, and flags the HEIC case for a conversion step rather than silently storing something the front end cannot display.

import { writeFile } from "node:fs/promises";

const BASE = process.env.MAPIER_BASE_URL!;

const EXTENSIONS: Record<string, string> = {
  "image/jpeg": "jpg",
  "image/png": "png",
  "image/gif": "gif",
  "image/heic": "heic",
};

export async function downloadAttachment(attachmentId: string, dir: string) {
  const res = await fetch(`${BASE}/v1/attachments/${encodeURIComponent(attachmentId)}`, {
    headers: { Authorization: `Bearer ${process.env.MAPIER_API_KEY}` },
  });

  if (res.status === 404) return null; // unknown, another account's, or still transferring
  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(`${res.status} ${body.error ?? "attachment fetch failed"}`);
  }

  const contentType = res.headers.get("content-type") ?? "application/octet-stream";
  const etag = res.headers.get("etag");
  const bytes = Buffer.from(await res.arrayBuffer());

  const extension = EXTENSIONS[contentType] ?? "bin";
  const path = `${dir}/${attachmentId}.${extension}`;
  await writeFile(path, bytes);

  return {
    path,
    contentType,
    etag,
    needsConversion: contentType === "image/heic",
  };
}

Fetch attachments one at a time per message rather than firing the whole attachmentIds array at once. The endpoint allows 120 requests per rolling 60-second window, and a burst of a shared photo album will reach that. A 429 carries both a Retry-After header and a retryAfter field in the body, in whole seconds and never below 1.

Errors

Note that 404 deliberately collapses three different situations. An id that belongs to another account is indistinguishable from one that never existed — existence is never leaked across accounts. If an id from your own stream returns 404, the likely cause is that the transfer has not landed yet; retry shortly.

Related