Collecting Subscribers via SDK¶

The MailJawn Swift SDK lets your iOS and macOS app identify users as subscribers, set custom properties, and track events — all without building API calls by hand.

SDK Initialization¶

Configure the SDK once at app launch with your API key and app ID:

MailJawn.configure(
    apiKey: "mj_xxxxxxxx...",
    projectId: "550e8400-e29b-41d4-a716-446655440000"
)

Parameter	Required	Description
`apiKey`	Yes	API key with `mj_` prefix (needs `subscribers:write` scope)
`projectId`	Yes	UUID of your app
`baseUrl`	No	Override for self-hosted installations

Tip

Create your API key in the Dashboard under Settings > API Keys. Make sure it has the subscribers:write and events:write scopes.

Identifying Users¶

Set a Local User ID¶

MailJawn.identify(userId: "user_12345")

Sets a local identifier for the current user. This is stored on-device only and used for local tracking.

Set Email (Creates Subscriber)¶

MailJawn.setEmail("jane@example.com")

This triggers a call to the /identify endpoint, which creates the subscriber if they don't exist or updates them if they do. A welcome automation fires for newly created subscribers by default.

Set Custom Properties¶

MailJawn.setUserProperties([
    "app_subscription_status": "premium",
    "favorite_category": "dinner",
    "referral_code": "FRIEND10"
])

This also triggers an /identify call and merges the properties into the subscriber's custom fields. Existing keys are updated; unmentioned keys are left untouched.

Auto-Collected Fields¶

The SDK automatically collects and sends these fields on every identify call — no code required:

Field	Example	Description
`device_type`	`"iPhone"`, `"iPad"`, `"Mac"`	Device hardware type
`os_version`	`"iOS 17.2"`, `"macOS 14.1"`	Operating system version
`app_version`	`"2.3.1"`	Your app's bundle version
`locale`	`"en_US"`, `"it_IT"`	Device locale
`timezone`	`"America/New_York"`	IANA timezone
`sdk_version`	`"1.0.0"`	MailJawn SDK version

These are stored as indexed database columns for fast querying and can be used in segment rules.

Tracking Events¶

MailJawn.track(
    event: "view_recipe",
    properties: [
        "recipe_id": "abc123",
        "category": "dinner"
    ]
)

Events are used for behavioral automation triggers. Each event gets a client-generated UUID for idempotent processing.

Parameter	Required	Description
`event`	Yes	Event name (e.g., `"view_recipe"`, `"complete_purchase"`)
`properties`	No	Event-specific metadata as key-value pairs

Resetting User Data¶

MailJawn.reset()

Clears the local user ID, subscriber ID, and any queued events. Use this when a user logs out of your app.

Offline Behavior¶

The SDK is designed to work reliably on mobile networks:

Write-ahead persistence — Events are written to disk before being added to the memory queue, so nothing is lost if the app is terminated
Client-generated event IDs — Each event gets a UUID for deduplication on the server
Automatic retry — Failed requests are retried with exponential backoff
Network monitoring — The queue flushes automatically when connectivity is restored

You can also force a flush at any time:

MailJawn.flush()

Platform Requirements¶

Platform	Minimum Version
iOS	15.0
macOS	12.0

All public SDK methods are thread-safe.

See also: Integrations > Swift SDK Reference for the full method reference and advanced configuration.