Quickstart

Quickstart

Send your first email through Optail in under 5 minutes.

1. Install the SDK

npm install optail

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';

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

• API Reference — Full REST API documentation
• Node.js SDK — Complete SDK method reference
• Template Guide — Create MJML templates with variables
• Unsubscribe Management — Set up suppression groups