Email

List all inbound domains for the organization, both verified and unverified. Each domain includes its verification status and DNS records. Use before addDomain to check whether a domain is already claimed.

Claim a new domain and receive the DNS records to publish. Returns dns_records with the exact records to add. If the domain has an mx_conflict (existing mail provider), re-call with confirmed: true to proceed. After publishing DNS records, call verifyDomain to complete setup.

• requestBodyobjectrequired

Check DNS records for a domain claim (MX, TXT, SPF, DKIM, DMARC). On success the domain becomes verified and starts receiving mail. On failure, returns which checks passed and which still need attention. If DNS propagation is incomplete, wait a few minutes and retry.

• idstringrequiredDomain ID returned by addDomain or listDomains.

Download a BIND-format DNS zone file for a domain. Useful when users want to import all required DNS records at once rather than copying them individually. Returns plain text in BIND zone file format.

• idstringrequiredDomain ID from listDomains or addDomain.
• outbound_onlybooleanWhen true, include only outbound DNS records (SPF, DKIM, DMARC). Defaults to all records for unverified domains, outbound-only for verified.

Use this when you need the authenticated Primitive account summary, including email, plan, onboarding state, and webhook secret rotation time.

Use this when the user asks whether inbound email is ready or needs setup. Returns domains, routes, deployed Functions, and recent inbound activity.

What can I send FROM? Lists this account's verified outbound (sendable) domains plus any domains still pending DNS verification, with next actions. Call this BEFORE sendEmail to pick a valid `from` domain — the account email is not necessarily sendable. The same sendable list is echoed in a cannot_send_from_domain error.

Use this when you need to browse inbound emails received at verified domains with cursor pagination, status filters, date filters, or sender/recipient search.

• cursorstringPagination cursor from a previous response's `meta.cursor` field.
• limitnumberMaximum number of emails to return (1–100, default 50).
• domain_idstringFilter to emails received on a specific verified domain.
• statusstringFilter to emails in this processing status.
• searchstringFree-text search across sender, recipient, and subject.
• date_fromstringInclusive lower bound on received_at (ISO 8601).
• date_tostringInclusive upper bound on received_at (ISO 8601).

Use this when you need to find inbound emails with structured filters or full-text matching. Use sort=received_at_asc plus date_from for new-mail polling.

• qstringFull-text query matched across subject, body, sender, and recipient.
• fromstringFilter to emails from this sender address or domain.
• tostringFilter to emails addressed to this recipient.
• subjectstringFilter to emails whose subject contains this string.
• bodystringFilter to emails whose body contains this string.
• domain_idstringFilter to emails received on a specific verified domain.
• reply_to_sent_email_idstringFilter to inbound emails that are replies to a specific sent email ID.
• statusstringFilter to emails in this processing status.
• date_fromstringInclusive lower bound on received_at (ISO 8601).
• date_tostringInclusive upper bound on received_at (ISO 8601).
• has_attachmentstringFilter to emails that have ("true") or lack ("false") attachments.
• spam_score_ltnumberFilter to emails with a spam score strictly below this value.
• spam_score_gtenumberFilter to emails with a spam score at or above this value.
• sortstringSort order. Use received_at_asc with date_from for polling new mail.
• cursorstringPagination cursor from a previous response's `meta.cursor` field.
• limitnumberMaximum number of emails to return (1–100, default 50).
• snippetstringInclude a short body snippet in each result (default true).
• include_facetsstringInclude aggregated facet counts (sender, domain, status) in the response (default true).

Use this when you need full details for one inbound email ID, including parsed bodies, threading metadata, SMTP envelope, webhook state, and replies.

• idstringrequiredInbound email ID from listEmails or searchEmails.

Use this when the user has selected a specific inbound email and confirmed a reply. Sends real outbound email with threading handled server-side.

• idstringrequiredInbound email ID to reply to. Threading headers are set server-side.
• requestBodyobjectrequired

Use this when the user has confirmed a new outbound email. Sends real email through Primitive's relay and can wait for the first SMTP delivery outcome.

• Idempotency-KeystringClient-supplied idempotency key. Retrying with the same key returns the original result without re-sending.
• requestBodyobjectrequired

Send a SIMULATED email with no account required. Validates the body against the exact same schema as sendEmail, then returns a realistic synthetic success envelope (demo: true) — it never actually sends, queues, or stores anything. Use this to let someone try Primitive and see the response shape before they sign up. To send for real, sign up for an API key and use sendEmail.

• requestBodyobjectrequired

