# Quickstart

> Send your first email in five minutes with a test key — curl, Node/TypeScript, Laravel, Python or Go.

Source: https://charchy.krd/docs/quickstart



You need a Charchy Send workspace. It is invite-only for now —
[request access](/docs/request-access).

<Callout title="Using an AI coding agent?">
  Copy a ready prompt for Next.js, Convex, Laravel, Express or Django from
  [Build with AI](/docs/build-with-ai). It covers everything on this page.
</Callout>

### Get a test key

Your welcome screen has a **test key** ready (`chy_test_…`); make more under
**API keys**. A test key goes through every check a live key does but never
sends a real email, and it is free. Put it in your server's environment:

```bash
export CHARCHY_SEND_KEY="chy_test_…"
```

Keys belong on your server. The API sends no CORS headers, so a call from
browser code fails — on purpose.

### Send an email

Send to `delivered@sim.charchy.krd`, a [magic address](/docs/test-mode#magic-addresses)
that always "delivers". With a test key, `from` can use any domain.

```ts
// npm install @charchy/send — or plain fetch: it is one JSON POST.
import { CharchySend } from "@charchy/send"

const send = new CharchySend() // reads CHARCHY_SEND_KEY when a request is made

const { data, error } = await send.emails.send(
  {
    from: "My App <hello@example.com>",
    to: "delivered@sim.charchy.krd",
    subject: "Hello from Charchy Send",
    html: "<p>It works.</p>",
  },
  { idempotencyKey: "quickstart/1" }
)

if (error) throw error // error.code, error.message, error.docs
console.log(data.id) // "em_…"
```

```bash
curl https://api.charchy.krd/v1/emails \
  -H "Authorization: Bearer $CHARCHY_SEND_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart/1" \
  -d '{
    "from": "My App <hello@example.com>",
    "to": ["delivered@sim.charchy.krd"],
    "subject": "Hello from Charchy Send",
    "html": "<p>It works.</p>"
  }'
```

```php
// .env: CHARCHY_SEND_KEY=chy_test_…
// config/services.php: 'charchy_send' => ['key' => env('CHARCHY_SEND_KEY')],
use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.charchy_send.key'))
    ->withHeaders(['Idempotency-Key' => 'quickstart/1'])
    ->acceptJson()
    ->post('https://api.charchy.krd/v1/emails', [
        'from' => 'My App <hello@example.com>',
        'to' => ['delivered@sim.charchy.krd'],
        'subject' => 'Hello from Charchy Send',
        'html' => '<p>It works.</p>',
    ])
    ->throw();

echo $response->json('id'); // "em_…" — try it in php artisan tinker
```

```python
import os
import requests

response = requests.post(
    "https://api.charchy.krd/v1/emails",
    headers={
        "Authorization": f"Bearer {os.environ['CHARCHY_SEND_KEY']}",
        "Idempotency-Key": "quickstart/1",
    },
    json={
        "from": "My App <hello@example.com>",
        "to": ["delivered@sim.charchy.krd"],
        "subject": "Hello from Charchy Send",
        "html": "<p>It works.</p>",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["id"])  # "em_…"
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"from":    "My App <hello@example.com>",
		"to":      []string{"delivered@sim.charchy.krd"},
		"subject": "Hello from Charchy Send",
		"html":    "<p>It works.</p>",
	})

	req, _ := http.NewRequest("POST", "https://api.charchy.krd/v1/emails", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CHARCHY_SEND_KEY"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "quickstart/1")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var result struct {
		ID     string `json:"id"`
		Status string `json:"status"`
	}
	json.NewDecoder(res.Body).Decode(&result)
	fmt.Println(res.StatusCode, result.ID) // 200 em_…
}
```

The response comes back at once:

```json
{ "id": "em_8f2k1x9q4w7m3n5p6r0s2t4v", "status": "queued" }
```

### Watch it arrive

In **Emails** in the dashboard, the email appears once accepted, turns
**sent**, then **delivered** a second later. Or ask the API (reading needs a
key with full permission, like the welcome-screen one):

```ts
const { data, error } = await send.emails.get("em_8f2k1x9q4w7m3n5p6r0s2t4v")
console.log(data?.status) // "delivered"
```

```bash
curl https://api.charchy.krd/v1/emails/em_8f2k1x9q4w7m3n5p6r0s2t4v \
  -H "Authorization: Bearer $CHARCHY_SEND_KEY"
```

Try `bounced@sim.charchy.krd` too, to see what your code does with a bounce.

### Add your domain

Real emails leave from your own domain. In **Domains**, add it and publish
the three DNS records shown — or press **Add with Cloudflare**. See
[Domains & DNS](/docs/domains).

### Go live

Create a **live key** (`chy_live_…`; you accept the Charchy Send terms
first) and change `from` to an address on your verified domain. Until your
workspace is approved, a live key sends only to your own team's addresses, up
to 50 a day, free — enough to see a real email in your inbox. Once approved
and paid, it sends to anyone.

## Next

* Tell your server what happened to each email: [Webhooks](/docs/webhooks).
* Never send an email twice: [Idempotency](/docs/idempotency).
* Codes that expire: [`expires_at`](/docs/scheduling#expires_at).
* Every field: [Send an email](/docs/send-email).
