Reference

Report an objection

POST /v1/objections. Record an objection to direct marketing.

Generated from the contractsView as Markdown

POST /v1/objections

Record an objection to direct marketing. Scope licensee suppresses the record for your organisation at once; scope emailmovers suppresses it database-wide within one working day and tells every licensee holding it.

Property	Value
Endpoint	`POST https://mydatahub.emailmovers.com/v1/objections`
Operation id	`reportObjection`
Cost	Free (0 credits)
Access	An API key or an OAuth 2.1 token with the scope `suppressions:write`.
Idempotency-Key	Optional. Makes a retry safe.
MCP tool	`report_objection`
Tag	Suppressions

Request

Parameters

Name	In	Type	Required	Description
`MyDataHub-Version`	header	string	no	The dated API version, pinned per key when left out. Non-breaking changes ship as new dates; the path major changes only for breaking changes, with a 12 month deprecation window.
`Idempotency-Key`	header	string	no	Makes the request safe to retry: the same key returns the stored response. Keys are kept for the life of the organisation.

Body

Member	Type	Required	Description
`record_id`	string	no	Format: a contact id: contact_ followed by a 26 character ULID in upper case Crockford base32, such as contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8.
`email_sha256`	string	no	SHA-256 of the trimmed, lower cased address, when the record id is not known.
`channel`	enum: `email`, `telephone`, `post`, `web_form`, `other`	yes
`received_at`	string (date-time)	yes	RFC 3339 date and time, with Z or an offset such as +01:00.
`scope`	enum: `licensee`, `emailmovers`	yes	licensee suppresses the record for your organisation at once; emailmovers suppresses it database-wide within one working day.
`note`	string	no

Example request

curl -X POST "https://mydatahub.emailmovers.com/v1/objections" \
  -H "Authorization: Bearer $MYDATAHUB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "record_id": "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8",
  "channel": "email",
  "received_at": "2026-10-01T08:30:00Z",
  "scope": "emailmovers",
  "note": "Replied asking not to be contacted again."
}'

Responses

201: The suppression it created.

Headers: RateLimit, RateLimit-Policy.

Member	Type	Always present	Description
`suppression_id`	string	yes	The list the record now sits on.
`record_id`	string or null	yes
`scope`	enum: `licensee`, `emailmovers`	yes
`status`	enum: `suppressed`, `pending`	yes	suppressed now, or pending until the database-wide overlay applies.
`suppressed_at`	string (date-time) or null	yes
`effective_by`	string (date-time)	yes

Example response

{
  "suppression_id": "sup_01JA0Q5V7XN3M9R6T1Y5W8ZAK8",
  "record_id": "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8",
  "scope": "emailmovers",
  "status": "pending",
  "suppressed_at": null,
  "effective_by": "2026-10-02T17:00:00Z"
}

Errors

Every error is a problem object with a code and a next_step. Every response carries the RateLimit and RateLimit-Policy headers; see Rate limits.

Status	Problem codes	When
400	`invalid-request`, `idempotency-key-required`, `unsupported-version`	The request could not be read, or an Idempotency-Key is missing.
401	`authentication-required`, `account-required`	Sign in (OAuth) or send an API key (authentication-required), or create a free account for what the anonymous tier does not cover (account-required).
403	`insufficient-scope`, `confirmation-required`, `business-details-required`, `licence-acceptance-required`, `dpa-acceptance-required`, `agent-budget-exceeded`	The token lacks a scope (insufficient-scope, with required_scope and a WWW-Authenticate step-up challenge); no person confirmed the spend and no agent key covers it (confirmation-required, with an approval_url); an agent key's per-order cap or monthly budget does not cover it (agent-budget-exceeded); an account made by self-serve sign-up has not yet confirmed its business name and that it is a UK business, which its first order needs (business-details-required); the order needs the Data Licence and Sharing Agreement accepted at the version in force (licence-acceptance-required); or a suppression upload comes before the organisation has accepted the Article 28 data processing agreement in force (dpa-acceptance-required). Nothing is charged.
409	`idempotency-key-reused`, `quote-expired`, `order-not-ready`, `order-not-cancellable`	An Idempotency-Key reused with different parameters, an expired machine quote, or an object in the wrong state.
422	`validation-failed`, `quote-required`, `dataset-unavailable`	The request is not valid. errors lists every problem with a JSON pointer and did_you_mean.
429	`rate-limited`	Too many requests. Wait for Retry-After.
Any other failure	`internal-error`, `service-unavailable`, `tps-screen-expired`	Something failed on our side (500 internal-error) or the service is briefly unavailable (503 service-unavailable, with Retry-After). Nothing was charged; retry with the same Idempotency-Key. A count, sample, quote or order with telephone in play is also refused with 503 tps-screen-expired, with no Retry-After, while the dataset version's TPS and CTPS screen is more than 28 days old.