Skip to content
My Beast
Cart
Developer docsMenu

Mail · Getting started

Quickstart

From an API key to a delivered email in six steps. You need an Email API plan and, from step 3, access to your domain's DNS settings.

1. Create an API key

API keys are created in your account: open your Email API plan and create a key. Copy it straight away, because it's only shown once.

Keep the key on your server, for example in an environment variable:

Terminal
export MYBEAST_API_KEY="mb_live_..."

Keep your key secret

Anyone with the key can send email as you. Never put it in code that runs in a browser or a mobile app. More about keeping keys safe.

2. Try it in a test inbox

You can send your first email before touching DNS. Make a test inbox in the Email API dashboard and copy its key, which starts with mb_test_. It takes the same request as a live key and keeps the email instead of sending it: any from, any to, nothing leaves, and the inbox shows the email as a phone or a desktop client would.

Terminal
export MYBEAST_API_KEY="mb_test_..."

Then run the request of step 5. When your code is right, put the live key back and carry on below. Test keys has the details, including the recipients that simulate a bounce or a complaint.

3. Add your domain

You can only send from a domain you've verified, so that mailbox providers can tell the email really comes from you. Add the domain you want to send from:

curl -X POST https://services.my-beast.com/mail/api/email/v1/domains \
  -H "Authorization: Bearer $MYBEAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme.com"
  }'
Response
{
  "id": "dom_01JA2N5Q7RB3XK",
  "name": "acme.com",
  "status": "pending",
  "records": [
    {
      "purpose": "spf",
      "type": "MX",
      "name": "mb-bounces.acme.com",
      "value": "bounces.my-beast.com",
      "priority": 10,
      "required": true,
      "status": "missing"
    },
    {
      "purpose": "spf",
      "type": "TXT",
      "name": "mb-bounces.acme.com",
      "value": "v=spf1 include:_spf.my-beast.com ~all",
      "priority": null,
      "required": true,
      "status": "missing"
    },
    {
      "purpose": "dkim",
      "type": "TXT",
      "name": "mb1._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1x…IDAQAB",
      "priority": null,
      "required": true,
      "status": "missing"
    },
    {
      "purpose": "dmarc",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "priority": null,
      "required": false,
      "status": "missing"
    }
  ],
  "created_at": "2026-10-09T08:52:41Z",
  "checked_at": null
}

The response lists the DNS records to create. Add each one at the company that runs DNS for your domain, which is often where you registered it. Copy the names and values from your response: the ones above are examples. Sending domains explains what each record does.

4. Verify your domain

We check new domains every 15 minutes for 72 hours. To check right away once you've created the records:

curl -X POST https://services.my-beast.com/mail/api/email/v1/domains/dom_01JA2N5Q7RB3XK/verify \
  -H "Authorization: Bearer $MYBEAST_API_KEY"

When the domain's status is verified, you can send. If it's still pending, each record's status shows which one we couldn't find yet. DNS changes can take a while to spread, so give it a few minutes and try again.

5. Send an email

Use any address at your verified domain as from. For a first test, send to an address you can read:

curl -X POST https://services.my-beast.com/mail/api/email/v1/emails \
  -H "Authorization: Bearer $MYBEAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": ["customer@example.com"],
    "subject": "Your order has shipped",
    "html": "<p>Your order is on its way.</p>"
  }'
Response
{
  "id": "em_01JA2Q8ZK4T9W6",
  "status": "queued"
}

The id identifies the email from now on. Its status starts as queued.

6. Check what happened

Look the email up by its ID to see its status and what happened to each recipient:

curl https://services.my-beast.com/mail/api/email/v1/emails/em_01JA2Q8ZK4T9W6 \
  -H "Authorization: Bearer $MYBEAST_API_KEY"

The status moves from queued to sent to delivered, or to bounced, complained or failed if something went wrong. Email statuses explains each one.

Instead of asking, you can have us tell your app. Create a webhook:

curl -X POST https://services.my-beast.com/mail/api/email/v1/webhooks \
  -H "Authorization: Bearer $MYBEAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://acme.com/webhooks/my-beast",
    "events": [
      "email.delivered",
      "email.bounced",
      "email.complained",
      "email.failed"
    ]
  }'
Response
{
  "id": "wh_01JA2T4H8MC6YP",
  "url": "https://acme.com/webhooks/my-beast",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained",
    "email.failed"
  ],
  "created_at": "2026-10-09T09:20:15Z",
  "secret": "whsec_5Kq8vR2xN7mT4bW9cJ3hL6pD1fG0sY"
}

Store the secret now, because it isn't shown again: you need it to check that events come from us.

Next steps