Reference
Send the confirmation link for a sample
POST /v1/sample-requests/{id}/email. The person's work email address, from the calling server's own form, never through a model.
POST /v1/sample-requests/{id}/email
The person's work email address, from the calling server's own form, never through a model. A one-time link is emailed; the answer is the same whether the address was accepted or refused (suppressed, objecting, over a limit), so it cannot be used to test addresses. Free webmail and malformed addresses get 422.
| Property | Value |
|---|---|
| Endpoint | POST https://mydatahub.emailmovers.com/v1/sample-requests/{id}/email |
| Operation id | createSampleRequestEmail |
| Cost | Free (0 credits) |
| Access | An API key or an OAuth 2.1 token with the scope samples:request. |
| Tag | Samples |
Request
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Format: a sample request id: smr_ followed by a 26 character ULID in upper case Crockford base32, such as smr_01JB4P2Q5W8ZAK8Q2V7XN3M9R6. |
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. |
Body
| Member | Type | Required | Description |
|---|---|---|---|
email | string (email) | yes | The person's work email address, sent by the calling server from its own form, never through a model. Free webmail addresses are refused. |
follow_up | boolean | yes | Whether the person ticked the box allowing Emailmovers to email them about the sample. |
wording | string | yes | The version of the wording the person saw beside the field and the box. |
Example request
curl -X POST "https://mydatahub.emailmovers.com/v1/sample-requests/smr_01JB4P2Q5W8ZAK8Q2V7XN3M9R6/email" \
-H "Authorization: Bearer $MYDATAHUB_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"email": "[email protected]",
"follow_up": false,
"wording": "2026-10-11"
}'Responses
202: Taken: the person checks their inbox.
Headers: RateLimit, RateLimit-Policy.
| Member | Type | Always present | Description |
|---|---|---|---|
status | check_your_inbox | yes | The same answer whether the address was accepted or refused (a suppressed address, an objection, a limit), so the call cannot be used to test addresses. |
Example response
{
"status": "check_your_inbox"
}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. |
| 404 | not-found | No such object for this organisation. |
| 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. |