# 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:

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](#raw-bodies) 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](#call-options).

```ts
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`](/docs/sdks/typescript/messages/get) takes the mailbox and
the message, as `GET /mailboxes/{mailboxId}/messages/{messageId}` names them;
[`messages.send`](/docs/sdks/typescript/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):

```ts
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.

```ts
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`](/docs/sdks/typescript/domains/set-logo),
[`uploads.create`](/docs/sdks/typescript/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`).

```ts
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:

| 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](/docs/sdks/typescript/errors#retries-and-idempotent-sends)). |
| `headers` | Headers for this call alone. |

```ts
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.
