Campaigns

Export project campaign recipients

Required scope: campaigns:read

Returns recipients as CSV in queue order. Unfiltered exports page up to 1,000 recipients per request. Each page starts with a header row. When more recipients match, the Polymorfa-Next-Cursor response header carries the cursor for the next page; it is absent on the last page. Each page is read when it is requested, so a recipient appears once, with the outcome it had when its page was read. A filtered export is one atomic page of up to 1,000 recipients; larger filtered results return 409, so changing statuses cannot silently omit matches between pages. The export contains outcomes and failureReason codes only, never message content or template variables.

GET

messaging

projects

{projectSlug}

campaigns

{id}

recipients

export

Export project campaign recipients

curl --request GET \
  --url https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/recipients/export \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/recipients/export', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/recipients/export"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/recipients/export"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<string>

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}

{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}

{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}

Authorizations

Authorization

string

header

required

Polymorfa organization key (pmfa_ prefix), project token (pmfa_pt_ prefix) where supported, or short-lived client token (pmfa_ct_ prefix). Organization and project keys may be personal or service-account owned and enforce selected action scopes. Organization keys cover the team and its projects; project tokens stay inside one project. Client tokens stay inside their live project and session and enforce their client rules.

Path Parameters

projectSlug

string

required

Specifies project slug for this path parameter.

string

required

Identifier for this resource.

Query Parameters

status

enum<string>

Current status of this resource or operation.

Allowed values

Value	Meaning
`queued`	Queued.
`sending`	Sending.
`sent`	Sent.
`delivered`	Delivered.
`read`	Read.
`failed`	Failed.
`skipped`	Skipped.

Available options:

queued,

sending,

sent,

delivered,

read,

failed,

skipped

reason

enum<string>

Reason for the reported state or outcome.

Allowed values

Value	Meaning
`opted_out`	Opted out.
`cold_held`	Cold held.
`campaign_cancelled`	Campaign cancelled.
`invalid_recipient`	Invalid recipient.
`session_not_connected`	Session not connected.
`ack_timeout`	Ack timeout.
`blocked_by_safety`	Blocked by safety.
`send_failed`	Send failed.
`missing_variable`	Missing variable.
`other`	Other.
Only recipients whose `failureReason` is this code.

Available options:

opted_out,

cold_held,

campaign_cancelled,

invalid_recipient,

session_not_connected,

ack_timeout,

blocked_by_safety,

send_failed,

missing_variable,

other

cursor

string

Specifies cursor for this query parameter.

Value constraints

Constraint	Accepted input
String length	`1` through `256` characters
The `Polymorfa-Next-Cursor` value from the previous unfiltered page. Filtered exports cannot be paged.

Required string length: 1 - 256

limit

integer

Specifies limit for this query parameter.

Value constraints

Constraint	Accepted input
Numeric value	`1` through `1000` (inclusive)
Recipients per unfiltered page, up to 1,000. Filtered exports require 1,000. Default 1,000.

Required range: 1 <= x <= 1000

Response

One page of recipients.

Header row, then one row per recipient. Columns: recipientId, phone, status, failureReason, attempts, variantKey, queuedAt, sentAt, deliveredAt, readAt, failedAt, respondedAt, followUpStatus, followUpAnchor, followUpDueAt, followUpExpiresAt, followUpSentAt, followUpReadAt, followUpRepliedAt, followUpReason, followUpCommandId. Times are ISO 8601 in UTC. Empty fields are null. Text that begins with =, +, -, @, tab or carriage return is prefixed with an apostrophe, including phone numbers in international format. Machine readers should remove that leading apostrophe from phone cells.

Export project campaign recipients

curl --request GET \
  --url https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/recipients/export \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/recipients/export', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/recipients/export"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/recipients/export"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<string>

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}

{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}

{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}

Overview

Messaging API

Platform API

Graph API

Webhook events

Export project campaign recipients

Authorizations

Path Parameters

Query Parameters

Response