Cresca LogoCresca

Quickstart

Verify a domain, create an API key and send your first transactional email in a few minutes.

1. Verify a sending domain

In the Cresca app, open Sending Domains, add your domain and publish the DNS records Cresca shows you (DKIM, a custom MAIL FROM domain and an ownership record). If your DNS is on Cloudflare, Cresca can publish them for you. The domain becomes active once the records are verified.

Consider a subdomain for app email, such as mail.acme.com. It keeps the reputation of your password resets separate from your marketing campaigns.

2. Add a sender

On the same page, create a sender address on the verified domain, for example hello@acme.com, with a display name and an optional Reply-To. The from address of every API email must be one of your active senders.

3. Create an API key

Open API keys and create a key. For a production server, choose Sending access: it can send email but cannot read your logs or change templates. The key is shown once, so store it in your server's environment, for example as CRESCA_API_KEY. See Authentication.

4. Send an email

Request
curl -X POST 'https://api.cresca.xyz/api/v1/emails' \
  -H 'Authorization: Bearer cr_live_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: password-reset/user-123' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": "user@example.com",
  "subject": "Reset your password",
  "html": "<p>Click <a href=\"https://acme.com/reset?token=abc\">here</a> to reset your password. The link expires in 1 hour.</p>"
}'
Response 200
{
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c"
}

Cresca queues the email and sends it within seconds. The Idempotency-Key makes the request safe to retry: if your server times out and sends it again, the second request returns the same id instead of a second email. See Idempotency.

5. Check delivery

Open Transactional in the app to see the email's timeline, or call the API with a full-access key:

Request
curl -X GET 'https://api.cresca.xyz/api/v1/emails/4ef9a417-02e9-4d39-ad75-9611e0fcc33c' \
  -H 'Authorization: Bearer cr_live_xxxxxxxxx'

The last_event field moves from queued to sent and then delivered (or bounced). See Email lifecycle.

Next steps