imap_client 0.2.7

  • Readme
  • Changelog
  • Example
  • Installing
  • 81

imap_client #

An interface to get emails via the imap protocol (version 4rev1)

This interface implements the IMAP protocol (version 4 rev 1) as described in rfc 3501. This package gives easy access to all commands and automatically analyzes responses.

Supported extensions:

  • RFC 2177: IMAP4 IDLE command

This package is made available under the GNU General Public License v3.0.

Usage #

This example connects the client to an imap server:

import 'package:imap_client/imap_client.dart';

main() async {
  ImapClient client = new ImapClient();
  
  await client.connect("imap.gmail.com", 993, true);
}

All commands are async methods that can be awaited for. On completion, most return an enum ImapTaggedResponse, which can be either:

  • OK: success
  • NO: command was unsuccessful
  • BAD: command not accepted by the server

Sometimes, there are commands which have other return data, like fetch or list.

To select a folder, a simple call to getFolder() is sufficient:

import 'package:imap_client/imap_client.dart';

main() async {
  ImapClient client = new ImapClient();
  
  await client.connect("imap.gmail.com", 993, true);
  
  ImapFolder inbox = client.getFolder("inbox");
}

This ImapFolder instance allows for actions in this specific folder. Folders can only exist once per name, so another call to ImapClient.getFolder() with the same name will return the same ImapFolder instance! If an instance is no longer needed, it can be marked for garbage collection via ImapFolder.destroy(). This will free up some ram and should especially be considered when working with many folders.

There are two types of handlers that are highly suggested to be implemented:

ALERT handler: #
void Function(String message)

The messages passed to this function are directly from the server and must be shown to the user (as defined in the protocol).

EXPUNGE handler: #
void Function(int number)

This function receives message numbers of messages that have been deleted.

Both can be set directly via the client instance, either via client.expungeHandler = ... or client.alertHandler = ...

ImapFolder.store(), ImapFolder.fetch() and ImapFolder.copy() need messages to work with. Those messages can either be provided via the optional messageId parameter, or if ranges are needed, via the optional messageIdRanges. One of the two must always be given.

Ranges have the following format: start:end, whereas end can also be *, which matches the highest possible number as determined by the server. This means that 1:* would match every mail in this folder.

To use message uids instead of relative numbers, the optional parameter uid can be set to true. Please note that responses from the server will also use uids instead of relative numbers.

Example:

await inbox.fetch(["BODY"], messageIds: [1]);

Authentication #

The last important thing would be logging in. There are three possible ways:

Preauth #

Preauth means that the client is already registered, this might be because credentials were already submitted via the url on connect.

Login #

The login command takes a username and password as parameters.

await client.login("username", "password");
Authenticate #

The authenticate command is used for any other authentication mechanisms. It takes an ImapSaslMechanism object and logs in via the mechanism defined there. "login" and "plain" are both already implemented, a short walk through on how to create a custom mechanism can be found in the wiki.

await client.authenticate(new ImapPlainAuth("username", "password"));

Closing the connection #

To close the connection, logout can either be called in a folder or the client itself.

Features and bugs #

Feel free to contribute to this project.

If you find a bug or think of a new feature, but don't know how to fix/implement it, please open an issue.

If you fixed a bug or implemented a new feature, please send a pull request.

0.2.7 #

  • Fix test cases for Socket's new usage of Uint8List instead of List<int>
  • Update dependencies

0.2.6 #

  • Fix #15 by translating folder names to utf-7 before sending it them to the server

0.2.5 #

  • Fix bodystructure parsing errors (issues #16, #18)

0.2.4 #

  • Fix #14 by using utf8.decode instead of standard String.fromCharCodes
  • Code cleanup: Follow latest best practices

0.2.3 #

  • Fix #13 by refreshing capabilities list after successful tls negotiation
  • Expose capabilities list and accepted auth methods

0.2.2 #

  • Merge #10, fix string with leading escaped character

0.2.1 #

  • Fix #4, bug that prevented mailboxes with spaces from being opened
  • Fix #7, bug that did not acknowledge escaped characters
  • Fix #8, add missing imap 4 rev 1 commands (subscribe, unsubscribe, lsub)

0.2.0 #

  • Version change, 1.0.0-alpha is lower than 0.1.3, which causes updates to fail

1.0.0-alpha #

  • Complete rewrite
  • Now easier to use and extend
  • Fix #2, a bug that prevents fetches
  • Change concept of folders to representation based instead of internal handling

0.1.3 #

  • Update test package to latest version
  • Do travis tests on stable, now that dart v2 is out of dev

0.1.2 #

  • Implement logging. Use printImapClientDebugLog() to display it.

0.1.1 #

  • Fix errors caused by older dart version 2.0.0-dev.63.0
  • Set minimum required sdk version to 2.0.0-dev.63.0

0.1.0 #

  • Initial version

example/example.dart

import 'package:imap_client/imap_client.dart';

main() async {
  // print log, helpful for debugging
  printImapClientDebugLog();

  ImapClient client = new ImapClient();
  // connect
  await client.connect("imap.gmail.com", 993, true);
  // authenticate
  await client.authenticate(new ImapPlainAuth("user@gmail.com", "password"));
  // get folder
  ImapFolder inbox = await client.getFolder("inbox");
  // get "BODY" for message 1
  print(await inbox.fetch(["BODY"], messageIds: [1]));
  // get "BODYSTRUCTURE" for message 1
  print(await inbox.fetch(["BODYSTRUCTURE"], messageIds: [1]));
  // close connection
  await client.logout();
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  imap_client: ^0.2.7

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:imap_client/imap_client.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
62
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
81
Learn more about scoring.

We analyzed this package on Oct 21, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.5.1
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, other

Primary library: package:imap_client/imap_client.dart with components: io.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
logging ^0.11.3+2 0.11.3+2
pedantic ^1.8.0+1 1.8.0+1
utf7 ^0.2.0 0.2.0
Dev dependencies
mockito ^4.1.1
test ^1.6.10