Skip to main content

Quickstart

Send your first email through Optail in under 5 minutes.

1. Install the SDK​

npm install @optail/node

2. Get your API key​

  1. Sign in to the Optail dashboard
  2. Go to Settings > API Keys
  3. Click Create API Key, give it a name, and select the SEND permission
  4. Copy the key -- it is only shown once

Set it as an environment variable:

export OPTAIL_API_KEY="ms_live_..."

3. Connect a provider​

Before sending, you need at least one email provider connected. In the dashboard:

  1. Go to Providers > Connect Provider
  2. Select your provider (SendGrid, Postmark, Mailgun, or Amazon SES)
  3. Enter your provider credentials
  4. Verify your sending domain

See the Provider Setup guides for detailed instructions.

4. Send your first email​

import { Optail } from '@optail/node';

const optail = new Optail({
  apiKey: process.env.OPTAIL_API_KEY,
});

const result = await optail.send({
  to: 'user@example.com',
  from: 'hello@yourdomain.com',
  subject: 'Welcome!',
  html: '<h1>Hello World</h1>',
  tags: ['welcome'],
});

console.log(result.messageId);
// => "a1b2c3d4-..."
console.log(result.status);
// => "queued"

The API returns 202 immediately -- Optail queues the email and delivers it through the resolved provider asynchronously.

5. Send with a template​

If you have created a template in the dashboard, you can reference it by ID:

const result = await optail.send({
  to: 'user@example.com',
  from: 'hello@yourdomain.com',
  subject: 'Welcome, {{name}}!',
  templateId: 'your-template-id',
  variables: {
    name: 'Jane',
    activationUrl: 'https://app.example.com/activate?token=abc',
  },
  tags: ['welcome', 'onboarding'],
});

6. Verify delivery​

Open the Optail dashboard and go to Messages. You should see your email with status tracking:

  • QUEUED -- Accepted and waiting for the worker
  • SENT -- Handed off to the provider
  • DELIVERED -- Provider confirmed delivery
  • BOUNCED -- Delivery failed (hard or soft bounce)

Next steps​