Skip to content
mailprompt
Start free trial

API reference

Mailprompt API version 1.0.0. This page is rendered from the OpenAPI 3.1 document that the contract tests validate against, so every operation below exists in the running API. The raw document is at /openapi.json.

No operation sends email or makes a flow live. Writes create drafts and request human approvals. Test keys (mp_test_) persist nothing and charge nothing.

Authentication, errors, rate limits, pagination, idempotency and webhooks are documented in the developer guide. Every operation is grouped by tag below.

Profiles

3 operations

GET/v1/profiles

List profiles

Cursor-paginated, newest id first. Scoped to the key's account.

Parameters for listProfiles
ParameterInTypeRequiredDescription
limitqueryintegerNo
cursorquerystringNoOpaque `next_cursor` from the previous page.
Responses
  • 200 A page of profiles. (ProfileList)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/profiles?limit=50' \
  -H 'Authorization: Bearer mp_live_your_key'
POST/v1/profiles

Create or update a profile by email

Upserts on the normalised email. `properties` is shallow-merged into the existing record. A suppressed profile cannot be resubscribed through the API (`409 conflict`). Returns 201 when created, 200 when updated. In test mode the response is synthetic and nothing is persisted.

Parameters for upsertProfile
ParameterInTypeRequiredDescription
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Request body
application/json

ProfileUpsertRequest

  • email string (email) required
  • first_name string
  • last_name string
  • phone string
  • properties object
  • consent_status string
  • consent_source string
