flutter_coremail

Typed Coremail account configuration and mail clients for Dart and Flutter. The package provides an IMAP/SMTP facade backed by enough_mail, plus a small, session-bound adapter for Coremail Webmail JSON-RPC actions.

This package is an independent community project and is not affiliated with Coremail.

Features

• Configure IMAP, SMTP, optional POP3, and Webmail endpoints explicitly.
• Connect to a Coremail mailbox with a normal or dedicated client password.
• List and select folders, count unread messages, fetch pages, and search.
• Mark messages read or unread, move or delete messages, and manage folders.
• Build and send MIME messages using enough_mail types.
• Integrate application-owned WebView, CAS, or SSO flows without storing cookies.
• Call selected private Webmail JSON-RPC actions with an existing session.

Installation

Add the package to your application:

dart pub add flutter_coremail

For Flutter applications, the equivalent command is:

flutter pub add flutter_coremail

The package uses dart:io for its Webmail HTTP client, so the Webmail client is intended for Android, iOS, Linux, macOS, and Windows. The IMAP/SMTP facade also depends on the platform support provided by enough_mail.

Configure A Mailbox

Coremail installations can use different hostnames and ports. Ask the mail administrator for the IMAP and SMTP settings instead of relying on defaults.

import 'package:flutter_coremail/flutter_coremail.dart';

const server = CoremailServerConfiguration(
  imap: CoremailEndpoint(
    host: 'imap.example.edu',
    port: 993,
    security: CoremailTransportSecurity.implicitTls,
  ),
  smtp: CoremailEndpoint(
    host: 'smtp.example.edu',
    port: 465,
    security: CoremailTransportSecurity.implicitTls,
  ),
  webmailBaseUri: Uri.parse('https://mail.example.edu'),
);

final account = CoremailAccount(
  username: 'student@example.edu',
  password: 'dedicated-client-password',
  displayName: 'Student mailbox',
  server: server,
);

implicitTls is appropriate for common IMAPS/SMTPS ports such as 993 and 465. Use startTls or plain only when the administrator explicitly requires it. A dedicated client password is preferable when the deployment provides one; it can usually be revoked independently of the Webmail password.

Read Mail

CoremailClient keeps the connection lifecycle explicit. Select a mailbox before fetching or searching its messages.

final client = CoremailClient(account);

try {
  await client.connect();
  await client.selectInbox();

  final unread = await client.unreadCount();
  print('$unread unread messages');
  final messages = await client.fetchMessages(count: 20);

  for (final message in messages) {
    print('${message.decodeSubject()} from ${message.from}');
  }

  if (messages.isNotEmpty) {
    await client.markRead(messages.first);
  }
} finally {
  await client.disconnect();
}

To work with another folder, list available mailboxes and pass one to selectMailbox or fetchMailboxMessages:

final mailboxes = await client.listMailboxes();
final archive = mailboxes.firstWhere((mailbox) => mailbox.name == 'Archive');
await client.selectMailbox(archive);
final archivedMessages = await client.fetchMessages(count: 20);

The facade returns enough_mail types, so use MimeMessage, Mailbox, MailSearch, MailAddress, and related types from that package for advanced message handling.

Send Mail

Create MIME messages with enough_mail's MessageBuilder, then send them through the same connected client:

import 'package:enough_mail/enough_mail.dart';

final message = MessageBuilder.prepareMultipartAlternativeMessage(
  plainText: 'Hello from Coremail.',
  htmlText: '<p>Hello from Coremail.</p>',
)
  ..from = [const MailAddress('Student', 'student@example.edu')]
  ..to = [const MailAddress('Recipient', 'recipient@example.edu')]
  ..subject = 'Test message';

await client.sendMessage(message.buildMimeMessage());

Use sendMessageWithOptions when the sent-folder behavior or SMTP recipient list needs to be controlled explicitly.

Webmail And SSO

CoremailWebClient does not perform login, CAS, SSO, WebView navigation, or cookie storage. The host application must complete authentication in its own WebView or SSO flow and provide a short-lived CoremailWebSession:

final session = CoremailWebSession(
  baseUri: Uri.parse('https://mail.example.edu'),
  cookieHeader: cookieHeaderFromWebView,
  sid: sidFromRedirect,
);
final webClient = CoremailWebClient(session);

try {
  final appPassword = await webClient.createAppPassword(name: 'My app');
  print('Created client password ${appPassword.id}.');
} finally {
  webClient.close();
}

The current Webmail adapter exposes user:addAppPwd and user:deleteAppPwds, and also supports explicit calls through call. These are private, deployment-dependent endpoints rather than a stable official Coremail API. Validate them against the target installation before production use. Never log or persist cookieHeader, sid, or the returned password.

For the intended login boundary and observed request shapes, see doc/coremail-flow.md and doc/coremail-web-api.md.

API Overview

Type	Purpose
CoremailEndpoint	Host, port, and TLS mode for one service
CoremailServerConfiguration	IMAP, SMTP, POP3, and Webmail settings
CoremailAccount	Mailbox credentials and server configuration
CoremailClient	IMAP mailbox operations and SMTP sending
CoremailWebSession	Existing authenticated Webmail session data
CoremailWebClient	Session-bound Webmail JSON-RPC calls
CoremailSsoAdapter	Application-owned SSO integration boundary

Security And Compatibility

• Do not commit passwords, cookies, session IDs, or client secrets.
• Prefer TLS endpoints and dedicated client passwords.
• Confirm sends, deletes, moves, and folder changes in the host application.
• Coremail deployments vary by release and administrator configuration.
• Test against a disposable account before enabling write operations.
• CoremailException categorizes client failures; underlying protocol errors may still be thrown by enough_mail.

Development

dart format lib test example
dart analyze
dart test
dart pub publish --dry-run

License

MIT. See LICENSE.