DOCSEARCHbyAlgolia
Submit Docs

Arsel Documentation

website·Indexed 30 days ago

https://docs.arsel.sa

Developer documentation for the Arsel API and SDKs, providing tools for managing contacts and sending communications via email (transactional and campaigns), SMS, WhatsApp, and push notifications. Includes guides on DNS configuration for SPF, DKIM, and DMARC, event tracking, and API basics such as rate limiting, idempotency, and cursor-based pagination.

Tokens
57.2K
Snippets
256
Records
385
Agent score
48%

What's inside Arsel

  1. Overview of Arsel communication channels

    Arsel supports four primary communication channels for both transactional messaging and campaign lifecycles: Email, SMS, WhatsApp, and Push Notifications. Additionally, it provides tools for managing contacts (audience) and custom events to trigger automations.

  2. Overview of Arsel communication channels

    Arsel provides four primary channels for sending messages via its REST API. Each channel has specific prerequisites for activation:

    • Email: Used for transactional emails and campaigns with tracking for delivery, opens, clicks, bounces, and complaints. Supports REST or plain SMTP. Requires a verified domain.
    • SMS: Used for transactional SMS and campaigns specifically for Saudi Arabia and Egypt, including delivery receipts. Requires a registered sender name.
    • WhatsApp: Used for transactional messages using Meta-approved templates. Requires a connected WhatsApp Business account.
    • Push Notifications: Delivers notifications to Android, iOS, and web under the user's own identity (Firebase project or Apple key). Requires a client SDK or server-side device registration.

  3. Overview of Arsel Multi-Channel API Capabilities

    Arsel provides a single set of REST conventions to send messages across four different communication channels: Email, SMS, WhatsApp, and Push notifications. The platform includes built-in analytics for tracking per-recipient delivery, opens, clicks, and bounces directly via the API, and provides Client SDKs for Web, Android, and iOS platforms.

  4. Overview of Arsel communication channels

    Arsel provides several communication channels for sending messages, each with specific setup requirements and behaviors:

    • Email: Used for transactional sends, campaigns, templates, SMTP configuration, domain verification, and managing sender reputation.
    • SMS: Covers sender-name registration, regional formats (KSA and Egypt), encoding, message parts, and campaigns.
    • WhatsApp: Focuses on template approval, filling placeholders, and tracking delivery states.
    • Push Notifications: Involves per-platform credential setup, device registration, targeting, and engagement reporting.

  5. Overview of Arsel Push Notification Credentials

    Arsel sends push notifications using your own sender identity via credentials you upload to the Arsel Dashboard under Integration > Push. Because Arsel does not proxy through its own sender, existing device tokens remain valid when migrating to Arsel, and you maintain full control by being able to revoke keys independently.

    PlatformRequired CredentialsSource
    AndroidFirebase service-account JSONYour Firebase project
    iOSAPNs auth key (.p8), Key ID, Team ID, and Bundle IDApple Developer Account
    WebAllowed origins for device registrationGenerated by Arsel

  6. Manage audience and behavioral triggers

    Arsel provides tools to manage recipients and automate messaging based on user behavior:

    • Audience Management: Handles contacts, identifiers, lists, tags, and custom properties.
    • Events & Automation: Allows sending product events, triggering automated workflows, and tracking conversion and revenue attribution.

  7. Understand Arsel credential types

    Arsel provides two distinct types of credentials based on their prefix. API keys (be_) are secret and must only be used on servers. Client keys (pub_) are publishable and intended for use in web or mobile applications for event ingestion and device registration via Client SDKs. These are separate from SMTP credentials (username/password), which are used exclusively for the SMTP server and cannot be used for the REST API.

  8. Understand the Arsel custom event lifecycle

    Custom events allow you to track product or system occurrences (e.g., order.completed) to trigger automations, segment contacts, and personalize messaging. The lifecycle consists of four stages:

    1. Definition: Create a named schema once (e.g., order.completed with specific fields).
    2. Sending: Report individual occurrences for specific contacts with a data payload.
    3. Validation: Arsel validates the payload against the schema. Matching payloads are accepted; others are rejected.
    4. Triggering: Automations subscribed to that event fire for the matching contact in real time.

  9. Retrieve a single tag by ID

    Use the GET /tags/:id endpoint to retrieve detailed information about a specific tag. You must provide the tag's unique ID as a path parameter and include a Bearer token for authorization. To list contacts associated with a specific tag, use the GET /contacts?tag_id=:id endpoint instead.
    curl "https://api.arsel.sa/v1/tags/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a" \
  -H "Authorization: Bearer <your-api-key>"

  10. Manage unsubscribe links in email templates

    To include a per-recipient tracked unsubscribe link in an email template, use the {{unsubscribe_link}} placeholder anywhere in the template HTML. If no unsubscribe element is present in the template, a footer is automatically appended at send time. Custom external unsubscribe URLs are not supported.

  11. Migrate an existing Web Push audience to Arsel

    To prevent existing web subscribers from becoming unreachable, you must import the VAPID keypair used by your previous provider. Browser subscriptions are bound to the applicationServerKey used at creation; using a different key will make existing subscriptions permanently unsignable. Importing is only available during the initial provisioning of Web Push.

  12. Migrate mobile push device tokens to Arsel

    Existing device tokens remain valid because the Firebase sender and Apple keys remain the user's. To migrate:

    1. Export current tokens with their contact identifiers.
    2. Import tokens in batches of 1,000 using the Bulk Register Devices API, omitting the sdk_version.
    3. For iOS: Ensure you are importing APNs device tokens. If your previous provider used FCM for iOS, those tokens are incompatible and users must re-register via the Arsel SDK.
    4. If tokens are from development builds, specify apns_environment as the default is production.
    Use the Bulk Register Devices endpoint for imports.