Responses
  • 200 The profile was updated. (Profile)
  • 201 The profile was created. (Profile)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 409 State conflict, concurrent idempotent request, or an approval is required / already granted. (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/profiles' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13' \
  -H 'Content-Type: application/json' \
  --data '{"email":"[email protected]"}'
GET/v1/profiles/{id}

Get a profile

Parameters for getProfile
ParameterInTypeRequiredDescription
idpathstringYes
Responses
  • 200 The profile. (Profile)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/profiles/your_id' \
  -H 'Authorization: Bearer mp_live_your_key'

Events

1 operation

POST/v1/events

Track one event or a batch of up to 100

`events:write` uses its own rate-limit bucket at 10× the plan rate. Events with a `unique_id` are idempotent per `(account, metric, unique_id)`; duplicates are reported, not re-inserted. In test mode the response is synthetic and no events are stored.

Parameters for trackEvents
ParameterInTypeRequiredDescription
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Request body
application/json

EventsRequest

  • event EventInput required
    • metric string required
    • profile_id string
    • email string (email)
    • properties object
    • value integer
    • currency string
    • occurred_at string (ISO-8601)
    • unique_id string
Responses
  • 202 Events accepted. (EventsResponse)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/events' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13' \
  -H 'Content-Type: application/json' \
  --data '{"event":{"metric":"string"}}'

Lists

8 operations

GET/v1/lists

List contact lists

Cursor-paginated, newest id first. Includes archived lists so callers can audit them.

Parameters for listLists
ParameterInTypeRequiredDescription
limitqueryintegerNo
cursorquerystringNoOpaque `next_cursor` from the previous page.
Responses
  • 200 A page of lists. (ListList)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/lists?limit=50' \
  -H 'Authorization: Bearer mp_live_your_key'
POST/v1/lists

Create a contact list

Parameters for createList
ParameterInTypeRequiredDescription
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Request body
application/json

CreateListRequest

  • name string required
  • description string | null
  • consent_mode string
  • kind string
Responses
  • 201 The created list. (ListResponse)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/lists' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13' \
  -H 'Content-Type: application/json' \
  --data '{"name":"string"}'
GET/v1/lists/{id}

Get a list with member and consent counts

Parameters for getList
ParameterInTypeRequiredDescription
idpathstringYes
Responses
  • 200 The list. (ListResponse)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/lists/your_id' \
  -H 'Authorization: Bearer mp_live_your_key'
PATCH/v1/lists/{id}

Rename a list or change its consent mode

Parameters for updateList
ParameterInTypeRequiredDescription
idpathstringYes
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Request body
application/json

UpdateListRequest

  • name string
  • description string | null
  • consent_mode string
Responses
  • 200 The updated list. (ListResponse)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X PATCH 'https://api.mailprompt.ai/v1/lists/your_id' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13' \
  -H 'Content-Type: application/json' \
  --data '{"name":"string"}'
DELETE/v1/lists/{id}

Archive a list

Archived lists keep their members and evidence but are hidden from campaign pickers.

Parameters for archiveList
ParameterInTypeRequiredDescription
idpathstringYes
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Responses
  • 204 List archived. (none)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X DELETE 'https://api.mailprompt.ai/v1/lists/your_id' \
  -H 'Authorization: Bearer mp_live_your_key'
GET/v1/lists/{id}/members

List the people on a list

Parameters for listListMembers
ParameterInTypeRequiredDescription
idpathstringYes
limitqueryintegerNo
cursorquerystringNoOpaque `next_cursor` from the previous page.
Responses
  • 200 A page of members with their consent evidence. (ListMemberPage)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/lists/your_id/members?limit=50' \
  -H 'Authorization: Bearer mp_live_your_key'
POST/v1/lists/{id}/members

Add profiles to a list

All profile ids must belong to the key's account; otherwise 404. At most 1,000 ids per request. Test mode persists nothing.

Parameters for addListMembers
ParameterInTypeRequiredDescription
idpathstringYes
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Request body
application/json

AddMembersRequest

  • profile_ids array of string required
  • source string
  • consent_evidence one of ConsentEvidence | null
    • source string required
    • consented boolean
    • textShown string
    • ip string
    • formId string
    • importId string
    • at integer
Responses
  • 201 Members added (duplicates counted in `already_members`). (ListMembersResponse)
  • 202 At or above 1,000 people the addition waits for human approval; nothing was added. (ListMembersResponse)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/lists/your_id/members' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13' \
  -H 'Content-Type: application/json' \
  --data '{"profile_ids":["string"]}'
DELETE/v1/lists/{id}/members/{profileId}

Remove a profile from a list

204 on success, 404 when the list or membership does not exist.

Parameters for removeListMember
ParameterInTypeRequiredDescription
idpathstringYes
profileIdpathstringYes
Responses
  • 204 Member removed. (none)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X DELETE 'https://api.mailprompt.ai/v1/lists/your_id/members/profile_123' \
  -H 'Authorization: Bearer mp_live_your_key'

Segments

7 operations

GET/v1/segments

List segments with their cached counts

Counts are the cached values written by the segment evaluator (`counted_at` says when). Live evaluation is not performed on this path.

Parameters for listSegments
ParameterInTypeRequiredDescription
limitqueryintegerNo
cursorquerystringNoOpaque `next_cursor` from the previous page.
Responses
  • 200 A page of segments. (SegmentList)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/segments?limit=50' \
  -H 'Authorization: Bearer mp_live_your_key'
POST/v1/segments

Create a draft segment

The definition is validated against this account's real lists, tags, metrics, properties, products, collections and segments. Costs 1 credit and emails nobody.

Parameters for createSegment
ParameterInTypeRequiredDescription
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Request body
application/json

CreateSegmentRequest

  • name string required
  • description string | null
  • definition object required
Responses
  • 201 The created segment. (SegmentResponse)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 402 Not enough credits for this billable write. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/segments' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13' \
  -H 'Content-Type: application/json' \
  --data '{"name":"string","definition":{}}'
GET/v1/segments/{id}

Get a segment

Parameters for getSegment
ParameterInTypeRequiredDescription
idpathstringYes
Responses
  • 200 The segment with its definition and summary. (SegmentResponse)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/segments/your_id' \
  -H 'Authorization: Bearer mp_live_your_key'
PATCH/v1/segments/{id}

Save a new segment version

If a live flow or scheduled campaign uses the segment, the change returns `approval_required: true` and is not applied until an owner approves it. Costs 1 credit.

Parameters for updateSegment
ParameterInTypeRequiredDescription
idpathstringYes
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Request body
application/json

UpdateSegmentRequest

  • name string
  • description string | null
  • definition object
Responses
  • 200 The updated segment, or the pending approval. (SegmentResponse)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 402 Not enough credits for this billable write. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X PATCH 'https://api.mailprompt.ai/v1/segments/your_id' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13' \
  -H 'Content-Type: application/json' \
  --data '{"name":"string"}'
GET/v1/segments/{id}/count

Cached profile count for a segment

Parameters for getSegmentCount
ParameterInTypeRequiredDescription
idpathstringYes
Responses
  • 200 The cached count. (SegmentCount)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/segments/your_id/count' \
  -H 'Authorization: Bearer mp_live_your_key'
GET/v1/segments/{id}/members

Page the people currently in a segment

Parameters for listSegmentMembers
ParameterInTypeRequiredDescription
idpathstringYes
limitqueryintegerNo
cursorquerystringNoOpaque `next_cursor` from the previous page.
Responses
  • 200 A page of matching profiles. (SegmentMemberPage)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/segments/your_id/members?limit=50' \
  -H 'Authorization: Bearer mp_live_your_key'
POST/v1/segments/preview

Validate and count a segment definition

Uses a 5 second statement timeout and returns `slow: true` instead of hanging. Free.

Request body
application/json

PreviewSegmentRequest

  • segment_id string
  • definition object
Responses
  • 200 Validation result, count, summary and masked sample. (PreviewSegmentResponse)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/segments/preview' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13' \
  -H 'Content-Type: application/json' \
  --data '{"segment_id":"string"}'

Flows

4 operations

GET/v1/flows

List flows

Parameters for listFlows
ParameterInTypeRequiredDescription
limitqueryintegerNo
cursorquerystringNoOpaque `next_cursor` from the previous page.
Responses
  • 200 A page of flows. (FlowList)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/flows?limit=50' \
  -H 'Authorization: Bearer mp_live_your_key'
POST/v1/flows

Create a flow draft

Creates a `draft` only. Costs 10 credits (PLAN §2); `?dry_run=true` returns `{ dry_run: true, credits: 10 }` and changes nothing. Asking for `status: live` is refused with `409 approval_required`: create the draft, request approval, and let a human activate it. Document, segment and list ids referenced by the definition must belong to the key's account (404).

Parameters for createFlowDraft
ParameterInTypeRequiredDescription
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
dry_runquerybooleanNoOn a billable write, return the credit cost and change nothing.
Request body
application/json

CreateFlowRequest

  • name string required
  • definition FlowDefinitionInput required — The trigger/audience/steps a client sends; the API adds the identity fields.
    • trigger FlowTrigger required
      • metric string required
      • where object
    • audience FlowAudience required
    • reentryDays integer
    • exitOn array of FlowEventRule
    • quietHours QuietHours
      • start integer required
      • end integer required
    • steps array of FlowStep required
  • status string
Responses
  • 200 Dry run result (`?dry_run=true`). (DryRun)
  • 201 The draft flow. (Flow)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 402 Not enough credits for this billable write. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 409 State conflict, concurrent idempotent request, or an approval is required / already granted. (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/flows' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13' \
  -H 'Content-Type: application/json' \
  --data '{"name":"string","definition":{"trigger":{"metric":"string"},"audience":"any","steps":[{"wait":{}}]}}'
GET/v1/flows/{id}

Get a flow with its definition

Parameters for getFlow
ParameterInTypeRequiredDescription
idpathstringYes
Responses
  • 200 The flow. (Flow)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/flows/your_id' \
  -H 'Authorization: Bearer mp_live_your_key'
POST/v1/flows/{id}/request-approval

Request a human go-live approval for a draft flow

Creates a pending `Approval` (`kind: flow_live`) through the core approval constructor and returns 202. The target id is `{flowId}@v{version}` and the snapshot hash covers the whole definition, exactly what the engine's `goLiveFlow()` checks. Repeating the call with unchanged content returns the pending approval; an expired row is marked `expired` and a fresh one is created. The API never flips a flow live. Core runs the pre-send checklist on every referenced email first; a failing check returns 422 with the failures in `error.details.checks`.

Parameters for requestFlowApproval
ParameterInTypeRequiredDescription
idpathstringYes
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Responses
  • 202 The pending approval. (Approval)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 409 State conflict, concurrent idempotent request, or an approval is required / already granted. (ErrorEnvelope)
  • 422 The pre-send checklist (PLAN §9 #12) blocked the approval request. `error.code` is `validation_failed`; `error.details.checks` lists each document it rendered and the failing checks, so a client can show the human exactly what to fix. A missing brand kit is reported the same way; a missing or invalid referenced document also returns `422 validation_failed`. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/flows/your_id/request-approval' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13'

Campaigns

3 operations

GET/v1/campaigns

List campaigns

Parameters for listCampaigns
ParameterInTypeRequiredDescription
limitqueryintegerNo
cursorquerystringNoOpaque `next_cursor` from the previous page.
Responses
  • 200 A page of campaigns. (CampaignList)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/campaigns?limit=50' \
  -H 'Authorization: Bearer mp_live_your_key'
POST/v1/campaigns

Create a campaign draft

Creates a `draft` only. Costs 5 credits; `?dry_run=true` returns the cost and changes nothing. `schedule_at` is refused with `409 approval_required`: create the draft, request approval, and let a human schedule/send it.

Parameters for createCampaignDraft
ParameterInTypeRequiredDescription
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
dry_runquerybooleanNoOn a billable write, return the credit cost and change nothing.
Request body
application/json

CreateCampaignRequest — `document_id` is required to create a campaign; it is optional in the schema only so `?dry_run=true` needs nothing but a name. The content fields are persisted so the core `campaign_snapshot` can hash them.

  • name string required
  • document_id string
  • subject string
  • segment_id string
  • preheader string
  • marketing boolean — Defaults to true.
  • coupon_rule_id string
  • variants array of CampaignVariant
  • test_percent integer — Defaults to 20.
  • decide_after_minutes integer — Defaults to 240.
  • schedule_at string (ISO-8601)
Responses
  • 200 Dry run result (`?dry_run=true`). (DryRun)
  • 201 The draft campaign. (Campaign)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 402 Not enough credits for this billable write. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 409 State conflict, concurrent idempotent request, or an approval is required / already granted. (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/campaigns' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13' \
  -H 'Content-Type: application/json' \
  --data '{"name":"string"}'
POST/v1/campaigns/{id}/request-approval

Request a human send approval for a draft campaign

Creates a pending `Approval` (`kind: campaign_send`) through `requestCampaignApproval` and returns 202. The snapshot hash covers the campaign content config plus the segment definition, exactly what `scheduleCampaign()` checks. Expired or stale rows are ignored. Core runs the pre-send checklist first; a failing check returns 422 with the failures in `error.details.checks`. The API never sends email.

Parameters for requestCampaignApproval
ParameterInTypeRequiredDescription
idpathstringYes
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Responses
  • 202 The pending approval. (Approval)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 409 State conflict, concurrent idempotent request, or an approval is required / already granted. (ErrorEnvelope)
  • 422 The pre-send checklist (PLAN §9 #12) blocked the approval request. `error.code` is `validation_failed`; `error.details.checks` lists each document it rendered and the failing checks, so a client can show the human exactly what to fix. A missing brand kit is reported the same way; a missing or invalid referenced document also returns `422 validation_failed`. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/campaigns/your_id/request-approval' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13'

Results

1 operation

GET/v1/results/summary

Revenue, sends, opens, clicks and bounces for a date range

Defaults to the last 30 days. The range is capped at 366 days. Heavy endpoint: consumes 5 rate-limit tokens. Uses click-based attribution (opens are reported but never used for revenue).

Parameters for getResultsSummary
ParameterInTypeRequiredDescription
fromquerystring (ISO-8601)No
toquerystring (ISO-8601)No
Responses
  • 200 The summary. (ResultsSummary)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/results/summary' \
  -H 'Authorization: Bearer mp_live_your_key'

Account

2 operations

GET/v1/account

The key's account, plan and API allowance

Responses
  • 200 The account. (Account)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/account' \
  -H 'Authorization: Bearer mp_live_your_key'
GET/v1/credits

The account's credit balance

Responses
  • 200 The balance. (Credits)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/credits' \
  -H 'Authorization: Bearer mp_live_your_key'

Webhooks

9 operations

GET/v1/webhooks

List webhook endpoints

Every endpoint registered for the key's account. Reads use the `webhooks:read` scope. Signing secrets are never returned; they are shown once at creation or rotation.

Responses
  • 200 The account's endpoints. (WebhookList)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/webhooks' \
  -H 'Authorization: Bearer mp_live_your_key'
POST/v1/webhooks

Register a webhook endpoint

The URL must be https, have no embedded credentials and resolve only to public addresses (the SSRF check runs again on every delivery). Events come from the fixed catalogue. An account can have at most 20 endpoints. The response includes the signing secret exactly once; store it before leaving the page. Requires `webhooks:write`.

Parameters for createWebhook
ParameterInTypeRequiredDescription
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Request body
application/json

WebhookCreateRequest

  • url string required
  • events array of WebhookEventType required
  • description string | null
Responses
  • 201 Created. `secret` is shown only in this response. (WebhookCreateResponse)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 409 State conflict, concurrent idempotent request, or an approval is required / already granted. (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/webhooks' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13' \
  -H 'Content-Type: application/json' \
  --data '{"url":"string","events":["profile.subscribed"]}'
GET/v1/webhooks/{id}

Get a webhook endpoint

Parameters for getWebhook
ParameterInTypeRequiredDescription
idpathstringYes
Responses
  • 200 The endpoint. (WebhookResponse)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/webhooks/your_id' \
  -H 'Authorization: Bearer mp_live_your_key'
PATCH/v1/webhooks/{id}

Update a webhook endpoint

Change the URL (re-checked with the https + SSRF guard), the subscribed events or whether the endpoint is enabled. Re-enabling clears the failure streak. Requires `webhooks:write`.

Parameters for updateWebhook
ParameterInTypeRequiredDescription
idpathstringYes
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Request body
application/json

WebhookUpdateRequest

  • url string
  • events array of WebhookEventType
  • enabled boolean
Responses
  • 200 The updated endpoint. (WebhookResponse)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 422 Zod validation failed; `error.fields` maps field paths to messages. (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X PATCH 'https://api.mailprompt.ai/v1/webhooks/your_id' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13' \
  -H 'Content-Type: application/json' \
  --data '{"url":"string"}'
DELETE/v1/webhooks/{id}

Delete a webhook endpoint

Stops future deliveries and removes the endpoint's delivery log. Requires `webhooks:write`.

Parameters for deleteWebhook
ParameterInTypeRequiredDescription
idpathstringYes
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Responses
  • 204 Deleted. (none)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X DELETE 'https://api.mailprompt.ai/v1/webhooks/your_id' \
  -H 'Authorization: Bearer mp_live_your_key'
GET/v1/webhooks/{id}/deliveries

List the last 30 days of deliveries for an endpoint

Cursor-paginated, newest first. Each row reports the event, status, HTTP status, attempt number, duration and time. Rows older than 30 days are purged. Requires `webhooks:read`.

Parameters for listWebhookDeliveries
ParameterInTypeRequiredDescription
idpathstringYes
limitqueryintegerNo
cursorquerystringNoOpaque `next_cursor` from the previous page.
Responses
  • 200 A page of deliveries. (WebhookDeliveryList)
  • 400 Malformed request, invalid cursor, oversized body or an API key passed in the query string. (ErrorEnvelope)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X GET 'https://api.mailprompt.ai/v1/webhooks/your_id/deliveries?limit=50' \
  -H 'Authorization: Bearer mp_live_your_key'
POST/v1/webhooks/{id}/rotate-secret

Rotate a webhook signing secret

Replaces the secret and returns the new value exactly once. Deliveries already queued with the old secret will fail verification; update the receiver promptly. Requires `webhooks:write`.

Parameters for rotateWebhookSecret
ParameterInTypeRequiredDescription
idpathstringYes
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Responses
  • 200 The new secret and the updated endpoint. (WebhookSecretResponse)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/webhooks/your_id/rotate-secret' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13'
POST/v1/webhooks/{id}/test

Queue a signed webhook.test event

Queues one `webhook.test` delivery for this endpoint. It is signed with the endpoint secret and sent by the delivery worker like any other event; `webhook.test` is not subscribable. Requires `webhooks:write`.

Parameters for testWebhook
ParameterInTypeRequiredDescription
idpathstringYes
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Responses
  • 202 The test event is queued. (WebhookTestResponse)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/webhooks/your_id/test' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13'
POST/v1/webhooks/deliveries/{id}/redeliver

Redeliver a logged delivery

Re-queues the same event with the same event id and payload, so a receiver can deduplicate it against the original. The retry count starts again. Requires `webhooks:write`.

Parameters for redeliverWebhookDelivery
ParameterInTypeRequiredDescription
idpathstringYes
Idempotency-KeyheaderstringNoUp to 100 characters. The first response is stored for 24 hours and replayed for the same method, path and body; a different body returns `409 idempotency_mismatch`; a concurrent duplicate returns `409 conflict`.
Responses
  • 202 The delivery is queued again. (WebhookDeliveryResponse)
  • 401 Missing, malformed, unknown, revoked or expired API key. (ErrorEnvelope)
  • 403 Missing scope, IP not allowed, unknown/read-only plan. (ErrorEnvelope)
  • 404 The resource does not exist in this account (cross-store ids are 404). (ErrorEnvelope)
  • 429 Rate limit or monthly quota exceeded; see `Retry-After`. (ErrorEnvelope)
  • 500 Unexpected error. No stack traces or internal messages are returned. (ErrorEnvelope)
Example
curl -X POST 'https://api.mailprompt.ai/v1/webhooks/deliveries/your_id/redeliver' \
  -H 'Authorization: Bearer mp_live_your_key' \
  -H 'Idempotency-Key: 1f0c9d2e-4b7a-4c3e-9d61-2a8b5c0e7f13'