10 operations. Guide: Send email with the API, How an email is delivered. 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.

Get email metrics

GET /v1/emails/metrics

Totals for a range (by default today and the six days before it), and with dimensions rows by period (in timezone, at granularity), domain, email or broadcast. Counts cover the key's project, environment and mode: received emails accepted, events by type and bounce kind, opens and clicks with their unique emails, and unsubscribes from an email's own links. Rates are percentages with one decimal. Lists take commas or repeated parameters.

Operation getEmailMetrics, SDK minket.emails.metrics. Keys: full access. Test keys work on test-mode data.

Parameters

NameInTypeRequiredDescription
start_datequerystringno
end_datequerystringno
timezonequerystringno
granularityqueryone of "hourly", "daily", "weekly", "monthly"no
metricsquerystring or array of stringnoComma-separated, or the parameter repeated
dimensionsquerystring or array of stringnoComma-separated, or the parameter repeated
domain_idquerystring or array of stringnoComma-separated, or the parameter repeated
email_idquerystring or array of stringnoComma-separated, or the parameter repeated
broadcast_idquerystring or array of stringnoComma-separated, or the parameter repeated

Response

200 Success: object.

FieldTypeRequiredDescription
object"metrics"yes
start_datestring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
end_datestring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
metricsarray of one of "received", "delivered", "complained", "suppressed", "bounced", "bounced_transient", "bounced_permanent", "bounced_undetermined", "opened", "clicked", "unsubscribed", "delivery_delayed", …yes
dimensionsarray of one of "period", "domain", "email", "broadcast"yes
granularityone of "hourly", "daily", "weekly", "monthly"yes
totalsobjectyes
totals.receivednumberno
totals.deliverednumberno
totals.complainednumberno
totals.suppressednumberno
totals.bouncednumberno
totals.bounced_transientnumberno
totals.bounced_permanentnumberno
totals.bounced_undeterminednumberno
totals.openednumberno
totals.clickednumberno
totals.unsubscribednumberno
totals.delivery_delayednumberno
totals.failednumberno
totals.sentnumberno
totals.unique_openednumberno
totals.unique_clickednumberno
totals.delivery_ratenumberno
totals.open_ratenumberno
totals.click_ratenumberno
totals.bounce_ratenumberno
totals.complaint_ratenumberno
totals.unsubscribe_ratenumberno
dataarray of objectno
data[].receivednumberno
data[].deliverednumberno
data[].complainednumberno
data[].suppressednumberno
data[].bouncednumberno
data[].bounced_transientnumberno
data[].bounced_permanentnumberno
data[].bounced_undeterminednumberno
data[].openednumberno
data[].clickednumberno
data[].unsubscribednumberno
data[].delivery_delayednumberno
data[].failednumberno
data[].sentnumberno
data[].unique_openednumberno
data[].unique_clickednumberno
data[].delivery_ratenumberno
data[].open_ratenumberno
data[].click_ratenumberno
data[].bounce_ratenumberno
data[].complaint_ratenumberno
data[].unsubscribe_ratenumberno
data[].periodstringno
data[].domain_idstringnoA UUID.
data[].domain_namestringno
data[].email_idstringnoA UUID.
data[].broadcast_idstringnoA UUID.
data[].broadcast_namestringno

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

Examples

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

Send an email

POST /v1/emails

Queues one email. Send Idempotency-Key (or idempotency_key) to make retries safe for 24 hours; a repeated key returns the original response.

Operation sendEmail, SDK minket.emails.send. Keys: full access, sending access. Test keys work on test-mode data.

Request body

