Domains API methods (unstable)

Sidemail enables you to manage and verify custom domains for sending emails on behalf of your brand. Before you can send from your own domain, it must be added and verified (including DNS authentication such as DKIM). This API lets you list, add, and remove domains, as well as view their verification and DNS setup status.

Available API endpoints:

• GET https://api.sidemail.io/v1/domains — List all sending domains
• POST https://api.sidemail.io/v1/domains — Create a sending domain
• DELETE https://api.sidemail.io/v1/domains/{id} — Delete a sending domain

Domain Object

A Domain object represents a verified sending domain used for email delivery.

• id (string): Unique identifier of the domain (object ID).
• domain (string, required): The domain name (e.g., "example.com").
• status (string): Verification status. One of pending, success, failed.
• dkim (boolean): Whether DKIM is set up (true/false).
• dkimTokens (array of strings): DKIM selector tokens used for DNS records.
• mailFromDomain (string): The custom MAIL FROM domain used for email delivery.
• mailFromStatus (string): Status of the MAIL FROM domain (e.g., pending, success, failed).
• dns (array of objects): List of DNS records required for setup. Each object has:
  • hostname (string): The DNS record hostname.
  • value (string): The value to set for the DNS record.
• dcUrl (string): Domain Connect setup URL for automated DNS setup.

Example Domain Object

{
  "id": "5d45dd1ca546d200fe201f84",
  "domain": "example.com",
  "status": "pending",
  "dkim": true,
  "dkimTokens": ["xxxxx"],
  "mailFromDomain": "out.mail.example.com",
  "mailFromStatus": "pending",
  "dns": [
    {
      "hostname": "xxxxx._domainkey.out.mail.example.com",
      "value": "xxxxx.dkim.sidemail.net"
    },
    {
      "hostname": "out.mail.example.com",
      "value": "xxxxx.mailfrom.sidemail.net"
    }
  ],
  "dcUrl": "https://dash.cloudflare.com/domainconnect/v2/d..."
}

List all domains

GET https://api.sidemail.io/v1/domains

Returns a list of all sending domains for the authenticated organization.

Response:

{
  "domains": [
    { /* Domain object */ },
    ...
  ]
}

Create a sending domain

POST https://api.sidemail.io/v1/domains

Begins the sending domain set up process. Requires a domain name in the request body.

• To verify a domain, you must add the required DNS records provided in the dns field of the domain object.
• Use the dcUrl for automated DNS setup if your provider is Cloudflare.
• The domain status transitions from pending → success (when verified) or failed (if verification fails).

Request Body:

{
  "domain": "example.com"
}

Response:

{ /* Domain object */ }

Delete a sending domain

DELETE https://api.sidemail.io/v1/domains/:id

Deletes a sending domain. The domain must not be used in any active automations or scheduled emails.

Response:

{
  "deleted": true
}