Skip to content
My Beast
Cart
Developer docsMenu

Mail · API reference

Domains

A sending domain is a domain you send email from. Add it, create the DNS records it lists, then verify it. Your plan sets how many (Plans and limits). The sending domains guide explains each record.

Endpoints

https://services.my-beast.com/mail/api/email/v1

The domain object

A sending domain and the DNS records it needs.

Fields

  • idstring

    Unique ID, starting with dom_.

  • namestring

    The domain, such as acme.com or mail.acme.com.

  • statusstring

    pending, verified or failed. You can only send from verified domains. See Domain statuses.

  • recordsarray of objects

    The DNS records to create at your DNS provider.

    • purposestring

      spf, dkim or dmarc.

    • typestring

      MX or TXT.

    • namestring

      The full record name, such as mb1._domainkey.acme.com. Some DNS providers want only the part before your domain.

    • valuestring

      The record's content. Copy it exactly.

    • priorityinteger or null

      The priority of an MX record. null for TXT records.

    • requiredboolean

      true for the SPF and DKIM records. The DMARC record is recommended, but not needed to verify.

    • statusstring

      verified if the last check found the record with this value, otherwise missing. For DMARC, any valid DMARC record counts, so you can keep the one you have.

  • created_atstring

    When the domain was added (ISO 8601, UTC).

  • checked_atstring or null

    When we last checked its DNS records (ISO 8601, UTC). null before the first check.

Example
{
  "id": "dom_01JA2N5Q7RB3XK",
  "name": "acme.com",
  "status": "verified",
  "records": [
    {
      "purpose": "spf",
      "type": "MX",
      "name": "mb-bounces.acme.com",
      "value": "bounces.my-beast.com",
      "priority": 10,
      "required": true,
      "status": "verified"
    },
    {
      "purpose": "spf",
      "type": "TXT",
      "name": "mb-bounces.acme.com",
      "value": "v=spf1 include:_spf.my-beast.com ~all",
      "priority": null,
      "required": true,
      "status": "verified"
    },
    {
      "purpose": "dkim",
      "type": "TXT",
      "name": "mb1._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1x…IDAQAB",
      "priority": null,
      "required": true,
      "status": "verified"
    },
    {
      "purpose": "dmarc",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "priority": null,
      "required": false,
      "status": "verified"
    }
  ],
  "created_at": "2026-10-09T08:52:41Z",
  "checked_at": "2026-10-09T09:03:17Z"
}

Domain statuses

StatusMeaning
pendingAdded, and waiting for the required DNS records. We check every 15 minutes for 72 hours.
verifiedThe required records are in place. You can send from this domain.
failedWe didn't find the required records within 72 hours, or a daily check found one missing. Fix the records and verify again.

We also check verified domains once a day. Emails from a domain that isn't verified are refused with domain_not_verified.

Add a domain

POST/domains

Adds a sending domain and returns the DNS records to create. It starts as pending; we check its records every 15 minutes for 72 hours, or you can verify it yourself.

Body

  • namestringrequired

    A domain or subdomain you control, such as acme.com or mail.acme.com. Without https:// or a path, up to 253 characters. Each subdomain counts as its own domain.

Response

200 OK. The new domain object.

Errors

  • 403test_keyThe key is a test inbox's (mb_test_…). These endpoints take a live key.
  • 403domain_limit_reachedYour plan's sending domains are all in use.
  • 409domain_existsThis domain is already on your plan.
  • 422validation_errorname is missing or isn't a valid domain.

Any endpoint can also return the common errors.

Request

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

200 OK
{
  "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
}

List domains

GET/domains

Returns your sending domains, newest first.

Query parameters

  • limitintegeroptional

    How many to return, from 1 to 100. Default 20.

  • afterstringoptional

    The ID of the last domain on the previous page. Leave it out for the first page. See Pagination.

Response

200 OK. A page of domain objects.

Errors

  • 403test_keyThe key is a test inbox's (mb_test_…). These endpoints take a live key.
  • 422validation_errorlimit is out of range, or after isn't a domain in this list.

Any endpoint can also return the common errors.

Request

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

Response

