Calling methods
How a TypeScript SDK method takes its arguments: the path's parameters, the body or its raw bytes, the operation's options, and what every call takes.
Every method reads the way its operation's URL does:
- The path's parameters, in the order the path names them.
- The body, when the operation takes one: its JSON, or the raw bytes of a message, a calendar or a file.
- The options, one object: the operation's query and header parameters, and how this one call is sent.
const message = await openemail.messages.get(mailboxId, messageId)
const sent = await openemail.messages.send(mailboxId, {
from: { email: 'ada@example.com', name: 'Ada' },
to: [{ email: 'grace@example.org' }],
subject: 'Hello',
text: 'Hello from the SDK',
}, { deliveryId: 'order-1234' })messages.get takes the mailbox and
the message, as GET /mailboxes/{mailboxId}/messages/{messageId} names them;
messages.send the mailbox, then the
message to send, then its options. Each method's page lists its arguments and
options, with their types.
Path parameters
Each is encoded as one segment of the path, so an address's @ or a label's
/ is sent as it should be. An empty one, . or .. is refused before
anything is sent.
The body
A JSON body is typed after the method (DomainsCreateBody,
MessagesSendBody), and printed on its page. An optional one may be left out
when nothing follows it; to give options, pass undefined in its place (a
JavaScript caller's options there would be sent as the body):
await openemail.securityKeys.remove(identityId, webauthnId, undefined, { timeout: 10_000 })Raw bodies
An operation that takes bytes takes the bytes themselves, a RawBody: text,
a Blob, an ArrayBuffer or a Uint8Array, named for what they are.
await openemail.messages.append(mailboxId, rawMime, { label: 'Archive' })
await openemail.domains.setLogo(domain, png, { contentType: 'image/png' })A raw body is sent as the media type its operation takes: message/rfc822
for a message, text/calendar for a calendar object, text/vcard, text/csv.
An operation that takes bytes of any type (domains.setLogo,
uploads.create) has a contentType
option; without it the body goes as a Blob's own type, else as the type its
first bytes tell (a PNG, a JPEG, a GIF, a WebP, a PDF, an SVG), else as
application/octet-stream.
Options
The operation's query parameters go by the API's own names (limit,
cursor, label); its header parameters in camelCase without the x-
(x-delivery-id is deliveryId, if-match is ifMatch).
const { messages } = await openemail.messages.list(mailboxId, {
label: 'INBOX',
limit: 20,
excludeRoles: ['trash', 'junk'],
})- A switch the API spells
'true'/'false'takes a boolean (domains.list({ usage: true })). - A list is sent as one value joined by commas (
excludeRoles=trash,junk), the form the API reads. - An option left
undefinedornullis left out. - An option the operation does not take is refused, with a
TypeErrornaming the ones it does: the API ignores a query it does not know, so a misspelt filter would otherwise filter nothing.
Call options
Every call also takes these (CallOptions), beside its operation's options:
| Option | What it does |
|---|---|
signal | An AbortSignal that cancels the call, and any retry it waits on: it then rejects with a RequestError whose kind is abort. A live channel it closes. |
timeout | How long one send waits for its answer, body included, in ms; 0 for no limit. The client's by default (60 s). |
retry | This call's retries: false for none, a number, or a policy, which vouches that sending it twice is harmless (retries). |
headers | Headers for this call alone. |
const controller = new AbortController()
const page = openemail.messages.list(mailboxId, { limit: 50, signal: controller.signal, timeout: 10_000 })Bad arguments
A bad argument (an option the operation does not take, a missing path
parameter, a body that is no body) rejects the method's promise with a
TypeError, and nothing is sent. A live channel's method answers no
promise, so it throws instead.
The client
The TypeScript SDK's client: its credential, the API's address, timeouts and retries, headers, its fetch and WebSocket, and why a browser is refused.
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.