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.
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 versionThe 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).
Listings
A TypeScript SDK listing: awaited, one page as the API answers it; iterated, every item of every page, each page fetched as the loop reaches it.
Errors and retries
The TypeScript SDK's one error type, RequestError, and its codes; which calls it sends again, and how idempotency keys make a send safe to retry.