Email receiving API

NoticeAPI can receive email for verified receiving domains, parse MIME, store the message body and attachments, and emit a signed email.received webhook. This is API-based receiving: no IMAP, POP3, webmail, or end-user inbox product.

Domain flow

Add a receiving domain, publish the TXT and MX records, then verify DNS. Prefer a subdomain such as reply.example.com; setting MX on a root domain captures normal mail for that domain.

POST/api/v1/receiving/domains

create receiving domain

curl -X POST https://www.noticeapi.com/api/v1/receiving/domains \
  -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "reply.example.com" }'

Field	Type	Description
`domain`required	string	Custom receiving domain or subdomain.
`kind`	custom \| managed	Use custom for production DNS; managed creates a hosted test domain.

Endpoint	Purpose
`GET /api/v1/receiving/domains`	List receiving domains.
`POST /api/v1/receiving/domains/:id/verify`	Check required TXT and MX records.
`DELETE /api/v1/receiving/domains/:id`	Remove a receiving domain and stop accepting mail for it.

Webhook event

Inbound delivery is webhook-first. The event is intentionally metadata-only so your handler can respond quickly and fetch bodies or attachment content only when needed. Signatures use the same HMAC header documented in Webhooks.

email.received

{
  "type": "email.received",
  "emailId": "rx_0f83...",
  "messageId": "<[email protected]>",
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Re: Invoice",
  "receivedFor": ["[email protected]"],
  "receivedAt": "2026-07-03T18:04:14.000Z",
  "attachments": [
    { "id": "att_123", "filename": "invoice.pdf", "contentType": "application/pdf", "size": 48213 }
  ],
  "accountId": "..."
}

Retrieve messages

GET/api/v1/receiving/emails

GET/api/v1/receiving/emails/:id

GET/api/v1/receiving/emails/:id/attachments

GET/api/v1/receiving/emails/:id/attachments/:attachmentId

The email detail endpoint returns headers, HTML, text, envelope recipients, and attachment metadata. The final attachment endpoint returns the raw file bytes.

fetch received email

curl https://www.noticeapi.com/api/v1/receiving/emails/rx_0f83... \
  -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx"

Node SDK

receiving.ts

import { NoticeAPI } from "noticeapi";

const notice = new NoticeAPI(process.env.NOTICEAPI_KEY);

const { domains } = await notice.receiving.domains.list();
const email = await notice.receiving.emails.get("rx_0f83...");
const file = await notice.receiving.attachments.get(email.id, email.attachments[0].id);

Limits

V1 stores message content and attachments with tight caps. Oversized messages are rejected at SMTP time. Each accepted inbound message counts as one email against monthly volume. Receiving domains share your plan domain limit.