Email quickstart

This page sends one email with Notify. The recipient is a test recipient: its message is rendered and captured on the Message record and never delivered, so you can try the whole path without sending real mail.

Below, $ENV is the environment name that sylphx access whoami returns, for example orgs/acme/projects/shop/envs/production.

#1. Add and verify the domain

sylphx notify mail-domains create \
  --parent "$ENV" \
  --spec.domain mail.example.com

The answer lists status.dns_records: the DKIM, SPF, return-path and DMARC records to publish at your DNS provider. Publish them, then check them now instead of waiting for the next sweep:

sylphx notify mail-domains verify "$ENV/mail_domains/<id>"

A domain sends only after its DKIM and SPF records verify.

#2. Write a template

curl -X POST "https://api.sylphx.com/v1/$ENV/templates?template_id=welcome" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "spec": {
        "email": {
          "sender_address": "hello@mail.example.com",
          "sender_name": "Example",
          "subject": "Welcome",
          "text_body": "Welcome aboard."
        }
      }
    }
  }'

The From address must be on a verified domain.

#3. Create a test recipient

curl -X POST "https://api.sylphx.com/v1/$ENV/recipients?recipient_id=ada" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipient": {"external_key": "user-123", "email_addresses": ["ada@example.com"], "test": true}}'

test: true marks the recipient as a test recipient. So is any address whose local part carries +sylphx_test, such as ada+sylphx_test@example.com.

#4. Send the message

sylphx notify messages send \
--parent "$ENV" \
--recipient "$ENV/recipients/ada" \
--topic onboarding \
--template "$ENV/templates/welcome"

Notify admits the message, checks suppression and the recipient's preferences for the topic, and answers it with a state. For a test recipient the rendered subject and bodies are on the message's capture. For a real recipient, deliveries carries one entry per channel with its state and the provider's receipt.

#5. Read it back

sylphx notify messages get "$ENV/messages/<id>"

Send one to a real address by dropping test and using your own address, and check deliveries[].state reach delivered. A message you no longer want sent can be cancelled with sylphx notify messages cancel until its deliveries are handed off.