# Responses and headers

What a TypeScript SDK method answers, how withResponse() gives its Response for the headers, and conditional reads and writes with ETags.

Awaited, a method answers its operation's body:

- **JSON**, typed by its schema (`Domain`, `MessageMeta`, `SendResult`);
- **text**, for a text answer (a CSV export, an iCalendar feed);
- **a `Blob`**, for bytes (raw MIME, a message part, a logo), which keeps its
  media type;
- **nothing**, where the operation answers no body.

Each method's page says which, under its Answer.

## The Response

A method answers an `ApiPromise`, which goes wherever a `Promise` of its
body does (`await`, `then`, `Promise.all`). It is sent as the method is
called, once. Its `withResponse()` answers the body with the `Response` it came
in (an `ApiResponse`, `{ data, response }`), for what rides on headers: an
`ETag`, a `Retry-After`, a request id.

```ts
import { isNotModified } from '@openemail/sdk'

const { data: content, response } = await openemail.messages.getContent(mailboxId, messageId).withResponse()
const etag = response.headers.get('etag') ?? undefined     // this content's version
```

The response is the one the body was read from: after a retry, the last
send's. Its body is read already (`data` is it); its status and headers are
there to read. A listing's `withResponse()` answers its first page.

## Conditional reads

A read that takes `ifNoneMatch` with an ETag an earlier read gave is answered
`304` when the copy you hold is current: a message's content, its parts and
its raw MIME, a delivery's fetch, a domain's public logo. A `304` rejects, as any answer that
is not a success does, and `isNotModified(error)` tells it from every other
failure:

```ts
try {
  const fresh = await openemail.messages.getContent(mailboxId, messageId, { ifNoneMatch: etag })
} catch (error) {
  if (!isNotModified(error)) throw error                   // a 304: the copy held is current
}
```

## Conditional writes

A write that takes `ifMatch` sends the version its read gave: preferences'
`version`, a vacation reply's `state`, a calendar's or an address book's
object's `etag`. A stale one is refused `412` with its code
(`version_conflict`, `state_conflict`, `precondition_failed`): read again, then
write. `ifNoneMatch: '*'` only creates (a Sieve script, a calendar's or an
address book's object).
