Skip to Content

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:

  1. The path's parameters, in the order the path names them.
  2. The body, when the operation takes one: its JSON, or the raw bytes of a message, a calendar or a file.
  3. 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 undefined or null is left out.
  • An option the operation does not take is refused, with a TypeError naming 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:

OptionWhat it does
signalAn 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.
timeoutHow long one send waits for its answer, body included, in ms; 0 for no limit. The client's by default (60 s).
retryThis call's retries: false for none, a number, or a policy, which vouches that sending it twice is harmless (retries).
headersHeaders 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.