---
title: "Mail — Getting started"
description: "From zero to a signed, delivered transactional email: verify a domain, create a template, mint an API key, send."
url: https://productcraft.co/docs/mail/getting-started
---

[Mail docs](https://productcraft.co/docs/mail.md)

Getting started

# Send your first transactional email.

Ten minutes. DKIM-signed. From your own domain.

Step 1

## Pick a workspace

Open [console.productcraft.co/mail](https://console.productcraft.co/mail). If you don't have a ProductCraft account yet, sign up at [auth.productcraft.co](https://auth.productcraft.co/signup) first — every product in the console shares the same account. Once signed in, pick or create a workspace. The workspace is the boundary for your domains, templates, keys, and suppression list. Mail must be enabled for the workspace (sidebar → Workspace → Services). Use separate workspaces for dev / staging / prod isolation.

Step 2

## Add and verify a domain

From the Domains tab, click Add domain and enter the fqdn you want to send from. Mail generates a DKIM keypair for the domain and opens a setup checklist with four DNS records to set at your registrar — ownership, MX, DKIM, SPF.

```title="DNS records"
MX  acme.com                                → 10 mx.productcraft.co.
TXT acme.com                                → v=spf1 include:_spf.productcraft.co -all
TXT productcraft._domainkey.acme.com        → v=DKIM1; k=rsa; p=...
TXT _productcraft-verify.acme.com           → productcraft-verify=<token>
```

Once the records are set, the console re-checks them on its own every 30 seconds and ticks each step green as it lands. To force a lookup, open a record from the checklist and click **Check DNS now**. The domain flips to `active` once all four records pass.

Step 3

## Write a template

Templates use Handlebars — subject and body share the same syntax. A plain-text body is optional; if omitted, we derive it from the HTML for clients that can’t render rich content.

```title="welcome template"
name:      welcome
subject:   Welcome, {{name}}!
body_html: <h1>Hi {{name}},</h1>
           <p>Thanks for signing up for Acme.</p>
```

Step 4

## Mint an API key

From Workspace → API keys, click New API key. A key's access comes from the managed policies you bind to it (author them under Workspace → Policies); for a typical sender key, bind a policy that allows:

```title="policy actions"
✓ mail.send
✓ mail.read
```

The full key (starting with `pcft_live_`) is shown **once**. Copy it immediately into your secret store; if you lose it, revoke and mint a fresh one. Keys are scoped to the workspace.

Step 5

## Send

One HTTP call. :workspaceId is your workspace's UUID — find it on Workspace → General in the console, in the Resource URN field (pcft:workspace/<uuid>).

```bash title="send a message"
curl -X POST \
  https://api.mail.productcraft.co/v1/workspaces/:workspaceId/templates/welcome/send \
  -H "Authorization: Bearer pcft_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@acme.com",
    "to":   "user@example.com",
    "data": { "name": "Alice" }
  }'

→ HTTP/1.1 202 Accepted
{ "accepted": true, "from": "hello@acme.com", "to": "user@example.com",
  "subject": "Welcome, Alice!" }
```

The 202 confirms the message was rendered, DKIM-signed with your domain's private key, and queued. Delivery is async. Retries are safe if you pass an `Idempotency-Key` header — replays return the original response for 24 hours.

## What else you should know

- **Rate limits.** Sending is limited per workspace. Over a limit the API answers 429 with `Retry-After` and `ratelimit-*` headers that tell you the limit and when it resets. Contact us if you outgrow the defaults.
- **Suppression.** Hard bounces auto-populate your workspace's suppression list. Sends to a suppressed address return 422 before they hit the queue.
- **Invite teammates.** Workspace → Members → **Invite** mints an invite link with a role attached (email optional — supply one and we mail the link for you). _admin_ can do everything except destructive ops like deleting the workspace; _member_ is read-only by default.
- **Render preview.** Test a template before sending: `POST /v1/workspaces/:workspaceId/templates/:name/render` with your data payload returns the rendered subject, HTML, and text — no mail goes out. `.../test-send` delivers a real `[TEST]`-prefixed email, bypassing suppression and rate limits.
- **Inbound mail.** Every verified domain is also listening on `mx.productcraft.co`. Create a mailbox under it and inbound messages land with parsed MIME + attachments, readable via the mailbox endpoints.

Something not covered? Email [hello@productcraft.co](mailto:hello@productcraft.co) — most docs gaps turn into features in the next release.
