Dart / Flutter

Installation

Add to `pubspec.yaml`

dependencies:
  keplars: ^1.0.15

Then run:

dart pub get

Set your API key

KEPLARS_API_KEY=kms_your_workspace_id.live_your_secret

Send your first email

import 'package:keplars/keplars.dart';
import 'dart:io';

void main() async {
  final client = Keplars(apiKey: Platform.environment['KEPLARS_API_KEY']!);

  final response = await client.emails.send(SendEmailRequest(
    to:      '[email protected]',
    from:    '[email protected]',
    subject: 'Hello!',
    body:    '<h1>It works!</h1>',
    isHtml:  true,
  ));

  print('ID: ${response.id}');
  client.close();
}

Priority Levels

Method	Delivery	Use case
`sendInstant`	0–5 seconds	OTP, 2FA, password reset
`sendHigh`	0–30 seconds	Transactional confirmations
`send` / `sendAsync`	0–5 minutes	Welcome emails, notifications
`sendBulk`	Background	Newsletters, campaigns

await client.emails.sendInstant(request);
await client.emails.sendHigh(request);
await client.emails.send(request);
await client.emails.sendBulk(request);

Using Templates

final response = await client.emails.sendInstant(SendEmailRequest(
  to:         '[email protected]',
  from:       '[email protected]',
  templateId: 'your-template-id',
  params: {
    'user_name':         'Jane',
    'verification_code': '123456',
  },
));

Schedule an Email

final response = await client.emails.schedule(ScheduleEmailRequest(
  to:           '[email protected]',
  from:         '[email protected]',
  subject:      'Weekly digest',
  body:         '<p>Here is your digest.</p>',
  isHtml:       true,
  scheduledFor: '2026-02-01T09:00:00Z',
  timezone:     'America/New_York',
));

Error Handling

import 'package:keplars/keplars.dart';

try {
  final response = await client.emails.sendInstant(request);
} on AuthenticationException {
  print('Invalid API key');
} on RateLimitException catch (e) {
  print('Rate limit hit, retry after: ${e.retryAfter}');
} on KeplarsException catch (e) {
  print('Error: ${e.message}');
} finally {
  client.close();
}

Flutter Usage

Store the client as a singleton (e.g., with a service locator) and call client.close() when the app disposes:

class EmailService {
  final _client = Keplars(apiKey: const String.fromEnvironment('KEPLARS_API_KEY'));

  Future<void> sendWelcome(String email) async {
    await _client.emails.sendInstant(SendEmailRequest(
      to:      email,
      from:    '[email protected]',
      subject: 'Welcome!',
      body:    '<h1>Welcome aboard!</h1>',
      isHtml:  true,
    ));
  }

  void dispose() => _client.close();
}

Admin API

Need to manage contacts, audiences, automations, or domains? Use an admin key - same client, different key suffix:

final client = Keplars(apiKey: 'kms_xxx.adm_xxx');

await client.contacts.add(AddContactRequest(email: '[email protected]', name: 'Jane'));
await client.audiences.create(name: 'Newsletter');
await client.automations.enroll('auto_id', '[email protected]');
await client.domains.verify('domain_id');

See the full Admin API reference.

Next Steps

Admin API - Contacts, audiences, automations, domains
Send Emails - API reference
Email Templates - Build reusable templates
Schedule Emails - Delayed delivery

Dart / Flutter

On this page