Welcome!

> ## Documentation Index
> Fetch the complete documentation index at: https://torpedo.co.mz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Send email and SMS from TypeScript with torpedo-sdk

The TypeScript SDK wraps Torpedo's REST API for server-side JavaScript and TypeScript apps.
It supports transactional email, email batches, SMS, and TypeScript-only email templates powered
by React Email.

Other languages should continue using the REST API examples until dedicated SDKs are available.

## Install

```bash theme={null}
pnpm add torpedo-sdk
```

## Create a client

```ts theme={null}
import { Torpedo } from 'torpedo-sdk'

const torpedo = new Torpedo({
  apiKey: process.env.TORPEDO_API_KEY!,
})
```

## Send raw HTML email

```ts theme={null}
await torpedo.emails.send({
  from: 'Acme <hello@myapp.com>',
  to: 'user@example.com',
  subject: 'Welcome to Acme',
  html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
})
```

## Send a template email

Template support is specific to the TypeScript SDK. The SDK renders the template to `html`,
generates plain text, and sends the existing Torpedo email API request.

React Email support is optional. Install it only when you want to send React templates:

```bash theme={null}
pnpm add react react-dom @react-email/components @react-email/render
```

```tsx theme={null}
import { Body, Html, Text } from '@react-email/components'
import { Torpedo } from 'torpedo-sdk'

function WelcomeEmail({ name }: { name: string }) {
  return (
    <Html>
      <Body>
        <Text>Welcome {name}</Text>
      </Body>
    </Html>
  )
}

const torpedo = new Torpedo({
  apiKey: process.env.TORPEDO_API_KEY!,
})

await torpedo.emails.send({
  from: 'Acme <hello@myapp.com>',
  to: 'user@example.com',
  subject: 'Welcome to Acme',
  template: <WelcomeEmail name="Eliot" />,
})
```

Provide `text` if you want full control over the plain-text part:

```tsx theme={null}
await torpedo.emails.send({
  from: 'Acme <hello@myapp.com>',
  to: 'user@example.com',
  subject: 'Welcome to Acme',
  template: <WelcomeEmail name="Eliot" />,
  text: 'Welcome Eliot',
})
```

## Send a batch

Batch sends can mix raw HTML and templates:

```tsx theme={null}
await torpedo.emails.sendBatch({
  emails: [
    {
      from: 'Acme <hello@myapp.com>',
      to: 'one@example.com',
      subject: 'Welcome',
      html: '<h1>Welcome!</h1>',
    },
    {
      from: 'Acme <hello@myapp.com>',
      to: 'two@example.com',
      subject: 'Welcome',
      template: <WelcomeEmail name="Eliot" />,
    },
  ],
})
```

Batch requests do not support idempotency keys.

## Send SMS

```ts theme={null}
await torpedo.sms.send({
  to: '+258841234567',
  body: 'Your verification code is 482910.',
})
```

The SDK automatically adds an idempotency key for each write request so SDK retries are safe.

## Read messages

```ts theme={null}
const emails = await torpedo.emails.list({ limit: 20 })
const email = await torpedo.emails.get(emails.data[0].id)

const smsMessages = await torpedo.sms.list({ limit: 20 })
const sms = await torpedo.sms.get(smsMessages.data[0].id)
```