Skip to main content

Quickstart

Send your first email through the Arsel API and confirm it was delivered. About ten minutes, most of which is DNS propagation.

1. Verify a sending domain​

Email is the one channel you cannot try without setup: Arsel will reject a from address on an unverified domain. In the Arsel Dashboard go to Settings > Domains, add your domain, and publish the SPF, DKIM and DMARC records it gives you.

Records usually resolve within minutes, though some providers take up to a few hours. Domain verification walks through the process, and there are click-by-click guides for Cloudflare, GoDaddy, Namecheap, Route 53 and Hostinger.

Want to try something without DNS?

Custom events need no verification at all — you can POST /events/send the moment you have an API key. Come back here when your domain is ready.

2. Create an API key​

In the dashboard, generate a secret key. It looks like:

be_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep it server-side. It is shown once, so store it in your secrets manager now — see Authentication for rotation and for the separate publishable pub_ key that client SDKs use.

3. Send the 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: quickstart-001" \
  -d '{
    "from": "noreply@yourdomain.com",
    "from_name": "My App",
    "to": ["user@example.com"],
    "subject": "Hello from Arsel",
    "html": "<h1>Welcome!</h1><p>Your integration is working.</p>"
  }'

Response — 202 Accepted:

{
  "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a"
}

202 means queued, not delivered. The id is how you follow it.

The Idempotency-Key header is optional but worth adopting from the first call: retry the exact same request after a timeout and you get the original response back instead of a second email. See Idempotency.

4. Confirm delivery​

curl "https://api.arsel.sa/v1/email/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a" \
  -H "Authorization: Bearer be_your_api_key"
{
  "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
  "to": [
    { "email": "user@example.com", "status": "delivered", "timestamp": "2026-03-08T12:00:05.000Z" }
  ],
  "subject": "Hello from Arsel",
  "created_at": "2026-03-08T12:00:00.000Z"
}

Each recipient carries its own status, which starts at sent and advances as tracking events arrive — delivered, then opened or clicked, or bounced. The full list is in Get Email.

If it did not arrive, Errors covers what a rejection looks like and Sender reputation covers what happens when a domain starts bouncing.

Where to go from here​

Email guideTemplates, campaigns, attachments, and the SMTP route.
Audience guideCreate contacts so you can target people rather than raw addresses.
Events guideTrigger automations from your own product events.
API basicsPagination, rate limits, and the error envelope.