Flutter SMS Inbox

pub package pub points

Flutter android SMS inbox library based on Flutter SMS.

Installation

  1. Add the package to your project by the following command:
flutter pub add flutter_sms_inbox
  1. Add permission_handler package to your project because this package uses it for permission handling:
flutter pub add permission_handler
  1. Add the following permission to your AndroidManifest.xml file:
<uses-permission android:name="android.permission.READ_SMS"/>

Permission Handling

You need to request the SMS permission before dealing with the package. You can do it by using the permission_handler package. Here is an example of how to request the permission:

import 'package:permission_handler/permission_handler.dart';

Future<bool> getSmsPermission() async {
  var permissionStatus = await Permission.sms.status;

  if (permissionStatus.isGranted) {
    return true;
  } else if (permissionStatus.isDenied) {
    // We didn't ask for permission yet or the permission has been denied before but not permanently.
    if (await Permission.sms.request().isGranted) {
      return true;
    }
  } else if (permissionStatus.isPermanentlyDenied) {
    // The user opted to never again see the permission request dialog for this
    // app. The only way to change the permission's status now is to let the
    // user manually enable it in the system settings.
    openAppSettings();
  }
  return false;
}

Security notes

  • This plugin reads sensitive user data (SMS metadata and message body). Request READ_SMS only when needed and explain the purpose clearly to users.
  • Do not log, persist, or transmit SMS message content unless your app has a clear product and compliance need.
  • Handle permission denial gracefully. Calls may fail if SMS permission is revoked or restricted by device policy.

Error handling

Query calls can return structured platform errors:

  • permission_denied: READ_SMS was denied or unavailable.
  • invalid_arguments: one or more query arguments had an unexpected type or invalid value (start >= 0, count == -1 or >= 0, thread_id == -1 or >= 0, kinds must not be empty).
  • invalid_response: platform returned an unexpected payload shape.
  • query_failed: an unexpected platform failure occurred while querying SMS.

Querying SMS messages

Add the import statement for sms and create an instance of the SmsQuery class:

import 'package:flutter_sms_inbox/flutter_sms_inbox.dart';

void main() {
  SmsQuery query = SmsQuery();
}

Getting all SMS messages

List<SmsMessage> messages = await query.getAllSms;

Filtering SMS messages

The method querySms from the SmsQuery class returns a list of sms depending of the supplied parameters. For example, for querying all the sms messages sent and received write the followed code:

await query.querySms(
    kinds: [SmsQueryKind.inbox, SmsQueryKind.sent],
);

start and count are applied globally across the ordered kinds list (not per kind). For example, with kinds: [SmsQueryKind.inbox, SmsQueryKind.sent], start: 2, and count: 5, the query skips the first 2 messages across inbox then sent, and returns up to the next 5 messages from that combined ordered sequence.

For safety, queries are bounded in the Dart layer:

  • If count is omitted (or negative), the query uses a default cap of 200 messages.
  • Oversized request windows are clamped to 1000 messages before native queries are made.

The Android native layer also applies a defensive fallback cap of 1000 messages if requests arrive with unbounded or oversized values.

Privacy-safe usage patterns

  • Keep queries narrow: always set count and use address/threadId filters where possible.
  • Avoid rendering full SMS bodies by default in UI. Prefer a masked preview and add explicit user action before showing full content.
  • Do not log SMS body or sender details in production builds.
  • Do not persist or transmit SMS content unless it is strictly required and compliant with your product/privacy obligations.

You can also query all the sms messages sent and received from a specific contact:

await query.querySms(
    address: getContactAddress()
);

Libraries

flutter_sms_inbox