15 operations. Guide: Manage contacts and consent, Let recipients unsubscribe. Requests and responses are JSON with snake_case fields; authenticate with Authorization: Bearer <api key>. The examples assume a client built as in SDKs and the command line.

Create a contact

POST /v1/contacts

Properties must be defined first; topics and static segments must exist. The consent ledger records the subscription, and an unsubscribed contact's address is suppressed on the marketing stream.

Operation createContact, SDK minket.contacts.create. Keys: full access. Live keys only: test keys get 403 test_mode_only.

Request body

FieldTypeRequiredDescription
emailstringyesAn email address without display name.
first_namestring or nullnoAt most 100 characters.
last_namestring or nullnoAt most 100 characters.
unsubscribedbooleanno
propertiesmap of string or number or boolean or nullno
segmentsarray of objectnoAt most 50 items.
segments[].idstringyesA UUID.
topicsarray of objectnoAt most 50 items.
topics[].idstringyesA UUID.
topics[].subscriptionone of "opt_in", "opt_out"yes
sourcestringnoAt most 100 characters.

Response

201 Created: Contact.

FieldTypeRequiredDescription
idstringyesA UUID.
object"contact"yes
project_idstringyesA UUID.
emailstringyes
first_namestring or nullyes
last_namestring or nullyes
unsubscribedbooleanyes
statusone of "active", "unsubscribed", "bounced", "complained", "sunset"yes
propertiesmap of string or number or boolean or nullyes
topicsarray of objectyes
topics[].idstringyesA UUID.
topics[].subscriptionone of "opt_in", "opt_out"yes
segment_idsarray of stringyes
last_sent_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
last_opened_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
last_clicked_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
created_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
updated_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl -X POST https://api.minket.com/v1/contacts \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","first_name":"Jane","last_name":"Doe"}'

List contacts

GET /v1/contacts

Newest first. email matches part of the address.

Operation listContacts, SDK minket.contacts.list. Keys: full access. Test keys work on test-mode data.

Parameters

NameInTypeRequiredDescription
limitqueryintegerno Default 20.
afterquerystringnoA UUID.
beforequerystringnoA UUID.
emailquerystringno
segment_idquerystringnoA UUID.
topic_idquerystringnoA UUID.
statusqueryone of "active", "unsubscribed", "bounced", "complained", "sunset"no

Response

200 Success: object.

FieldTypeRequiredDescription
object"list"yes
dataarray of objectyes
data[].idstringyesA UUID.
data[].object"contact"yes
data[].project_idstringyesA UUID.
data[].emailstringyes
data[].first_namestring or nullyes
data[].last_namestring or nullyes
data[].unsubscribedbooleanyes
data[].statusone of "active", "unsubscribed", "bounced", "complained", "sunset"yes
data[].propertiesmap of string or number or boolean or nullyes
data[].last_sent_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
data[].last_opened_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
data[].last_clicked_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
data[].created_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
data[].updated_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
has_morebooleanyes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl https://api.minket.com/v1/contacts \
  -H "Authorization: Bearer $MINKET_API_KEY"

Import contacts from CSV

POST /v1/contacts/import

Up to 4 MB inline as base64 content, up to 50 MB through POST /v1/uploads (purpose import) and upload_id. Processed in the background; poll the import for its counts and row errors.

Operation importContacts, SDK minket.contacts.import. Keys: full access. Live keys only: test keys get 403 test_mode_only.

Request body

FieldTypeRequiredDescription
contentstringnoAt most 5592410 characters.
upload_idstringnoA UUID.
column_mapobjectnoDefault {"email":"email"}.
column_map.emailstringnoDefault "email".
column_map.first_namestringno
column_map.last_namestringno
column_map.unsubscribedstringno
column_map.propertiesmap of objectno
on_conflictone of "upsert", "skip"noDefault "upsert".
segmentsarray of objectnoAt most 50 items.
segments[].idstringyesA UUID.
topicsarray of objectno
topics[].idstringyesA UUID.
topics[].subscriptionone of "opt_in", "opt_out"yes

Response

202 Queued: object.

FieldTypeRequiredDescription
idstringyesA UUID.
object"contact_import"yes
statusone of "queued", "in_progress", "completed", "failed"yes
countsobjectyes
counts.totalintegeryes
counts.createdintegeryes
counts.updatedintegeryes
counts.skippedintegeryes
counts.failedintegeryes
errorstring or nullyes
errorsarray of objectyes
errors[].rowintegeryes
errors[].messagestringyes
created_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
completed_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl -X POST https://api.minket.com/v1/contacts/import \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"ZW1haWwsZmlyc3RfbmFtZQpqYW5lQGV4YW1wbGUuY29tLEphbmUK","column_map":{"email":"email","first_name":"first_name"}}'

List imports

GET /v1/contacts/import

Operation listImports, SDK minket.contacts.imports.list. Keys: full access. Test keys work on test-mode data.

Parameters

NameInTypeRequiredDescription
limitqueryintegerno Default 20.
afterquerystringnoA UUID.
beforequerystringnoA UUID.
statusqueryone of "queued", "in_progress", "completed", "failed"no