FieldTypeRequiredDescription
fromstringnoAn email address, optionally with a display name as Name <address>. 3 to 998 characters.
tostring or array of stringyesOne address, or an array of up to 50.
ccstring or array of stringnoOne address, or an array of up to 50.
bccstring or array of stringnoOne address, or an array of up to 50.
reply_tostring or array of stringnoOne address, or an array of up to 50.
subjectstringnoAt most 998 characters.
htmlstringno
textstringno
templateobjectno
template.idstringyesTemplate id or alias.
template.versionintegernoDefaults to the published version.
template.variablesmap of string or number or boolean or nullno
headersmap of stringnoCustom headers. Structural headers (From, To, Subject, ...) cannot be set here.
attachmentsarray of objectnoAt most 20 items.
attachments[] (shape 1).filenamestringyes1 to 255 characters.
attachments[] (shape 1).contentstring or object or array of integeryes
attachments[] (shape 1).content (shape 1).type"Buffer"yes
attachments[] (shape 1).content (shape 1).dataarray of integeryes
attachments[] (shape 1).content_typestringnoAt most 255 characters.
attachments[] (shape 1).content_idstringnoAt most 255 characters.
attachments[] (shape 1).dispositionone of "attachment", "inline"no
attachments[] (shape 2).idstringyesA UUID.
attachments[] (shape 2).filenamestringno1 to 255 characters.
attachments[] (shape 2).content_idstringnoAt most 255 characters.
attachments[] (shape 2).dispositionone of "attachment", "inline"no
attachments[] (shape 3).pathstringyesAn https URL to a public host. Private, loopback, link-local and metadata addresses are refused, also after DNS resolution and redirects. At most 2048 characters.
attachments[] (shape 3).filenamestringno1 to 255 characters.
attachments[] (shape 3).content_typestringnoAt most 255 characters.
attachments[] (shape 3).content_idstringnoAt most 255 characters.
tagsarray of objectnoAt most 50 items.
tags[].namestringyes
tags[].valuestringyes
scheduled_atstringnoISO 8601 or natural language (in 1 hour), at most 30 days ahead. At most 100 characters.
streamone of "transactional", "marketing"noDefaults to the stream of the from domain.
topic_idstring or nullnoMarketing: the topic this email belongs to; unsubscribe links point at it.
viaobjectnoSend through a connected mailbox instead of a domain.
via.mailboxstringyesA UUID.
idempotency_keystringnoAlternative to the Idempotency-Key header. 1 to 256 characters.
trackingobjectno
tracking.opensbooleanno
tracking.clicksbooleanno

Response

200 Success: object.

FieldTypeRequiredDescription
idstringyesA UUID.
object"email"yes
statusone of "queued", "scheduled", "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "canceled", "suppressed"yes
scheduled_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
idempotent_replaybooleanyes

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

Examples

curl
curl -X POST https://api.minket.com/v1/emails \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"Acme <hello@mail.acme.example>","subject":"Your receipt","text":"Thanks for your order.","to":"jane@example.com","tags":[{"name":"type","value":"receipt"}]}'

List emails

GET /v1/emails

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

Parameters

NameInTypeRequiredDescription
limitqueryintegerno Default 20.
afterquerystringnoA UUID.
beforequerystringnoA UUID.
toquerystringno
subjectquerystringno
statusqueryone of "queued", "scheduled", "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "canceled", "suppressed"no
streamqueryone of "transactional", "marketing"noTransactional mail is one-to-one and expected; marketing mail goes to lists and must carry List-Unsubscribe.
modequeryone of "live", "test"no
tagquerystringnoname:value
from_datequerystring (date-time)noAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
to_datequerystring (date-time)noAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
broadcast_idquerystringnoA UUID.

Response

200 Success: object.

FieldTypeRequiredDescription
object"list"yes
dataarray of objectyes
data[].idstringyesA UUID.
data[].object"email"yes
data[].project_idstringyesA UUID.
data[].environment_idstringyesA UUID.
data[].modeone of "live", "test"yes
data[].streamone of "transactional", "marketing"yesTransactional mail is one-to-one and expected; marketing mail goes to lists and must carry List-Unsubscribe.
data[].sourceone of "api", "smtp", "broadcast", "automation", "console", "inbound"yes
data[].statusone of "queued", "scheduled", "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "canceled", "suppressed"yes
data[].fromstringyes
data[].toarray of stringyes
data[].ccarray of stringyes
data[].bccarray of stringyes
data[].reply_toarray of stringyes
data[].subjectstringyes
data[].tagsarray of objectyes
data[].tags[].namestringyes
data[].tags[].valuestringyes
data[].templateobject or nullyes
data[].template.idstringyesA UUID.
data[].template.versionintegeryes
data[].topic_idstring or nullyesA UUID.
data[].viaobject or nullyes
data[].via.mailboxstringyesA UUID.
data[].attachmentsarray of objectyes
data[].attachments[].idstringyesA UUID.
data[].attachments[].filenamestring or nullyes
data[].attachments[].content_typestringyes
data[].attachments[].sizeintegeryes
data[].attachments[].content_idstring or nullyes
data[].attachments[].dispositionone of "attachment", "inline"yes
data[].message_idstring or nullyes
data[].providerobject or nullyes
data[].provider.nameone of "ses", "resend", "gmail", "microsoft", "smtp", "test"yes
data[].provider.regionstring or nullyes
data[].broadcast_idstring or nullyesA UUID.
data[].automation_run_idstring or nullyesA UUID.
data[].warningsarray of objectyes
data[].warnings[].checkstringyes
data[].warnings[].messagestringyes
data[].warnings[].hostsarray of stringno
data[].scheduled_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
data[].sent_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/emails \
  -H "Authorization: Bearer $MINKET_API_KEY"

