Suppressions & Consent

Suppressions prevent email from being sent to specific recipients. Consent records track the legal basis for contacting someone. Both are enforced automatically by the policy engine.

Suppression scopes

Suppressions can be applied at three levels:

Scope	Description
`global`	Blocked across all tenants. Checked first.
`tenant`	Blocked for a specific tenant.
`campaign`	Blocked for a specific campaign only.

When evaluating a send request, global suppressions are checked first, then tenant, then campaign.

Add a suppression

CLI

molted suppressions add --email user@example.com --reason manual_dnc --scope tenant

CLI - with expiration

molted suppressions add --email user@example.com --reason no_engagement --scope tenant \
  --expires-at 2027-01-01T00:00:00Z

CLI flags

Flag	Type	Required	Description
`--email`	`string`	Yes	Email address to suppress. Must be a valid email format.
`--reason`	`string`	Yes	Reason code (see table below).
`--scope`	`string`	Yes	Suppression scope: `global`, `tenant`, or `campaign`.
`--campaign-id`	`string`	No	Campaign ID. Required when `--scope` is `campaign`.
`--source`	`string`	No	Source of the suppression (for your own tracking).
`--expires-at`	`string`	No	ISO 8601 expiry timestamp. If omitted, suppression is permanent.

Via the API

POST https://api.molted.email/v1/suppressions

curl

curl -X POST https://api.molted.email/v1/suppressions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_abc123",
    "recipientEmail": "user@example.com",
    "scope": "tenant",
    "reasonCode": "manual_dnc",
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

Field	Type	Required	Description
`tenantId`	`string`	Yes	Your tenant identifier.
`recipientEmail`	`string`	Yes	Email address to suppress.
`scope`	`string`	Yes	Suppression scope: `global`, `tenant`, or `campaign`.
`reasonCode`	`string`	Yes	Reason code (see table below).
`campaignId`	`string`	No	Campaign ID. Required when `scope` is `campaign`.
`source`	`string`	No	Source of the suppression (for your own tracking).
`expiresAt`	`string`	No	ISO 8601 expiry timestamp. If omitted, suppression is permanent.

Reason codes

Code	Description
`complaint`	Recipient marked an email as spam.
`hard_bounce`	Email address hard-bounced.
`manual_dnc`	Manually added to do-not-contact list.
`legal_request`	Suppressed due to a legal request (e.g., GDPR erasure).
`role_account`	Role account (e.g., `info@`, `admin@`) that should not receive automated email.
`domain_suppressed`	Entire domain is suppressed.
`no_engagement`	Contact has not engaged with prior emails. Consider using `--expires-at` for temporary suppression.

Remove a suppression

CLI

molted suppressions remove SUPPRESSION_ID

curl

curl -X DELETE "https://api.molted.email/v1/suppressions/SUPPRESSION_ID?tenantId=tenant_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

List suppressions

CLI

molted suppressions list --email user@example.com

curl

curl "https://api.molted.email/v1/suppressions?tenantId=tenant_abc123&recipientEmail=user@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameter	Type	Required	Description
`tenantId`	`string`	Yes	Your tenant identifier.
`recipientEmail`	`string`	No	Filter by email address.

Consent records document the legal basis for contacting someone. The policy engine checks consent before marketing sends -- missing consent blocks the send with reason no_consent. Transactional emails (receipts, password resets) are exempt.

CLI

molted consent record --email alice@example.com \
  --type explicit_opt_in --source signup-form --jurisdiction EU

CLI - revoke consent

molted consent record --email alice@example.com \
  --type explicit_opt_in --revoked-at 2026-06-15T00:00:00Z

CLI flags

Flag	Type	Required	Description
`--email`	`string`	Yes	Recipient email address.
`--type`	`string`	Yes	Legal basis (see table below).
`--source`	`string`	No	Where consent was collected (e.g., `signup-form`).
`--jurisdiction`	`string`	No	Jurisdiction code (e.g., `EU`, `US-CA`, `UK`, `BR`). Free-form, used for compliance reporting.
`--granted-at`	`string`	No	When consent was granted (ISO 8601). Defaults to now.
`--revoked-at`	`string`	No	When consent was revoked (ISO 8601). Set this to revoke existing consent.

Via the API

POST https://api.molted.email/v1/consent

curl

curl -X POST https://api.molted.email/v1/consent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_abc123",
    "recipientEmail": "alice@example.com",
    "basis": "explicit_opt_in",
    "source": "signup-form",
    "jurisdiction": "EU"
  }'

Legal bases

Basis	Description
`explicit_opt_in`	Recipient explicitly agreed to receive email. Strongest basis, required for EU.
`legitimate_interest`	Business relationship justifies contact.
`contractual`	Email is necessary to fulfill a contract.
`legal_obligation`	Email is legally required.

Use consent check to verify whether you have a valid legal basis to send marketing email to a recipient.

CLI

molted consent check --email alice@example.com

curl

curl "https://api.molted.email/v1/consent?tenantId=tenant_abc123&recipientEmail=alice@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "hasConsent": true,
  "basis": "explicit_opt_in",
  "source": "signup-form",
  "jurisdiction": "EU",
  "grantedAt": "2026-01-15T10:00:00Z"
}

Marketing sends to this address are allowed.

Response

{
  "hasConsent": false
}

No consent record exists. Marketing sends to this address will be blocked by the policy engine with reason no_consent. Transactional sends are unaffected.

To unblock marketing sends, record consent:

molted consent record --email alice@example.com \
  --type explicit_opt_in --source signup-form --jurisdiction EU

Response

{
  "hasConsent": false,
  "revokedAt": "2026-06-15T00:00:00Z"
}

Consent was previously granted but has been revoked. Marketing sends are blocked. To re-enable, record a new consent with a fresh legal basis.

Consent is per-email address, not per-contact.
The policy engine auto-checks consent on every marketing send -- you do not need to call consent check manually before sending.
consent check is useful for pre-flight validation in your agent logic, or for building UI that shows consent status.
Transactional templates bypass consent checks entirely.

GDPR & Privacy -- data export, deletion, and decision trace
Sending Email -- how the policy engine evaluates send requests

On this page