List outbound emails sent by this org, with cursor pagination and filters. Bodies are omitted from list rows to keep responses small — use getSentEmail to fetch a specific row with full body. Useful for auditing delivery status, finding bounced sends, or checking gate-denied attempts.

• cursorstringPagination cursor from a previous response's `meta.cursor` field.
• limitnumberMaximum number of sent emails to return (1–100, default 50).
• statusstringFilter to rows in this status.
• request_idstringFilter to the row matching a specific server-issued request_id from a /send-mail response.
• idempotency_keystringFilter to rows with the given client idempotency key.
• date_fromstringInclusive lower bound on created_at (ISO 8601).
• date_tostringInclusive upper bound on created_at (ISO 8601).

Get the full record for a single sent email by id, including body_text and body_html. Use to inspect delivery details for a specific send — e.g. the SMTP response on a bounced row, or the gate denial reason on a gate_denied row.

• idstringrequiredSent email ID from listSentEmails or a /send-mail response.

Get the threaded reply to a sent email — the canonical 'did they reply yet?' call. Pass the sent email's id (from a sendEmail response). With wait=true it long-polls up to wait_timeout_ms for the reply to arrive (synchronous agent-to-agent chat); with wait=false (default) it returns immediately with the reply if one has arrived, else reply=null. Matches on the reply's threading, not a from/subject guess.

• idstringrequiredThe sent email id to fetch the reply for (from a sendEmail/replyToEmail response).
• waitstringWhen "true", long-poll until a reply arrives or wait_timeout_ms elapses. Default no-wait.
• wait_timeout_msnumberHow long to wait when wait=true (1000–30000 ms, default 10000).

Get the full conversation an inbound email belongs to as ordered, chat-model-ready turns with bodies. Each message is oldest-first with a direction (inbound/outbound) and a derived role (inbound→user, outbound→assistant). For a brand-new message, returns just that one turn. The response includes a truncated boolean (true when the message cap was reached) and a message_count field.

• idstringrequiredID of any inbound email in the conversation.

Get a conversation thread by id: metadata plus all inbound and outbound messages interleaved oldest-first. Each message has a direction (inbound/outbound) and id; fetch inbound message bodies via getEmail, or outbound bodies via getSentEmail. Discover thread_id from any email or sent-email record. Compare message_count against messages.length to detect truncation.

• idstringrequiredThread ID from the thread_id field on any email or sent-email.

Download all attachments for an inbound email as a gzip-compressed tar archive. Returns the archive as a base64-encoded string along with the attachment count and SHA-256 digest. Prefer getEmail first to check the attachment manifest before downloading.

• idstringrequiredInbound email ID.
• tokenstringSigned download token from a webhook payload. Optional — the bearer token is used when this is omitted.

List all active webhook endpoints for the organization. Each endpoint shows its URL, enabled state, and optional domain restriction.

Create a webhook endpoint to receive email.received events. If an endpoint with the same URL already exists but is deactivated, it is reactivated. After creating, call testEndpoint to confirm your signature verifier accepts the payload.

• requestBodyobjectrequired

Soft-delete a webhook endpoint. The endpoint will no longer receive deliveries.

• idstringrequiredEndpoint ID from listEndpoints or createEndpoint.

Send a sample email.received event to a webhook endpoint to verify your signature verifier. Rate limited to 4/min and 30/hr. Successful deliveries and verified-domain endpoints are exempt.

• idstringrequiredEndpoint ID from listEndpoints or createEndpoint.

List all whitelist and blocklist filter rules for the organization.

Create a whitelist or blocklist filter rule. Patterns are stored lowercase. Per-domain filters require a Pro plan.

• requestBodyobjectrequired

Delete a filter rule.

• idstringrequiredFilter rule ID from listFilters or createFilter.

List webhook delivery attempts with pagination and filters. Each delivery includes the target endpoint and a nested email object with sender/recipient/subject. Useful for diagnosing delivery failures or confirming a specific email was delivered.

• cursorstringPagination cursor from a previous response's `meta.cursor` field.
• limitnumberMaximum number of delivery records to return (1–100, default 50).
• email_idstringFilter by inbound email ID.
• statusstringFilter to deliveries in this status.
• date_fromstringInclusive lower bound on attempted_at (ISO 8601).
• date_tostringInclusive upper bound on attempted_at (ISO 8601).

Re-send a stored webhook payload from a previous delivery attempt to its original endpoint. Rate limited per org (burst + sustained windows, shared budget with email webhook replays).

• idstringrequiredDelivery ID (numeric string from listWebhookDeliveries).