Response

200 Success: object.

FieldTypeRequiredDescription
object"list"yes
dataarray of objectyes
data[].idstringyesA UUID.
data[].object"contact_import"yes
data[].statusone of "queued", "in_progress", "completed", "failed"yes
data[].countsobjectyes
data[].counts.totalintegeryes
data[].counts.createdintegeryes
data[].counts.updatedintegeryes
data[].counts.skippedintegeryes
data[].counts.failedintegeryes
data[].errorstring or nullyes
data[].errorsarray of objectyes
data[].errors[].rowintegeryes
data[].errors[].messagestringyes
data[].created_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
data[].completed_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
has_morebooleanyes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl https://api.minket.com/v1/contacts/import \
  -H "Authorization: Bearer $MINKET_API_KEY"

Get an import

GET /v1/contacts/import/{id}

Operation getImport, SDK minket.contacts.imports.get. Keys: full access. Test keys work on test-mode data.

Parameters

NameInTypeRequiredDescription
idpathstringyesA UUID.

Response

200 Success: object.

FieldTypeRequiredDescription
idstringyesA UUID.
object"contact_import"yes
statusone of "queued", "in_progress", "completed", "failed"yes
countsobjectyes
counts.totalintegeryes
counts.createdintegeryes
counts.updatedintegeryes
counts.skippedintegeryes
counts.failedintegeryes
errorstring or nullyes
errorsarray of objectyes
errors[].rowintegeryes
errors[].messagestringyes
created_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
completed_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl https://api.minket.com/v1/contacts/import/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $MINKET_API_KEY"

Export contacts as CSV

POST /v1/contacts/export

A presigned download of up to 200,000 contacts, valid until expires_at (an hour at most).

Operation exportContacts, SDK minket.contacts.export. Keys: full access. Test keys work on test-mode data.

Request body

FieldTypeRequiredDescription
segment_idstringnoA UUID.
statusone of "active", "unsubscribed", "bounced", "complained", "sunset"no

Response

200 Success: object.

FieldTypeRequiredDescription
object"export"yes
download_urlstringyes
expires_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl -X POST https://api.minket.com/v1/contacts/export \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"active"}'

Send a custom event for a contact

POST /v1/contacts/events

Recorded in the contact's history; starts any automation triggered by this event.

Operation sendContactEvent, SDK minket.contacts.sendEvent. Keys: full access. Test keys work on test-mode data.

Request body

FieldTypeRequiredDescription
eventstringyes1 to 100 characters.
contact_idstringnoA UUID.
emailstringnoAn email address without display name.
payloadmap of anyno

Response

202 Accepted: object.

FieldTypeRequiredDescription
object"event"yes
eventstringyes
runs_startedintegeryes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl -X POST https://api.minket.com/v1/contacts/events \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":"signed_up","email":"jane@example.com","payload":{"plan":"pro"}}'

List contact properties

GET /v1/contacts/properties

Operation listContactProperties, SDK minket.contacts.properties.list. Keys: full access. Test keys work on test-mode data.

Response

200 Success: object.

FieldTypeRequiredDescription
object"list"yes
dataarray of objectyes
data[].idstringyesA UUID.
data[].object"contact_property"yes
data[].keystringyes
data[].typeone of "string", "number", "boolean", "date"yes
data[].fallback_valuestring or number or boolean or nullyes
data[].created_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
has_morebooleanyes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl https://api.minket.com/v1/contacts/properties \
  -H "Authorization: Bearer $MINKET_API_KEY"

Define a contact property

POST /v1/contacts/properties

Operation createContactProperty, SDK minket.contacts.properties.create. Keys: full access. Live keys only: test keys get 403 test_mode_only.

Request body

FieldTypeRequiredDescription
keystringyes1 to 50 characters.
typeone of "string", "number", "boolean", "date"yes
fallback_valuestring or number or boolean or nullno

Response

201 Created: object.

FieldTypeRequiredDescription
idstringyesA UUID.
object"contact_property"yes
keystringyes
typeone of "string", "number", "boolean", "date"yes
fallback_valuestring or number or boolean or nullyes
created_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl -X POST https://api.minket.com/v1/contacts/properties \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"plan","type":"string"}'

Delete a contact property

DELETE /v1/contacts/properties/{id}

Removes the property's value from every contact.

Operation deleteContactProperty, SDK minket.contacts.properties.delete. Keys: full access. Live keys only: test keys get 403 test_mode_only.

Parameters

NameInTypeRequiredDescription
idpathstringyesA UUID.

Response

200 Success: object.

FieldTypeRequiredDescription
object"contact_property"yes
idstringyes
deletedtrueyes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl -X DELETE https://api.minket.com/v1/contacts/properties/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $MINKET_API_KEY"

Get a contact (by id or email)

GET /v1/contacts/{id}

Operation getContact, SDK minket.contacts.get. Keys: full access. Test keys work on test-mode data.

Parameters

NameInTypeRequiredDescription
idpathstringyes