Send up to 100 emails

POST /v1/emails/batch

Each item is validated and queued on its own; the response carries a result per item.

Operation sendBatch, SDK minket.emails.sendBatch. Keys: full access, sending access. Test keys work on test-mode data.

Request body

An array of SendEmailRequest. At most 100 items.

FieldTypeRequiredDescription
fromstringnoAn email address, optionally with a display name as Name <address>. 3 to 998 characters.
tostring or array of stringyesOne address, or an array of up to 50.
ccstring or array of stringnoOne address, or an array of up to 50.
bccstring or array of stringnoOne address, or an array of up to 50.
reply_tostring or array of stringnoOne address, or an array of up to 50.
subjectstringnoAt most 998 characters.
htmlstringno
textstringno
templateobjectno
template.idstringyesTemplate id or alias.
template.versionintegernoDefaults to the published version.
template.variablesmap of string or number or boolean or nullno
headersmap of stringnoCustom headers. Structural headers (From, To, Subject, ...) cannot be set here.
attachmentsarray of objectnoAt most 20 items.
attachments[] (shape 1).filenamestringyes1 to 255 characters.
attachments[] (shape 1).contentstring or object or array of integeryes
attachments[] (shape 1).content (shape 1).type"Buffer"yes
attachments[] (shape 1).content (shape 1).dataarray of integeryes
attachments[] (shape 1).content_typestringnoAt most 255 characters.
attachments[] (shape 1).content_idstringnoAt most 255 characters.
attachments[] (shape 1).dispositionone of "attachment", "inline"no
attachments[] (shape 2).idstringyesA UUID.
attachments[] (shape 2).filenamestringno1 to 255 characters.
attachments[] (shape 2).content_idstringnoAt most 255 characters.
attachments[] (shape 2).dispositionone of "attachment", "inline"no
attachments[] (shape 3).pathstringyesAn https URL to a public host. Private, loopback, link-local and metadata addresses are refused, also after DNS resolution and redirects. At most 2048 characters.
attachments[] (shape 3).filenamestringno1 to 255 characters.
attachments[] (shape 3).content_typestringnoAt most 255 characters.
attachments[] (shape 3).content_idstringnoAt most 255 characters.
tagsarray of objectnoAt most 50 items.
tags[].namestringyes
tags[].valuestringyes
scheduled_atstringnoISO 8601 or natural language (in 1 hour), at most 30 days ahead. At most 100 characters.
streamone of "transactional", "marketing"noDefaults to the stream of the from domain.
topic_idstring or nullnoMarketing: the topic this email belongs to; unsubscribe links point at it.
viaobjectnoSend through a connected mailbox instead of a domain.
via.mailboxstringyesA UUID.
idempotency_keystringnoAlternative to the Idempotency-Key header. 1 to 256 characters.
trackingobjectno
tracking.opensbooleanno
tracking.clicksbooleanno

Response

200 Success: object.

FieldTypeRequiredDescription
object"batch"yes
dataarray of objectyes
data[] (shape 1).indexintegeryes
data[] (shape 1).idstringyesA UUID.
data[] (shape 1).statusone of "queued", "scheduled", "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "canceled", "suppressed"yes
data[] (shape 2).indexintegeryes
data[] (shape 2).errorobjectyes
data[] (shape 2).error.codestringyes
data[] (shape 2).error.messagestringyes
data[] (shape 2).error.retryablebooleanyes
acceptedintegeryes
rejectedintegeryes

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

Examples

curl
curl -X POST https://api.minket.com/v1/emails/batch \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"from":"Acme <hello@mail.acme.example>","subject":"Your receipt","text":"Thanks for your order.","to":"jane@example.com"},{"from":"Acme <hello@mail.acme.example>","subject":"Your receipt","text":"Thanks for your order.","to":"sam@example.com"}]'

Get an email

GET /v1/emails/{id}

Includes html and text while content is retained (30 days).

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

Parameters

NameInTypeRequiredDescription
idpathstringyesA UUID.

Response

200 Success: Email.