200 OK
{
  "data": [
    {
      "id": "dom_01JA2N5Q7RB3XK",
      "name": "acme.com",
      "status": "verified",
      "records": [
        {
          "purpose": "spf",
          "type": "MX",
          "name": "mb-bounces.acme.com",
          "value": "bounces.my-beast.com",
          "priority": 10,
          "required": true,
          "status": "verified"
        },
        {
          "purpose": "spf",
          "type": "TXT",
          "name": "mb-bounces.acme.com",
          "value": "v=spf1 include:_spf.my-beast.com ~all",
          "priority": null,
          "required": true,
          "status": "verified"
        },
        {
          "purpose": "dkim",
          "type": "TXT",
          "name": "mb1._domainkey.acme.com",
          "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1x…IDAQAB",
          "priority": null,
          "required": true,
          "status": "verified"
        },
        {
          "purpose": "dmarc",
          "type": "TXT",
          "name": "_dmarc.acme.com",
          "value": "v=DMARC1; p=none;",
          "priority": null,
          "required": false,
          "status": "verified"
        }
      ],
      "created_at": "2026-10-09T08:52:41Z",
      "checked_at": "2026-10-09T09:03:17Z"
    }
  ],
  "has_more": false
}

Retrieve a domain

GET/domains/{id}

Returns a sending domain with its DNS records and their status.

Path parameters

  • idstringrequired

    The domain's ID.

Response

200 OK. The domain object.

Errors

  • 403test_keyThe key is a test inbox's (mb_test_…). These endpoints take a live key.
  • 404not_foundNo domain on your plan has this ID.

Any endpoint can also return the common errors.

Request

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

Response

200 OK
{
  "id": "dom_01JA2N5Q7RB3XK",
  "name": "acme.com",
  "status": "verified",
  "records": [
    {
      "purpose": "spf",
      "type": "MX",
      "name": "mb-bounces.acme.com",
      "value": "bounces.my-beast.com",
      "priority": 10,
      "required": true,
      "status": "verified"
    },
    {
      "purpose": "spf",
      "type": "TXT",
      "name": "mb-bounces.acme.com",
      "value": "v=spf1 include:_spf.my-beast.com ~all",
      "priority": null,
      "required": true,
      "status": "verified"
    },
    {
      "purpose": "dkim",
      "type": "TXT",
      "name": "mb1._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1x…IDAQAB",
      "priority": null,
      "required": true,
      "status": "verified"
    },
    {
      "purpose": "dmarc",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "priority": null,
      "required": false,
      "status": "verified"
    }
  ],
  "created_at": "2026-10-09T08:52:41Z",
  "checked_at": "2026-10-09T09:03:17Z"
}

Verify a domain

POST/domains/{id}/verify

Checks the domain's DNS records now and returns the result. Use it once you've created the records, instead of waiting for the next automatic check. The request has no body.

  • If every required record is found, the status becomes verified. If not, a pending domain stays pending, and a verified or failed domain becomes failed.

Path parameters

  • idstringrequired

    The domain's ID.

Response

200 OK. The domain object after the check.

Errors

  • 403test_keyThe key is a test inbox's (mb_test_…). These endpoints take a live key.
  • 404not_foundNo domain on your plan has this ID.

Any endpoint can also return the common errors.

Request

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

Response

200 OK
{
  "id": "dom_01JA2N5Q7RB3XK",
  "name": "acme.com",
  "status": "verified",
  "records": [
    {
      "purpose": "spf",
      "type": "MX",
      "name": "mb-bounces.acme.com",
      "value": "bounces.my-beast.com",
      "priority": 10,
      "required": true,
      "status": "verified"
    },
    {
      "purpose": "spf",
      "type": "TXT",
      "name": "mb-bounces.acme.com",
      "value": "v=spf1 include:_spf.my-beast.com ~all",
      "priority": null,
      "required": true,
      "status": "verified"
    },
    {
      "purpose": "dkim",
      "type": "TXT",
      "name": "mb1._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1x…IDAQAB",
      "priority": null,
      "required": true,
      "status": "verified"
    },
    {
      "purpose": "dmarc",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "priority": null,
      "required": false,
      "status": "verified"
    }
  ],
  "created_at": "2026-10-09T08:52:41Z",
  "checked_at": "2026-10-09T09:03:17Z"
}

Delete a domain

DELETE/domains/{id}

Removes a sending domain and frees its place on your plan. You can't send from it any more. Emails from it that are already queued are still sent, and their logs are kept.

Path parameters

  • idstringrequired

    The domain's ID.

Response

200 OK. The domain's ID and deleted: true.

Errors

  • 403test_keyThe key is a test inbox's (mb_test_…). These endpoints take a live key.
  • 404not_foundNo domain on your plan has this ID.

Any endpoint can also return the common errors.

Request

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

Response

200 OK
{
  "id": "dom_01JA2N5Q7RB3XK",
  "deleted": true
}