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

# TypeScript SDK

> Official TypeScript/Node.js SDK for Transmit

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install transmitdev
  ```

  ```bash yarn theme={null}
  yarn add transmitdev
  ```

  ```bash pnpm theme={null}
  pnpm add transmitdev
  ```
</CodeGroup>

## Requirements

* Node.js 16 or higher
* TypeScript 4.5 or higher (optional)

## Quick Start

```typescript theme={null}
import { Transmit } from 'transmitdev';

const client = new Transmit({
  apiKey: process.env.TRANSMIT_API_KEY
});

// Send an email
const response = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '<h1>Hello World</h1>'
});

console.log('Email sent:', response.id);
```

## Configuration

### Initialize the Client

```typescript theme={null}
import { Transmit } from 'transmitdev';

const client = new Transmit({
  apiKey: 'tx_your_api_key_here',
  baseUrl: 'https://api.transmit.dev', // optional
  timeout: 30000, // optional, in milliseconds
});
```

### Environment Variables

```bash theme={null}
# .env
TRANSMIT_API_KEY=tx_your_api_key_here
```

## Sending Emails

### Basic Email

```typescript theme={null}
const response = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>Welcome!</p>'
});
```

### Multiple Recipients

```typescript theme={null}
const response = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: ['user1@example.com', 'user2@example.com'],
  cc: ['manager@example.com'],
  bcc: ['admin@example.com'],
  subject: 'Team Update',
  html: '<p>Important update</p>'
});
```

### With Attachments

```typescript theme={null}
import fs from 'fs';

const fileBuffer = fs.readFileSync('./invoice.pdf');

const response = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Invoice',
  html: '<p>Your invoice is attached</p>',
  attachments: [
    {
      filename: 'invoice.pdf',
      content: fileBuffer,
      contentType: 'application/pdf'
    }
  ]
});
```

### Using Templates

```typescript theme={null}
const response = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  templateId: 'welcome-email',
  variables: {
    name: 'John Doe',
    confirmUrl: 'https://example.com/confirm'
  }
});
```

## Type Safety

The SDK is fully typed with TypeScript:

```typescript theme={null}
import type { Email, EmailResponse } from 'transmitdev';

// Full IntelliSense support
const emailData: Email = {
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Test',
  html: '<p>Test</p>'
};

const response: EmailResponse = await client.emails.send(emailData);
```

## Error Handling

```typescript theme={null}
import { TransmitError } from 'transmitdev';

try {
  const response = await client.emails.send({
    from: 'hello@yourdomain.com',
    to: 'invalid-email',
    subject: 'Test',
    html: '<p>Test</p>'
  });
} catch (error) {
  if (error instanceof TransmitError) {
    console.error('API Error:', error.code, error.message);
    console.error('Status:', error.statusCode);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## Async/Await and Promises

The SDK supports both async/await and promises:

```typescript theme={null}
// Async/await (recommended)
const response = await client.emails.send(emailData);

// Promises
client.emails.send(emailData)
  .then(response => console.log(response))
  .catch(error => console.error(error));
```

## Retrieving Emails

```typescript theme={null}
// Get a single email by ID
const email = await client.emails.get('email_abc123');

// List emails with pagination
const emails = await client.emails.list({
  page: 1,
  limit: 50,
  status: 'delivered'
});

console.log(emails.data);
console.log(emails.pagination);
```

## Managing Contacts

```typescript theme={null}
// Add a contact
const contact = await client.contacts.create({
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
  tags: ['customer', 'pro-plan']
});

// List contacts
const contacts = await client.contacts.list({
  page: 1,
  limit: 50
});

// Update a contact
await client.contacts.update('contact_abc123', {
  tags: ['customer', 'enterprise-plan']
});
```

## Templates

```typescript theme={null}
// Create a template
const template = await client.templates.create({
  name: 'Welcome Email',
  subject: 'Welcome {{name}}!',
  html: '<h1>Hello {{name}}</h1>'
});

// List templates
const templates = await client.templates.list();

// Get a template
const template = await client.templates.get('template_abc123');

// Update a template
await client.templates.update('template_abc123', {
  html: '<h1>Updated template</h1>'
});

// Delete a template
await client.templates.delete('template_abc123');
```

## GitHub Repository

<Card title="View on GitHub" icon="github" href="https://github.com/transmit-dev/sdk-typescript">
  Browse the source code, report issues, and contribute
</Card>

## Support

<CardGroup cols={2}>
  <Card title="API Reference" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Examples" href="https://github.com/transmit-dev/sdk-typescript/tree/main/examples">
    View example code on GitHub
  </Card>
</CardGroup>