Skip to Content

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.

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:

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).