--- title: Quickstart path: quickstart status: published --- # Quickstart Your first ScaiSend email in five minutes. Assumes you already have a ScaiSend instance (managed or self-hosted) and a user account with `mail.send` permission. ## 1. Get an API key From the admin UI: **API Keys → Create**. Pick a name (`my-first-integration`) and an environment: - `Live` keys (`sg_live_*`) send real email. - `Test` keys (`sg_test_*`) enable sandbox mode — requests are fully validated but no email is delivered. Start with a test key. Copy it; the full secret is shown exactly once. If you don't have admin UI access, ask your tenant admin to create one, or POST to `/v3/api_keys` if you have `admin.api_keys` permission. ## 2. Add and verify a sender domain Live keys will only deliver mail from a verified sender domain. Test keys skip this check. ```bash curl -X POST https://scaisend.scailabs.ai/api/admin/domains \ -H "Authorization: Bearer $SCAISEND_JWT" \ -H "Content-Type: application/json" \ -d '{"domain": "mail.example.com"}' ``` ScaiSend generates a DKIM keypair and returns the DNS records you need to publish: ```json { "id": "dom_abc123", "domain": "mail.example.com", "verified": false, "dkim_selector": "scaisend", "dns_records": [ {"type": "TXT", "host": "scaisend._domainkey.mail.example.com", "value": "v=DKIM1; k=rsa; p=MIIBIj..."}, {"type": "TXT", "host": "mail.example.com", "value": "v=spf1 include:scaisend.scailabs.ai ~all"}, {"type": "TXT", "host": "_dmarc.mail.example.com", "value": "v=DMARC1; p=none; rua=mailto:dmarc@example.com"} ] } ``` Publish the records. Then verify: ```bash curl -X POST https://scaisend.scailabs.ai/api/admin/domains/dom_abc123/verify \ -H "Authorization: Bearer $SCAISEND_JWT" ``` For this quickstart, you can skip the domain step if you're using a test key. ## 3. Send an email ### Request ```bash curl -X POST https://scaisend.scailabs.ai/v3/mail/send \ -H "Authorization: Bearer $SCAISEND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "personalizations": [ {"to": [{"email": "you@example.com"}]} ], "from": {"email": "hello@mail.example.com", "name": "ScaiSend Quickstart"}, "subject": "Hello from ScaiSend", "content": [ {"type": "text/plain", "value": "It works."} ] }' ``` ```python import os import httpx resp = httpx.post( "https://scaisend.scailabs.ai/v3/mail/send", headers={"Authorization": f"Bearer {os.environ['SCAISEND_API_KEY']}"}, json={ "personalizations": [ {"to": [{"email": "you@example.com"}]} ], "from": {"email": "hello@mail.example.com", "name": "ScaiSend Quickstart"}, "subject": "Hello from ScaiSend", "content": [ {"type": "text/plain", "value": "It works."} ], }, ) resp.raise_for_status() print(resp.json()) ``` ```typescript const resp = await fetch("https://scaisend.scailabs.ai/v3/mail/send", { method: "POST", headers: { "Authorization": `Bearer ${process.env.SCAISEND_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ personalizations: [ { to: [{ email: "you@example.com" }] } ], from: { email: "hello@mail.example.com", name: "ScaiSend Quickstart" }, subject: "Hello from ScaiSend", content: [ { type: "text/plain", value: "It works." } ], }), }); const data = await resp.json(); console.log(data); ``` ### Response ```json { "message_id": "msg_01HXYZ123..." } ``` HTTP status is `202 Accepted`. The email is queued; actual delivery happens in the background. ## 4. Check what happened Poll the message you just sent: ```bash curl https://scaisend.scailabs.ai/v3/messages/msg_01HXYZ123 \ -H "Authorization: Bearer $SCAISEND_API_KEY" ``` ```python resp = httpx.get( f"https://scaisend.scailabs.ai/v3/messages/{message_id}", headers={"Authorization": f"Bearer {os.environ['SCAISEND_API_KEY']}"}, ) msg = resp.json() print(msg["status"], msg["events"]) ``` You'll see a status (`queued`, `processing`, `sent`, `delivered`, `bounced`, `sandbox`, etc.) and an event timeline: ```json { "id": "msg_01HXYZ123", "status": "delivered", "subject": "Hello from ScaiSend", "from_email": "hello@mail.example.com", "to_emails": ["you@example.com"], "events": [ {"event_type": "processed", "timestamp": "2026-04-23T10:00:00Z"}, {"event_type": "delivered", "timestamp": "2026-04-23T10:00:02Z", "smtp_response": "250 2.0.0 OK"} ], "created_at": "2026-04-23T10:00:00Z", "delivered_at": "2026-04-23T10:00:02Z" } ``` If you used a test key, the status will be `sandbox` and there will be no `delivered` event — that's expected. That's it. You just sent a ScaiSend email. ## 5. Next: add a template Dynamic templates let you send structured emails without rebuilding the HTML every time. Create one: ```bash curl -X POST https://scaisend.scailabs.ai/v3/templates \ -H "Authorization: Bearer $SCAISEND_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "welcome-email", "generation": "dynamic"}' ``` Add a version with Handlebars markup: ```bash curl -X POST https://scaisend.scailabs.ai/v3/templates/d-abc123/versions \ -H "Authorization: Bearer $SCAISEND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "v1", "subject": "Welcome, {{name}}", "html_content": "

Hi {{name}}!

Your plan: {{plan}}.

", "plain_content": "Hi {{name}}! Your plan: {{plan}}.", "active": 1 }' ``` Send using the template: ```bash curl -X POST https://scaisend.scailabs.ai/v3/mail/send \ -H "Authorization: Bearer $SCAISEND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "personalizations": [ { "to": [{"email": "you@example.com"}], "dynamic_template_data": {"name": "Ada", "plan": "Pro"} } ], "from": {"email": "hello@mail.example.com"}, "template_id": "d-abc123" }' ``` See [Templates](tutorials/templates) for the full syntax (conditionals, iteration, helpers). ## What's next - [Authentication](concepts/authentication) — API keys vs JWTs, scopes, when to use which. - [Your First Integration](tutorials/first-integration) — full walk-through with error handling, retries, and webhooks. - [Sending Mail](tutorials/sending-mail) — the full `/v3/mail/send` reference.