A modern SMS / MMS plugin for Android that provides comprehensive messaging functionality for Flutter applications.
Contributing / agents: see
AGENTS.mdfor build·test·verify, the four-package layering contract, and the "What NOT to do" rulings (Claude Code reads it viaCLAUDE.md). Governed by the Simple Zen Documentation Standard, Code Quality Standard, and Toolchain Architecture in Notion.
- Send and receive SMS and MMS messages
- Background message delivery (even when app is killed)
- Conversation thread management
- Contact and participant resolution
- MMS attachment support (images, video, audio)
- Runtime permissions + default-SMS-app role management are delegated
to
simple_permissions_nativeso consumers have one source of truth for access state.
| Android | iOS | Web | macOS | Windows | Linux |
|---|---|---|---|---|---|
| API 30+ | - | - | - | - | - |
Add to your pubspec.yaml:
dependencies:
simple_sms_native: ^0.5.1Declare these in your AndroidManifest.xml:
<uses-permission android:name="android.permission.SEND_SMS" />
<uses-permission android:name="android.permission.READ_SMS" />
<uses-permission android:name="android.permission.RECEIVE_SMS" />
<uses-permission android:name="android.permission.RECEIVE_MMS" />
<uses-permission android:name="android.permission.RECEIVE_WAP_PUSH" />Runtime grants + the default-SMS-app role go through
simple_permissions_native:
import 'package:simple_permissions_native/simple_permissions_native.dart';
// Check and request everything the plugin needs to function.
final ok = await SimplePermissionsNative.instance.requestAll(const [
ReceiveSms(),
ReadSms(),
SendSms(),
DefaultSmsApp(), // Android role; only the default SMS app can write
// the Telephony provider or mark messages delivered.
]);
if (!ok.isFullyGranted) {
// Show "grant to continue" banner / disable writes.
}
// Or observe reactively so the UI updates when the user grants via
// system Settings.
final observer = SimplePermissionsNative.instance.observe(const [
DefaultSmsApp(),
ReceiveSms(),
SendSms(),
]);| Operation | Needs |
|---|---|
| Read conversations / threads / messages | ReadSms |
| Receive inbound SMS broadcasts | ReceiveSms |
| Receive MMS / write Telephony provider | DefaultSmsApp |
| Send SMS | SendSms + DefaultSmsApp (to mark delivered) |
import 'package:simple_sms_native/simple_sms_native.dart';
void main() {
Android.initialize(
inboundSmsCallback: (Sms sms) {
print('SMS from ${sms.address}: ${sms.body}');
},
inboundMmsCallback: (Mms mms) {
print('MMS from ${mms.address}: ${mms.body}');
},
);
runApp(const MyApp());
}final result = await Android.instance.messaging.sendMessage(
message: OutboundMessage(
body: 'Hello from simple_sms_native!',
addresses: {'+15551234567'},
attachmentPaths: null,
),
);final service = LookupService();
// Find a contact by phone number
final contact = await service.lookupContactableByAddress('+15551234567');
// Get all SMS in a thread
final messages = await service.getSmsByThread(threadId);Read-state actions write the authoritative Android SMS/MMS store. Obtain the
DefaultSmsApp role through simple_permissions_native before calling them;
these methods do not request permissions.
import 'package:simple_sms_native/android.dart';
// The native ID is unique within its SMS or MMS table, so always pass its type.
await AndroidAction.markMessageAsUnread('42', channel: SmsMmsType.sms);
await AndroidAction.markMessageAsRead('42', channel: SmsMmsType.sms);
await AndroidAction.markMessageAsUnread('17', channel: SmsMmsType.mms);
await AndroidAction.markMessageAsRead('17', channel: SmsMmsType.mms);
// Conversation IDs are native thread IDs; these actions update both tables.
await AndroidAction.markConversationAsUnread('123');
await AndroidAction.markConversationAsRead('123');Each method returns Future<bool>: true means the provider reported updated
rows; false means no rows were updated. Conversation actions update only rows
whose read flag differs, so repeating an action on an unchanged conversation
returns false. A missing message or conversation also returns false.
Marking read sets READ=1 and SEEN=1. Marking unread sets READ=0 and preserves
SEEN, restoring the follow-up cue without making the message newly unseen.
Provider failures throw PlatformException with MARK_READ_FAILED or
MARK_UNREAD_FAILED; callers must handle these errors. Conversation writes
update SMS and MMS separately, so a provider failure can leave one table
updated. Retrying the same action safely sets the requested flags again.
The explicit read/unread method pairs provide the symmetric API. Existing
markMessageAsRead and markConversationAsRead callers remain supported.
AndroidDestructiveAction.deleteSend(messageUri: ..., clientCorrelationId: ..., threadId: ...) uses the native job index, not a conversation-history scan.
It captures at most 64 retained rows, preserves different SMS/MMS identities,
checks their provider generation and thread, and deletes older attempts before
the actual latest attempt. The default-SMS role is required. The durable job
fence rejects later sends with SEND_DELETED before radio handoff; deletion
cannot recall a message already handed to the carrier.
The returned SendDeletionReceipt includes complete, exact
confirmedMessageUris, their confirmedGenerations, and any partial failure.
A partial failure is progress, not success: the latest row remains until its
older attempts can be removed. Persist every confirmed identity in your host's
delete journal before calling acknowledgeSendDeletion with those exact URIs.
Acknowledgement is idempotent and never permits a later retry to send again.
After interruption, pendingSendDeletions reads the durable journal without
querying provider history. It accepts an optional thread filter, a lexical
afterClientCorrelationId cursor and a page limit of 1–64 (default 20).
At most 64 operations can await acknowledgement; new operations fail before
mutation while that backlog is full. Each operation has at most 64 rows.
Already acknowledged identities are omitted. Cancellation and bounded per-job
identity records remain in no-backup SQLite storage, without message content
or recipient numbers. A missing or unrecognized receipt fails validation.
Repeat deleteSend for the same queue identity and native thread to resume a
partially completed deletion. Replaying confirmations alone never resumes
provider writes. Preserve newer provider occurrences that reuse a confirmed
SMS URI: its generation is the raw SMS date. MMS uses an opaque mms: proof
containing the PDU's tr_id; neither a date rewrite nor reuse of its row ID
can authorize deletion of another transaction. Missing transaction proof and
legacy MMS date/row-ID metadata fail closed without adopting the current PDU.
Recording transaction identities permanently advances the local registry to
schema 3, which older readers reject. No legacy metadata is erased.
An unavailable or null SMS generation fails before creating a new deletion plan. An empty acknowledgement can retire
a completed plan whose confirmations were already acknowledged before an
interrupted completion commit.
The Android SMS store holds a thread's draft as one row: an SMS text draft
(MESSAGE_TYPE_DRAFT) or an MMS draft with attachments (msg_box 3). A
thread has one draft across both tables. These methods write it. Like
deletes, they require the DefaultSmsApp role and read the result back before
resolving.
// Thread IDs are native thread IDs; the thread must already exist.
final draftId = await AndroidDraftAction.saveSmsDraft(threadId: '123', body: 'See you at 6');
// On a multi-SIM device, store the draft on the conversation's SIM.
await AndroidDraftAction.saveSmsDraft(threadId: '123', body: 'See you at 6', subscriptionId: 2);
// A draft with attachments: 1 to 8 files, plus an optional body. The
// addresses are the thread's recipients and must resolve to that thread.
final mmsDraftId = await AndroidDraftAction.saveMmsDraft(
threadId: '123',
addresses: {'+15555550100'},
body: 'Photo from the trip',
attachmentPaths: ['/path/to/photo.jpg'],
);
// discarded, or alreadyAbsent when the thread had no draft.
final result = await AndroidDraftAction.discardDraft('123');A save leaves the thread exactly one draft: it deletes the thread's drafts of
the other kind and any extra rows another app left. An SMS save updates the
thread's draft in place, so its _id stays the same across saves. An MMS
draft keeps each file's raw bytes, typed by its extension, and is marked read
and seen; the save is verified against the bytes, flags, SIM and recipients the
provider kept. A file over 16 MiB, or attachments over 32 MiB together, are
refused with invalidArgument. The provider keeps a text/plain or
text/html attachment as text, so one that is not valid UTF-8 or is over
300 KiB fails the verification with draftWriteIncomplete. An SMS body must
not be blank; discard to clear a draft. Discarding the draft of a thread that
holds no other message also removes the thread, as Android does for any
delete. A write that can't be verified throws DraftWriteFailedException with
a DraftWriteFailureReason.
To read drafts back, list the drafts box with
MmsFilter(messageBoxes: [MessageBox.draft]), or leave them out with
MmsFilter(excludeMessageBoxes: [MessageBox.draft]) (which also drops rows
whose msg_box is NULL).
When your app is the default SMS app, messages arrive even when the app is killed. Define a top-level entrypoint:
@pragma('vm:entry-point')
void initializeApp() {
AndroidMessaging.initialize(
inboundSmsCallback: handleSms,
inboundMmsCallback: handleMms,
);
}See example/lib/background_example.dart for the full pattern.
Inbound callbacks may return void or bool, synchronously or asynchronously.
The plugin waits for completion, acknowledges a successful void callback, and
preserves an explicit Boolean acknowledgement. Callback exceptions remain
visible through INBOUND_MESSAGE_PROCESSING_ERROR.
The retained SMS/MMS code is maintained as Kotlin under
io.simplezen.simple_sms.mms: codec holds PDU parsing and composition,
storage holds persistence helpers, sending holds the outbound transaction
layer, and support holds the shared helpers. This internal namespace change
preserves the public Dart API, models, imports, and platform-channel contracts.
MMS transfer uses Android's SmsManager. The platform and the selected SIM's
carrier configuration own maximum-message-size and HTTP parameters; the plugin
does not ship a carrier APN table, mms_config.xml, or an 800 KiB size override.
The Verizon content-location completion in resolveVerizonDownloadUrl remains
part of inbound notification handling and is covered by native unit tests.
Outbound MMS persists the composed PDU once. Its send result reads that same
record, including the stored parts and addresses, through a canonical MMS URI.
Successful sends move it to the sent box; failures move it to the failed box.
The PDU type stays SEND_REQ, while the message box determines send status.
With simple-permissions and simple-query checked out beside this repo, run
the local gates before pushing:
flutter pub get
flutter analyze --no-fatal-warnings
flutter test
./scripts/verify_mms_migration.sh
flutter pub publish --dry-run
(cd example && flutter pub get && flutter build apk --debug)
(cd example/android && ./gradlew :simple_sms_native:testDebugUnitTest --console=plain)Check that the publish dry-run includes root LICENSE and NOTICE. LICENSE
contains every retained license so Flutter can include them in the consuming
app's license bundle; a standalone NOTICE is not automatically collected.
The migration check rejects production Java, retired upstream package names,
and the removed carrier XML files. These local gates compile and test the
code, but do not establish carrier interoperability.
Android hosts must declare an ACTION_SENDTO activity to qualify for the
default-SMS role. Include the sms, smsto, mms, and mmsto schemes, as the
example manifest demonstrates; see Android's Telephony requirements.
The example targets Android 16 (API 36), matching Unify.
For a Samsung Galaxy S24 Ultra with an active Verizon SIM, connect the phone
and record the tested commit, Android/One UI build, active SMS/data SIM, and
network state. Obtain the device ID with flutter devices, then run:
cd example
flutter run -d <device-id>In the example, tap Grant Permissions and Set as Default SMS App. Use test recipients and messages, and keep the Flutter console open: inbound callbacks print there. Repeat the following checks with mobile data available, first with Wi-Fi off and then with Wi-Fi on:
| Check | Evidence to record |
|---|---|
| Send and receive short SMS, Unicode SMS, and a multipart-length body | Recipient sees the complete text; returned native record and inbound callback match the SMS provider row. |
| Tap Send MMS with one image, then Send MMS (Multiple Attachments) with two distinct images | Recipient sees the text and all attachments; the returned record reports the actual send outcome. |
| Receive image MMS and a group MMS from another phone | One inbox record per message, expected sender/recipients, body and attachment MIME types; no duplicate record from paired WAP-push broadcasts. |
| Background the app and receive SMS/MMS | Provider persistence and callbacks still complete. For a terminated-process check, use the initializeApp entrypoint pattern in background_example.dart; swiping away the app is distinct from Android force-stop. |
| Deny SMS access or remove the default-SMS role and retry the affected operation | The permission state and operation error are visible; no false success or unintended provider write. Restore access before the next case. |
Inspect provider records through LookupService/simple_query in the test
host, including message ID, thread ID, type, read/seen state, and MMS part
count. The stock example is an interactive send/receive harness, not an
automated device suite or a provider-inspection screen. Record actual device
results separately from JVM/Dart test results; no Samsung/Verizon sign-off is
implied by a successful build or package dry-run.
Sms.person changes from String? to int? (UNFY-403). Android's SMS provider
uses an integer contact reference; Sms.fromRaw and Sms.fromJson now accept
the integer, null, and cached numeric strings. This fixes the populated
provider column failing conversation enrichment with a TypeError.
The MMS migration preserves the public Dart API and channel contracts, so the
next release uses a minor bump (0.5.1 to 0.6.0). The Cut Release workflow
owns the version and tag; follow release procedure in Linear after the device
regression and code review pass.
Local sibling overrides validate development sources, not the published
dependency graph. Release and publish workflows resolve the package and
bundled example without those overrides. simple_query ^0.2.2 is required for
the native ContentQuery API; published 0.2.0 lacks it and also has an
incompatible permissions constraint. Publish the required sibling versions
before cutting this release. Do not lower the constraint or bypass dependency
validation to make publication succeed.
The Android SMS/MMS internals contain Kotlin ports and adaptations of android-smsmms by Jacob Klinker, including the AOSP MMS stack it carried. The sending layer, PDU codec, persistence helpers, and associated types are derived licensed code. Their Apache-2.0 obligations remain after translation and namespace changes.
Retained source notices also name The Android Open Source Project, Esmertec AG, and The Linux Foundation. Android Gradle scaffolding retains The Flutter Authors' BSD attribution. See NOTICE for the component inventory and LICENSE for the complete license texts.
Original Simple Zen code is BSD 3-Clause. Retained android-smsmms/AOSP-derived components remain Apache-2.0, and Flutter scaffolding retains its upstream BSD terms. All license texts are included in LICENSE.