Send Email

Learn how to send your first email with the Transactional TypeScript SDK.

Beginner

5 minutes

getting-started

sdk

Prerequisites

Node.js 18+ installed
Transactional account with API key
Verified sending domain

CODE

Full Example

send-email.ts

import { Transactional } from '@transactional/sdk';

const client = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY!,
});

async function sendEmail() {
  const { data, error } = await client.emails.send({
    from: 'hello@yourdomain.com',
    to: 'recipient@example.com',
    subject: 'Hello from Transactional!',
    html: '<h1>Welcome!</h1><p>This is your first email.</p>',
    text: 'Welcome! This is your first email.',
  });
  if (error) {
    console.error('Failed to send email:', error.message);
    return;
  }
  console.log('Email sent successfully!');
  console.log('Message ID:', data.id);
  console.log('Status:', data.status);
}

sendEmail();

Understanding the Code

Initializing the Client

const client = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY!,
});

Always use environment variables for your API key. Never hardcode it in your source code.

Send Options

The send method accepts these parameters:

Parameter	Type	Required	Description
`from`	string	Yes	Sender email address
`to`	string \| string[]	Yes	Recipient(s)
`subject`	string	Yes	Email subject line
`html`	string	No	HTML content
`text`	string	No	Plain text content
`cc`	string \| string[]	No	CC recipients
`bcc`	string \| string[]	No	BCC recipients
`replyTo`	string	No	Reply-to address

Response Handling

The SDK uses a result pattern that returns both data and error:

const { data, error } = await client.emails.send({...});
 
if (error) {
  // Handle the error
  console.error(error.code, error.message);
} else {
  // Use the data
  console.log(data.id);
}

Common Errors

Invalid From Address

Make sure the from address uses a domain you've verified in Transactional.

Missing Content

You must provide either html or text content (ideally both for accessibility).

Rate Limiting

If you're sending many emails, consider using batch sending instead.

Sources & References

[1]Node.js Fetch API — Node.js Foundation
[2]TypeScript Handbook — Microsoft
[3]MDN Web Docs - Using the Fetch API — Mozilla

Send Batch Emails

Learn how to send batch emails efficiently with the Transactional TypeScript SDK. Includes error handling and rate limiting strategies.

Handle Webhooks

Learn how to receive and process webhook events from Transactional. Track email opens, clicks, bounces, and more in real-time.