FieldTypeRequiredDescription
idstringyesA UUID.
object"email"yes
project_idstringyesA UUID.
environment_idstringyesA UUID.
modeone of "live", "test"yes
streamone of "transactional", "marketing"yesTransactional mail is one-to-one and expected; marketing mail goes to lists and must carry List-Unsubscribe.
sourceone of "api", "smtp", "broadcast", "automation", "console", "inbound"yes
statusone of "queued", "scheduled", "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "canceled", "suppressed"yes
fromstringyes
toarray of stringyes
ccarray of stringyes
bccarray of stringyes
reply_toarray of stringyes
subjectstringyes
headersmap of stringyes
tagsarray of objectyes
tags[].namestringyes
tags[].valuestringyes
templateobject or nullyes
template.idstringyesA UUID.
template.versionintegeryes
topic_idstring or nullyesA UUID.
viaobject or nullyes
via.mailboxstringyesA UUID.
attachmentsarray of objectyes
attachments[].idstringyesA UUID.
attachments[].filenamestring or nullyes
attachments[].content_typestringyes
attachments[].sizeintegeryes
attachments[].content_idstring or nullyes
attachments[].dispositionone of "attachment", "inline"yes
htmlstring or nullno
textstring or nullno
message_idstring or nullyes
providerobject or nullyes
provider.nameone of "ses", "resend", "gmail", "microsoft", "smtp", "test"yes
provider.regionstring or nullyes
broadcast_idstring or nullyesA UUID.
automation_run_idstring or nullyesA UUID.
warningsarray of objectyes
warnings[].checkstringyes
warnings[].messagestringyes
warnings[].hostsarray of stringno
scheduled_atstring (date-time) or nullyesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
sent_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/emails/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $MINKET_API_KEY"

Reschedule a scheduled email

PATCH /v1/emails/{id}

Operation rescheduleEmail, SDK minket.emails.reschedule. Keys: full access, sending access. Test keys work on test-mode data.

Parameters

NameInTypeRequiredDescription
idpathstringyesA UUID.

Request body

FieldTypeRequiredDescription
scheduled_atstringyesAt most 100 characters.

Response

200 Success: object.

FieldTypeRequiredDescription
object"email"yes
idstringyesA UUID.
statusone of "queued", "scheduled", "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "canceled", "suppressed"yes

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

Examples

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

Cancel a scheduled email

POST /v1/emails/{id}/cancel

Operation cancelEmail, SDK minket.emails.cancel. Keys: full access, sending access. Test keys work on test-mode data.

Parameters

NameInTypeRequiredDescription
idpathstringyesA UUID.

Response

200 Success: object.

FieldTypeRequiredDescription
object"email"yes
idstringyesA UUID.
statusone of "queued", "scheduled", "sent", "delivered", "delivery_delayed", "opened", "clicked", "bounced", "complained", "failed", "canceled", "suppressed"yes

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

Examples

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

Get an email's event timeline

GET /v1/emails/{id}/events

Operation listEmailEvents, SDK minket.emails.events. 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[].typestringyes
data[].created_atstring (date-time)yesAn ISO 8601 timestamp with timezone, for example 2026-10-24T18:00:00.000Z.
data[].datamap of anyyes
has_morebooleanyes

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

Examples

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

List an email's attachments with download URLs

GET /v1/emails/{id}/attachments

Operation listEmailAttachments, SDK minket.emails.attachments. Keys: full access. Test keys work on test-mode data.

Parameters

NameInTypeRequiredDescription
idpathstringyesA UUID.

Response

200 Success: object.

FieldTypeRequiredDescription
object"list"yes
dataarray of objectyes
data[].idstringyesA UUID.
data[].object"attachment"yes
data[].filenamestringyes
data[].content_typestringyes
data[].sizeintegeryes
data[].sha256stringyes
data[].download_urlstringno
data[].expires_atstring (date-time)noAn 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[].last_used_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/emails/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/attachments \
  -H "Authorization: Bearer $MINKET_API_KEY"

Share an email

POST /v1/emails/{id}/share

A link on links. that shows the email's headers and content to whoever has it, until expires_at (expires_in: up to and by default 48 hours). The content opens in a sandboxed frame: no scripts or forms. The link cannot be revoked; it only expires.

Operation shareEmail, SDK minket.emails.share. Keys: full access. Test keys work on test-mode data.

Parameters

NameInTypeRequiredDescription
idpathstringyesA UUID.

Request body

FieldTypeRequiredDescription
expires_instringnoAt most 40 characters.

Response

201 Created: object.

FieldTypeRequiredDescription
objectone of "email", "inbound"yes
idstringyesA UUID.
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/emails/019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b/share \
  -H "Authorization: Bearer $MINKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Updated