Response

200 Success: Contact.

FieldTypeRequiredDescription
idstringyesA UUID.
object"contact"yes
project_idstringyesA UUID.
emailstringyes
first_namestring or nullyes
last_namestring or nullyes
unsubscribedbooleanyes
statusone of "active", "unsubscribed", "bounced", "complained", "sunset"yes
propertiesmap of string or number or boolean or nullyes
topicsarray of objectyes
topics[].idstringyesA UUID.
topics[].subscriptionone of "opt_in", "opt_out"yes
segment_idsarray of stringyes
last_sent_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
last_opened_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
last_clicked_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
created_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
updated_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl https://api.minket.com/v1/contacts/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $MINKET_API_KEY"

Update a contact

PATCH /v1/contacts/{id}

Properties merge (null removes one); segments replaces the contact's static segments; topics sets the listed topics.

Operation updateContact, SDK minket.contacts.update. Keys: full access. Live keys only: test keys get 403 test_mode_only.

Parameters

NameInTypeRequiredDescription
idpathstringyes

Request body

FieldTypeRequiredDescription
first_namestring or nullnoAt most 100 characters.
last_namestring or nullnoAt most 100 characters.
unsubscribedbooleanno
propertiesmap of string or number or boolean or nullno
segmentsarray of objectnoAt most 50 items.
segments[].idstringyesA UUID.
topicsarray of objectnoAt most 50 items.
topics[].idstringyesA UUID.
topics[].subscriptionone of "opt_in", "opt_out"yes
sourcestringnoAt most 100 characters.

Response

200 Success: Contact.

FieldTypeRequiredDescription
idstringyesA UUID.
object"contact"yes
project_idstringyesA UUID.
emailstringyes
first_namestring or nullyes
last_namestring or nullyes
unsubscribedbooleanyes
statusone of "active", "unsubscribed", "bounced", "complained", "sunset"yes
propertiesmap of string or number or boolean or nullyes
topicsarray of objectyes
topics[].idstringyesA UUID.
topics[].subscriptionone of "opt_in", "opt_out"yes
segment_idsarray of stringyes
last_sent_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
last_opened_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
last_clicked_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
created_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
updated_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl -X PATCH https://api.minket.com/v1/contacts/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Janet"}'

Delete a contact

DELETE /v1/contacts/{id}

Suppressions for the address stay.

Operation deleteContact, SDK minket.contacts.delete. Keys: full access. Live keys only: test keys get 403 test_mode_only.

Parameters

NameInTypeRequiredDescription
idpathstringyes

Response

200 Success: object.

FieldTypeRequiredDescription
object"contact"yes
idstringyes
deletedtrueyes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl -X DELETE https://api.minket.com/v1/contacts/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $MINKET_API_KEY"

Consent ledger for a contact

GET /v1/contacts/{id}/consent

Operation listContactConsent, SDK minket.contacts.consent. Keys: full access. Test keys work on test-mode data.

Parameters

NameInTypeRequiredDescription
idpathstringyesA UUID.
limitqueryintegerno Default 20.
afterquerystringnoA UUID.
beforequerystringnoA UUID.

Response

200 Success: object.

FieldTypeRequiredDescription
object"list"yes
dataarray of objectyes
data[].idstringyesA UUID.
data[].object"consent"yes
data[].contact_idstringyesA UUID.
data[].topic_idstring or nullyesA UUID.
data[].actionone of "subscribe", "unsubscribe", "double_optin_sent", "double_optin_confirmed", "import", "sunset", "resubscribe"yes
data[].sourceone of "api", "console", "import", "preference_center", "one_click", "list_unsubscribe", "double_opt_in", "automation", "system"yes
data[].ipstring or nullyes
data[].user_agentstring or nullyes
data[].evidencemap of any or nullyes
data[].created_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
has_morebooleanyes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl https://api.minket.com/v1/contacts/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/consent \
  -H "Authorization: Bearer $MINKET_API_KEY"

Send a double opt-in confirmation

POST /v1/contacts/{id}/optin

Emails the contact a link that confirms their subscription (to topic_id, or to marketing mail). The link expires after 72 hours. Sent through the send pipeline from a domain of the project.

Operation sendContactOptin, SDK minket.contacts.optin. Keys: full access. Live keys only: test keys get 403 test_mode_only.

Parameters

NameInTypeRequiredDescription
idpathstringyes

Request body

FieldTypeRequiredDescription
fromstringyesAn email address, optionally with a display name as Name <address>. 3 to 998 characters.
subjectstringnoAt most 998 characters.
reply_tostring or array of stringnoOne address, or an array of up to 50.
topic_idstringnoA UUID.

Response

200 Success: object.

FieldTypeRequiredDescription
object"optin"yes
contact_idstringyesA UUID.
topic_idstring or nullyesA UUID.
email_idstringyesA UUID.
expires_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, with the error body.

Examples

curl
curl -X POST https://api.minket.com/v1/contacts/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/optin \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"Acme <hello@mail.acme.example>"}'

Updated