Skip to main content

Email

Arsel sends two kinds of email, and the distinction shapes everything else on this page.

Transactional email is one message triggered by something a specific person did — a receipt, a password reset, an OTP. You call POST /email/send with explicit recipient addresses and it goes out immediately.

Campaign email is one message sent to an audience you defined — a newsletter, an announcement. You create a campaign, attach lists or tags, then send or schedule it. Recipients are resolved from your audience at send time, not supplied by you.

Both paths share the same delivery infrastructure, the same tracking, and the same domain requirement.

Before your first send​

Email is the only channel with a hard setup gate: verify a sending domain. Arsel rejects any from address on an unverified domain, on both the transactional and campaign paths. Verification means publishing SPF, DKIM and DMARC records — there are step-by-step guides for Cloudflare, GoDaddy, Namecheap, Route 53 and Hostinger.

Once you are sending, sender reputation becomes the thing to watch. Bounce and complaint rates are monitored continuously, and sustained bad rates suspend sending for your organization.

Sending transactional email​

curl -X POST "https://api.arsel.sa/v1/email/send" \
  -H "Authorization: Bearer be_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-receipt" \
  -d '{
    "from": "receipts@yourdomain.com",
    "from_name": "My App",
    "to": ["customer@example.com"],
    "subject": "Your order {{order_id}}",
    "template_id": "0192a1b2-c3d4-7e5f-9000-abcdef123456",
    "variables": { "order_id": "1042" }
  }'

Things worth knowing before you build against it:

  • Exactly one content source. Provide html, text, or template_id — not a template alongside inline content. html and text together are fine, and produce a multipart message.
  • 50 recipients per message, counting to + cc + bcc combined. Larger sends belong in a campaign, or split across calls.
  • 202 means queued. Poll GET /email/:id for per-recipient delivery status.
  • Use an Idempotency-Key. A timed-out request you retry blindly sends the receipt twice. See Idempotency.
  • Open and click tracking is message-level for multi-recipient emails. With cc/bcc in play you cannot attribute an open to a specific address.

Full parameter list: Send Email.

Sending a campaign​

A campaign is a three-step lifecycle rather than a single call:

  1. Create — POST /email/campaigns. Every field is optional, so you can create an empty draft and fill it in later. Recipients come from list_ids and tag_ids, not from an address array.
  2. Update — the campaign stays fully editable while it is Draft or Scheduled.
  3. Send — POST /email/campaigns/:id/send. Omit scheduled_at to send now; include a future ISO 8601 datetime to schedule. Re-send with a new scheduled_at to reschedule, or cancel before it goes.

Status progresses Draft → Queued → Sending → Sent, or Draft → Scheduled → Queued → … Poll GET /email/campaigns/:id.

Unsubscribe is enforced

Every marketing campaign must offer an opt-out. Arsel enforces this with the reserved {{unsubscribe_link}} variable — see Unsubscribe compliance.

Templates​

Campaigns need a template_id; transactional sends can optionally use one. You have three routes to one:

RouteHow
Build it in the dashboardThe visual editor under Templates
Create it via APIPOST /templates
Copy a starter designBrowse the gallery, then copy it into your own templates in one call

Templates support {{variable}} placeholders, filled from the variables object on a transactional send or from contact properties on a campaign. Define the properties you want to merge from in the Audience guide.

Sending over SMTP​

If your application already speaks SMTP, you can point it at smtp.arsel.sa and send without touching your email code. Messages go through the same pipeline, tracking and analytics as API sends.

The trade-off is capability: SMTP sends messages, but listing status and per-recipient tracking still come from the REST API. See SMTP for connection details and credential management, and SMTP client setup for worked examples across languages and frameworks.

Reference​

Send Email · List · GetTransactional endpoints
CampaignsCreate, update, send, cancel, delete
Templates · GalleryContent