Mail API.
Send transactional email on your own domain. Every endpoint, request, and response — generated from the live OpenAPI spec.
Base URL
https://api.mail.productcraft.coAuth
Authorization: Bearer …Spec version
OpenAPI spec
https://api.mail.productcraft.co/docs-jsonBrand
The workspace brand used by branded emails, the unsubscribe page and hosted pages.
Broadcasts
Marketing sends to a segment or topic: drafts, scheduling, sending, recipients and click statistics.
- get
/v1/workspaces/{workspace_id}/broadcastsList broadcasts, newest first - post
/v1/workspaces/{workspace_id}/broadcastsCreate a broadcast (draft) - get
/v1/workspaces/{workspace_id}/broadcasts/audienceCount a broadcast audience - get
/v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}Get a broadcast - patch
/v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}Update a draft broadcast - delete
/v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}Delete a broadcast - post
/v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/sendSend or schedule a broadcast - post
/v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/cancelCancel a scheduled or sending broadcast - post
/v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/duplicateDuplicate a broadcast - get
/v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/recipientsList a broadcast's recipients - get
/v1/workspaces/{workspace_id}/broadcasts/{broadcast_id}/clicked-linksLinks clicked in a broadcast - get
/v1/workspaces/{workspace_id}/broadcast-settingsGet the broadcast settings - put
/v1/workspaces/{workspace_id}/broadcast-settingsUpdate the broadcast settings
Contacts
Contacts, their custom properties, imports from CSV, and their topic subscriptions.
- get
/v1/workspaces/{workspace_id}/contacts/importsList contact imports, newest first - post
/v1/workspaces/{workspace_id}/contacts/importsImport contacts from a CSV file - get
/v1/workspaces/{workspace_id}/contacts/imports/{import_id}Get a contact import and its progress - get
/v1/workspaces/{workspace_id}/contactsList contacts, newest first - post
/v1/workspaces/{workspace_id}/contactsCreate a contact - get
/v1/workspaces/{workspace_id}/contacts/{contact}Get a contact by id or email - patch
/v1/workspaces/{workspace_id}/contacts/{contact}Update a contact - delete
/v1/workspaces/{workspace_id}/contacts/{contact}Delete a contact - get
/v1/workspaces/{workspace_id}/contacts/{contact}/topicsList a contact's topic subscriptions - patch
/v1/workspaces/{workspace_id}/contacts/{contact}/topicsOpt a contact in to or out of topics - get
/v1/workspaces/{workspace_id}/contact-propertiesList contact properties, newest first - post
/v1/workspaces/{workspace_id}/contact-propertiesDefine a contact property - get
/v1/workspaces/{workspace_id}/contact-properties/{property_id}Get a contact property - patch
/v1/workspaces/{workspace_id}/contact-properties/{property_id}Change a contact property's fallback value - delete
/v1/workspaces/{workspace_id}/contact-properties/{property_id}Delete a contact property
Deliverability
A deliverability verdict per sending domain, from recent bounces, complaints and DNS state.
Domains
Sending and receiving domains: DNS records and their checks, one-click DNS setup (Domain Connect and provider APIs), share links, lookups and the domain event timeline.
- get
/v1/workspaces/{workspace_id}/domainsList domains registered to this workspace (newest first), cursor-paginated. - post
/v1/workspaces/{workspace_id}/domainsRegister a domain for a workspace - get
/v1/workspaces/{workspace_id}/domains/lookupLook up a domain before adding it: zone, DNS provider, Domain Connect support, a better subdomain, existing records. - get
/v1/workspaces/{workspace_id}/domains/{domain_id}Get a single domain (with DNS instructions and its latest events). - patch
/v1/workspaces/{workspace_id}/domains/{domain_id}Update domain settings: capabilities, DNS provider hint, custom MAIL FROM subdomain, DMARC recommendation. - delete
/v1/workspaces/{workspace_id}/domains/{domain_id}Delete a domain (must have no active mailboxes left). - get
/v1/workspaces/{workspace_id}/domains/{domain_id}/eventsList a domain's events (its timeline), newest first, cursor-paginated. - post
/v1/workspaces/{workspace_id}/domains/{domain_id}/verifyRun a synchronous DNS check against this domain; flips status to active when the required record set passes. - get
/v1/workspaces/{workspace_id}/domains/{domain_id}/dns-recordsPer-record DNS status for a domain. - get
/v1/workspaces/{workspace_id}/domains/{domain_id}/dns-records/exportDownload the domain's DNS records as a BIND zone fragment or a CSV. - post
/v1/workspaces/{workspace_id}/domains/{domain_id}/dns-records/checkCheck the domain's DNS records now. - post
/v1/workspaces/{workspace_id}/domains/{domain_id}/dns-records/applySet up the domain's DNS records in one step with a short-lived Cloudflare or DigitalOcean API token. - post
/v1/workspaces/{workspace_id}/domains/{domain_id}/domain-connect/startStart one-click DNS setup at the domain's DNS provider (Domain Connect). - post
/v1/workspaces/{workspace_id}/domains/{domain_id}/test-sendSend a built-in test email from this domain, no template needed.
Emails
Send email: one email to up to 50 recipients (`POST /emails`), a batch of up to 100, and the sent emails with their per-recipient status.
- get
/v1/workspaces/{workspace_id}/emailsList emails - post
/v1/workspaces/{workspace_id}/emailsSend an email - post
/v1/workspaces/{workspace_id}/emails/batchSend up to 100 emails in one request - get
/v1/workspaces/{workspace_id}/emails/{id}Retrieve an email - patch
/v1/workspaces/{workspace_id}/emails/{id}Reschedule a scheduled email - post
/v1/workspaces/{workspace_id}/emails/{id}/cancelCancel a scheduled email - get
/v1/workspaces/{workspace_id}/emails/{id}/attachments/{position}Download an attachment of a sent email
Integrations
Connected services, today GitHub, which syncs templates from a repository.
- get
/v1/workspaces/{workspace_id}/integrationsList connected workspace integrations. - get
/v1/workspaces/{workspace_id}/integrations/{provider}Get a single integration detail with redacted credentials. - delete
/v1/workspaces/{workspace_id}/integrations/{provider}Disconnect an integration. - get
/v1/workspaces/{workspace_id}/integrations/github/reposList repos visible to the connected GitHub account. - get
/v1/workspaces/{workspace_id}/integrations/github/repos/{owner}/{repo}/branchesList branches for the given repo. - put
/v1/workspaces/{workspace_id}/integrations/github/settingsSet the repo + branch + templates path to sync from. - post
/v1/workspaces/{workspace_id}/integrations/github/syncTrigger an immediate sync from GitHub. - get
/v1/workspaces/{workspace_id}/integrations/github/sync/latestThe most recent sync that changed or rejected something (kept 30 days), with the per-file errors and skips. - get
/v1/workspaces/{workspace_id}/integrations/github/sync/{sync_id}Poll a sync run's status. - post
/v1/workspaces/{workspace_id}/integrations/github/connectMint a GitHub OAuth state token and return the authorize URL.
Limits
How many emails the workspace may send per minute, hour and day, and what is left now.
Mailboxes
Mailboxes on a receiving domain and the messages delivered to them.
- get
/v1/workspaces/{workspace_id}/mailboxesList mailboxes in this workspace. - post
/v1/workspaces/{workspace_id}/mailboxesCreate a mailbox under a verified domain. - get
/v1/workspaces/{workspace_id}/mailboxes/{id}Get one mailbox by id. - patch
/v1/workspaces/{workspace_id}/mailboxes/{id}Update mailbox display name, retention, or status. - delete
/v1/workspaces/{workspace_id}/mailboxes/{id}Soft-delete a mailbox: its status becomes `disabled` and it stops accepting new mail; existing messages are kept until…
Messages
Messages delivered to a mailbox (raw MIME, attachments, read state), and the daily timeline of received mail.
- get
/v1/workspaces/{workspace_id}/messages/timelineDay-bucketed inbound message volume for a workspace - get
/v1/workspaces/{workspace_id}/mailboxes/{id}/messagesList messages in a mailbox - get
/v1/workspaces/{workspace_id}/mailboxes/{id}/messages/{mid}Get a single message (metadata + attachment manifest; `body_preview` is null without `mail.message.body.read`). - delete
/v1/workspaces/{workspace_id}/mailboxes/{id}/messages/{mid}Soft-delete a message - get
/v1/workspaces/{workspace_id}/mailboxes/{id}/messages/{mid}/rawStream the raw RFC5322 .eml for a message. - get
/v1/workspaces/{workspace_id}/mailboxes/{id}/messages/{mid}/attachments/{position}Stream a single attachment by its position. - post
/v1/workspaces/{workspace_id}/mailboxes/{id}/messages/{mid}/readMark a message as read
Metrics
Delivery metrics over time (sent, delivered, bounced, complained) for the workspace.
Outbound-Messages
The per-recipient delivery log of everything the workspace sent (`messages` in the SDKs): status, events, stored bodies, CSV export, retention settings and the GDPR erase by recipient.
- get
/v1/workspaces/{workspace_id}/messagesList outbound messages with cursor pagination - delete
/v1/workspaces/{workspace_id}/messagesRTBF: delete every message log row for `recipient` (case-insensitive). - get
/v1/workspaces/{workspace_id}/messages/exportStream the filtered message log as CSV. - get
/v1/workspaces/{workspace_id}/messages/settingsRead this workspace's outbound-message settings. - patch
/v1/workspaces/{workspace_id}/messages/settingsUpdate this workspace's outbound-message settings. - get
/v1/workspaces/{workspace_id}/messages/{id}Get a single outbound message (metadata + delivery verdicts; body not included) with its event timeline: `events[]`… - get
/v1/workspaces/{workspace_id}/messages/{id}/bodyGet the cleartext body of an outbound message.
Outbound-Webhooks
Webhook endpoints that receive `email.*`, `domain.*`, `suppression.*`, `contact.*` and `sending_defaults.updated` events, their delivery log and replays. The per-slot legacy routes are deprecated.
- get
/v1/workspaces/{workspace_id}/webhooksList the workspace default + every per-domain override. - get
/v1/workspaces/{workspace_id}/webhooks/defaultGet the workspace-default webhook config (returns null if unset). - put
/v1/workspaces/{workspace_id}/webhooks/defaultCreate or replace the workspace-default outbound webhook. - delete
/v1/workspaces/{workspace_id}/webhooks/defaultDelete the workspace-default webhook config. - post
/v1/workspaces/{workspace_id}/webhooks/default/rotate-secretRotate the workspace-default webhook signing secret. - get
/v1/workspaces/{workspace_id}/webhooks/domains/{domain_id}Get the per-domain webhook override (returns null if unset). - put
/v1/workspaces/{workspace_id}/webhooks/domains/{domain_id}Create or replace the per-domain webhook override. - delete
/v1/workspaces/{workspace_id}/webhooks/domains/{domain_id}Delete the per-domain webhook override. - post
/v1/workspaces/{workspace_id}/webhooks/domains/{domain_id}/rotate-secretRotate the per-domain webhook signing secret. - get
/v1/workspaces/{workspace_id}/webhooks/attemptsDelivery attempts across all of this workspace's webhook endpoints, newest first, cursor-paginated, optionally for one… - get
/v1/workspaces/{workspace_id}/webhooks/event-typesList the events an endpoint can subscribe to. - get
/v1/workspaces/{workspace_id}/webhooks/endpointsList webhook endpoints, oldest first. - post
/v1/workspaces/{workspace_id}/webhooks/endpointsAdd a webhook endpoint. - get
/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}Get one webhook endpoint (without its secret). - patch
/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}Change a webhook endpoint: URL, description, events, on/off. - delete
/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}Delete a webhook endpoint. - post
/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}/rotate-secretRotate the signing secret. - post
/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}/testSend a test event to this endpoint now and return the result. - get
/v1/workspaces/{workspace_id}/webhooks/eventsList webhook events, newest first (kept for 30 days). - get
/v1/workspaces/{workspace_id}/webhooks/events/{event_id}Get one webhook event with every delivery attempt. - post
/v1/workspaces/{workspace_id}/webhooks/events/{event_id}/replaySend a logged event again, to its endpoints or to one endpoint.
Public
Public pages linked from emails (unsubscribe and preferences) and shared domain setup. No API key: the token in the link is the credential.
- get
/v1/public/domain-setup/{token}Public, read-only DNS setup for a shared domain (no authentication). - get
/v1/public/domain-setup/{token}/exportDownload a shared domain's DNS records as a BIND zone fragment or a CSV (no authentication). - get
/v1/u/{token}Hosted unsubscribe and preferences page (no authentication). - post
/v1/u/{token}One-click unsubscribe (RFC 8058) and the preferences form (no authentication).
Received
Every email received by the workspace's domains, with raw MIME and attachments.
- get
/v1/workspaces/{workspace_id}/receivedList received email across every mailbox in the workspace - get
/v1/workspaces/{workspace_id}/received/exportStream the filtered received email as CSV. - get
/v1/workspaces/{workspace_id}/received/{id}Get one received email - delete
/v1/workspaces/{workspace_id}/received/{id}Delete a received email - get
/v1/workspaces/{workspace_id}/received/{id}/rawDownload the raw RFC 5322 message (.eml) - get
/v1/workspaces/{workspace_id}/received/{id}/attachments/{position}Download one attachment of a received email - post
/v1/workspaces/{workspace_id}/received/{id}/readMark a received email as read
Segments
Static and rule-based segments of contacts, used as broadcast audiences.
- get
/v1/workspaces/{workspace_id}/contacts/{contact}/segmentsList a contact's segments - post
/v1/workspaces/{workspace_id}/contacts/{contact}/segments/{segment_id}Add a contact to a static segment - delete
/v1/workspaces/{workspace_id}/contacts/{contact}/segments/{segment_id}Remove a contact from a static segment - get
/v1/workspaces/{workspace_id}/segmentsList segments, newest first - post
/v1/workspaces/{workspace_id}/segmentsCreate a segment - post
/v1/workspaces/{workspace_id}/segments/previewPreview a segment rule - get
/v1/workspaces/{workspace_id}/segments/{segment_id}Get a segment - patch
/v1/workspaces/{workspace_id}/segments/{segment_id}Update a segment - delete
/v1/workspaces/{workspace_id}/segments/{segment_id}Delete a segment - get
/v1/workspaces/{workspace_id}/segments/{segment_id}/contactsList a segment's contacts - get
/v1/workspaces/{workspace_id}/segments/{segment_id}/metricsA segment's size and unsubscribed share
Sending-Defaults
The workspace default sender, used when a template send gives no `from`.
Smtp-Config
Send through your own SMTP server instead of ProductCraft's: the workspace configuration, per-domain overrides and connection checks.
- get
/v1/workspaces/{workspace_id}/smtp-configGet the workspace-default SMTP config (returns null if unset). - put
/v1/workspaces/{workspace_id}/smtp-configCreate or update the workspace-default SMTP config (resets verification) - delete
/v1/workspaces/{workspace_id}/smtp-configRevert the workspace to ProductCraft Mail's own sending - post
/v1/workspaces/{workspace_id}/smtp-config/verifyTest arbitrary SMTP creds without persisting - post
/v1/workspaces/{workspace_id}/smtp-config/verify-savedTest the persisted workspace-default SMTP config; updates status - get
/v1/workspaces/{workspace_id}/smtp-configsList every SMTP config in the workspace (default + per-domain overrides) - get
/v1/workspaces/{workspace_id}/domains/{domain_id}/smtp-configGet the per-domain SMTP override (returns null if unset; the workspace default applies in that case). - put
/v1/workspaces/{workspace_id}/domains/{domain_id}/smtp-configCreate or update the per-domain SMTP override (resets verification) - delete
/v1/workspaces/{workspace_id}/domains/{domain_id}/smtp-configDrop the per-domain override; sends from this domain fall back to the workspace default (or ProductCraft Mail's own… - post
/v1/workspaces/{workspace_id}/domains/{domain_id}/smtp-config/verify-savedTest the per-domain SMTP override; updates status
Stats
Send totals and a daily series for the workspace dashboard.
Suppression
Addresses that are never sent to: added by bounces, complaints or by hand.
- get
/v1/workspaces/{workspace_id}/suppressionList suppressed recipients in the workspace (most-recent first), cursor-paginated. - post
/v1/workspaces/{workspace_id}/suppressionAdd an email to the workspace suppression list - delete
/v1/workspaces/{workspace_id}/suppression/{email}Remove an address from the workspace suppression list.
Templates
Handlebars templates (with layouts and partials): create, render, lint, test-send, and send to one recipient or a batch.
- get
/v1/workspaces/{workspace_id}/templatesList templates / layouts / partials in a workspace, name-ascending and cursor-paginated. - post
/v1/workspaces/{workspace_id}/templatesCreate or update a template, layout, or partial. - get
/v1/workspaces/{workspace_id}/templates/{name}Get a template, layout, or partial by name. - delete
/v1/workspaces/{workspace_id}/templates/{name}Delete a template, layout, or partial by name. - post
/v1/workspaces/{workspace_id}/templates/{name}/detachTake a GitHub-synced template over in Mail: it becomes editable here and the GitHub sync stops changing it (each sync… - post
/v1/workspaces/{workspace_id}/templates/{name}/attachHand a detached template back to the GitHub sync. - post
/v1/workspaces/{workspace_id}/templates/{name}/renderRender a saved template against a data payload. - post
/v1/workspaces/{workspace_id}/templates/previewPreview an unsaved draft. - post
/v1/workspaces/{workspace_id}/templates/lintLint a draft for deliverability red flags. - get
/v1/workspaces/{workspace_id}/templates/{name}/variablesVariables auto-detected from the saved template body + subject (Handlebars expressions, dotted paths preserved,… - post
/v1/workspaces/{workspace_id}/templates/{name}/test-sendSend a test rendering of the template to an arbitrary recipient. - post
/v1/workspaces/{workspace_id}/templates/{name}/sendSend a template-rendered message. - post
/v1/workspaces/{workspace_id}/templates/{name}/send-batchSend up to 100 messages with the same template in one request.
Topics
Subscription topics: what a contact can opt in to or out of on the unsubscribe page.
- get
/v1/workspaces/{workspace_id}/topicsList topics, newest first - post
/v1/workspaces/{workspace_id}/topicsCreate a topic - get
/v1/workspaces/{workspace_id}/topics/{topic_id}Get a topic - patch
/v1/workspaces/{workspace_id}/topics/{topic_id}Update a topic - delete
/v1/workspaces/{workspace_id}/topics/{topic_id}Delete a topic