SuperSend TXDocs

Inbound email API

Receive mail on a verified SuperSend TX domain, get email.received webhooks, and retrieve full inbound messages with attachments.

Base URL: https://api.supersendtx.com

Auth:

Authorization: Bearer stx_...

Overview

Inbound receiving is configured on the existing domain resource:

  1. Create a domain with inbound_enabled: true or enable it later with PATCH /domains/{id}.
  2. Verify the domain (POST /domains/{id} with { "action": "verify" }).
  3. Publish the returned MX record so SuperSend TX can receive mail for that hostname.
  4. Subscribe to email.received webhooks or poll /received-emails.

SuperSend TX stores:

  • the inbound message headers/bodies
  • attachment metadata on list responses
  • full attachment base64 data on retrieve responses

Important MX conflict note

Inbound receiving requires changing the domain hostname's MX record to SuperSend TX.

That means:

  • if example.com already receives mail at Google Workspace, Microsoft 365, Fastmail, etc, moving the MX record will stop that provider from receiving new mail for example.com
  • the safest pattern is usually a dedicated subdomain such as inbound.example.com

Every domain detail/create response includes:

  • inbound_records — the MX record to publish
  • inbound_note — the same warning in machine-readable responses

Create a receiving domain

POST /domains

curl -X POST https://api.supersendtx.com/domains \
  -H "Authorization: Bearer $SUPERSENDTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "inbound.example.com",
    "inbound_enabled": true
  }'

Response:

{
  "domain": {
    "id": "d_123",
    "name": "inbound.example.com",
    "status": "pending",
    "created_at": "2026-07-26T00:00:00.000Z",
    "verified_at": null,
    "open_tracking": false,
    "click_tracking": false,
    "tls_mode": "opportunistic",
    "inbound_enabled": true,
    "inbound_status": "pending",
    "inbound_error": null
  },
  "records": [
    {
      "type": "TXT",
      "host": "_supersendtx.inbound.example.com",
      "value": "supersendtx-verify=...",
      "purpose": "Domain ownership"
    }
  ],
  "inbound_records": [
    {
      "type": "MX",
      "host": "inbound.example.com",
      "value": "10 mx.core.superesp.com",
      "purpose": "Inbound receiving"
    }
  ],
  "inbound_note": "Inbound receiving requires pointing this hostname's MX record to SuperSend TX. That conflicts with any existing mailbox provider on the same hostname, so use a dedicated subdomain such as inbound.example.com when Google Workspace or Microsoft 365 should keep handling your main mailboxes."
}

inbound_status: "pending" means inbound receiving finishes setup after verification succeeds.

Enable inbound on an existing domain

PATCH /domains/{id}

curl -X PATCH https://api.supersendtx.com/domains/inbound.example.com \
  -H "Authorization: Bearer $SUPERSENDTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "inbound_enabled": true }'

If the domain is already verified, SuperSend TX immediately activates inbound receiving for that hostname.

Relevant fields:

  • domain.inbound_status = "active" — inbound receiving is configured
  • domain.inbound_status = "pending" — waiting for verification
  • domain.inbound_status = "error" + domain.inbound_error — inbound setup failed and should be retried

Verify the domain

POST /domains/{id}

{ "action": "verify" }

If inbound_enabled is already true, verification also activates inbound receiving and returns:

  • inbound_configured
  • inbound_pending
  • inbound_error

List received emails

GET /received-emails

Optional query params:

  • limit
  • cursor
  • domain — receiving domain name
curl https://api.supersendtx.com/received-emails?domain=inbound.example.com \
  -H "Authorization: Bearer $SUPERSENDTX_API_KEY"

Response:

{
  "received_emails": [
    {
      "id": "inb_abc123",
      "domain_id": "d_123",
      "domain_name": "inbound.example.com",
      "status": "received",
      "rcpt_to": "sales@inbound.example.com",
      "mail_from": "sender@example.org",
      "from": "Sender <sender@example.org>",
      "to": ["sales@inbound.example.com"],
      "cc": [],
      "subject": "Question about pricing",
      "spam_status": "NotSpam",
      "bounced": false,
      "received_with_ssl": true,
      "message_id": "<abc@example.org>",
      "in_reply_to": null,
      "references": [],
      "attachment_count": 1,
      "attachments": [
        {
          "filename": "invoice.pdf",
          "content_type": "application/pdf",
          "size": 48291
        }
      ],
      "text_body": null,
      "html_body": null,
      "auto_submitted": null,
      "received_at": "2026-07-26T12:00:00.000Z",
      "created_at": "2026-07-26T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

List responses omit attachment data and null out message bodies to keep payloads smaller.

Retrieve a received email

GET /received-emails/{id}

curl https://api.supersendtx.com/received-emails/inb_abc123 \
  -H "Authorization: Bearer $SUPERSENDTX_API_KEY"

Response:

{
  "received_email": {
    "id": "inb_abc123",
    "domain_id": "d_123",
    "domain_name": "inbound.example.com",
    "status": "received",
    "rcpt_to": "sales@inbound.example.com",
    "mail_from": "sender@example.org",
    "from": "Sender <sender@example.org>",
    "to": ["sales@inbound.example.com"],
    "cc": [],
    "subject": "Question about pricing",
    "spam_status": "NotSpam",
    "bounced": false,
    "received_with_ssl": true,
    "message_id": "<abc@example.org>",
    "in_reply_to": null,
    "references": [],
    "attachment_count": 1,
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content_type": "application/pdf",
        "size": 48291,
        "data": "JVBERi0xLjQKJ..."
      }
    ],
    "text_body": "Hello there!",
    "html_body": "<p>Hello there!</p>",
    "auto_submitted": null,
    "received_at": "2026-07-26T12:00:00.000Z",
    "created_at": "2026-07-26T12:00:00.000Z"
  }
}

Attachments are base64 encoded.

email.received webhook

Subscribe a webhook endpoint to email.received with POST /webhooks.

Webhook deliveries include metadata only, not full attachment data:

{
  "type": "email.received",
  "created_at": "2026-07-26T12:00:01.000Z",
  "data": {
    "email_id": "inb_abc123",
    "to": ["sales@inbound.example.com"],
    "from": "Sender <sender@example.org>",
    "subject": "Question about pricing",
    "status": "received",
    "rcpt_to": "sales@inbound.example.com",
    "cc": [],
    "message_id": "<abc@example.org>",
    "in_reply_to": null,
    "references": [],
    "spam_status": "NotSpam",
    "attachment_count": 1,
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content_type": "application/pdf",
        "size": 48291
      }
    ],
    "received_at": "2026-07-26T12:00:00.000Z"
  }
}

Retrieve the full message from /received-emails/{id} when you need bodies or attachment bytes.

SDK

import { SuperSendTX } from 'supersendtx'

const client = new SuperSendTX(process.env.SUPERSENDTX_API_KEY!)

await client.domains.create({
  name: 'inbound.example.com',
  inbound_enabled: true,
})

await client.domains.verify('inbound.example.com')

const { received_emails } = await client.receivedEmails.list({
  domain: 'inbound.example.com',
})

const one = await client.receivedEmails.get(received_emails[0].id)

CLI

supersendtx domains add inbound.example.com --inbound true
supersendtx domains verify inbound.example.com
supersendtx domains update inbound.example.com --inbound true
supersendtx received-emails list --domain inbound.example.com
supersendtx received-emails get inb_abc123

OpenAPI

Machine-readable spec: openapi/supersendtx.yaml