Campaigns

Send project campaign test

Required scopes (all): campaigns:manage · campaigns:read

Requires campaigns:manage and campaigns:read because the test can use stored recipient samples. Sends one copy of a draft campaign’s content to a seed recipient, through the same rendering, sending, and BanSafe checks as a launched campaign. The seed recipient must be a number connected to your team. A test is not a campaign recipient and is not counted in the campaign’s statistics or webhooks. A team can send 20 tests an hour, and at most 5 an hour to one seed recipient.

POST

messaging

projects

{projectSlug}

campaigns

{id}

test-send

Send project campaign test

curl --request POST \
  --url https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/test-send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "to": "+5511999990000"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a', to: '+5511999990000'})
};

fetch('https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/test-send', 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}/test-send"

payload = {
    "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "to": "+5511999990000"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

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

func main() {

	url := "https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/test-send"

	payload := strings.NewReader("{\n  \"sessionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"to\": \"+5511999990000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

{
  "success": true,
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "campaignId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "sent",
    "from": {
      "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "phone": "<string>"
    },
    "to": "<string>",
    "messageId": "<string>",
    "variables": {},
    "createdAt": 123
  }
}

{
  "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": "campaigns_not_entitled",
    "message": "This number’s plan does not include Campaigns.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#campaigns-not-entitled"
}

{
  "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": "invalid_request_error",
    "code": "campaign_variables_missing",
    "message": "A recipient has no value and no fallback for a variable in the campaign content.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#campaign-variables-missing"
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#rate-limit-exceeded"
}

{
  "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"
}

{
  "error": {
    "type": "upstream_error",
    "code": "upstream_failure",
    "message": "The messaging provider could not complete the request.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#upstream-failure"
}

{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}

{
  "error": {
    "type": "api_error",
    "code": "result_unknown",
    "message": "The result was not obtained before the deadline. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#result-unknown"
}

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.

Headers

Idempotency-Key

string

Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, Polymorfa-Version, and request never runs the write again: it returns 409 idempotency_completed when the original succeeded, or the original server error, with Idempotent-Replayed: true. Reusing the key for a different request returns 409 idempotency_conflict; a retry while the original is still running returns 409 idempotency_in_progress, and a retry after an unrecorded outcome returns 409 idempotency_outcome_unknown.

Value constraints

Constraint	Accepted input
String length	`1` through `255` characters

Required string length: 1 - 255

Path Parameters

projectSlug

string

required

Specifies project slug for this path parameter.

string

required

Identifier for this resource.

Body

application/json

sessionId

string<uuid>

required

The number to send the test from. It must be connected, on a plan that includes Campaigns, and, when the campaign selects numbers, one of them.

Value constraints

Constraint	Accepted input
Format	`uuid`

string

required

The seed recipient in international format. It must be the phone of a number connected to your team.

Value constraints

Constraint	Accepted input
String length	`1` through `32` characters

Required string length: 1 - 32

Example:

"+5511999990000"

sampleRecipientId

string<uuid>

A recipient of this campaign whose variables fill the content. Without it and without variables, the campaign's first recipient, or its audience's first member, is the sample.

Value constraints

Constraint	Accepted input
Format	`uuid`

variables

object

Variable values for the test, at most 50. They override the sample recipient's values; without sampleRecipientId, only these values are used.

Value constraints

Constraint	Accepted input
Object size	At most `50` properties

Show child attributes

Response

success

enum<boolean>

required

Whether the request succeeded.

Allowed values

Value	Meaning
`true`	True.

Available options:

true

data

object

required

Structured data carried by this object.

Show child attributes

Send project campaign test

curl --request POST \
  --url https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/test-send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "to": "+5511999990000"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a', to: '+5511999990000'})
};

fetch('https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/test-send', 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}/test-send"

payload = {
    "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "to": "+5511999990000"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

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

func main() {

	url := "https://api.polymorfa.com/messaging/projects/{projectSlug}/campaigns/{id}/test-send"

	payload := strings.NewReader("{\n  \"sessionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"to\": \"+5511999990000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

{
  "success": true,
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "campaignId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "sent",
    "from": {
      "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "phone": "<string>"
    },
    "to": "<string>",
    "messageId": "<string>",
    "variables": {},
    "createdAt": 123
  }
}

{
  "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": "campaigns_not_entitled",
    "message": "This number’s plan does not include Campaigns.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#campaigns-not-entitled"
}

{
  "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": "invalid_request_error",
    "code": "campaign_variables_missing",
    "message": "A recipient has no value and no fallback for a variable in the campaign content.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#campaign-variables-missing"
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#rate-limit-exceeded"
}

{
  "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"
}

{
  "error": {
    "type": "upstream_error",
    "code": "upstream_failure",
    "message": "The messaging provider could not complete the request.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#upstream-failure"
}

{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}

{
  "error": {
    "type": "api_error",
    "code": "result_unknown",
    "message": "The result was not obtained before the deadline. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#result-unknown"
}

Overview

Messaging API

Platform API

Graph API

Webhook events

Send project campaign test

Authorizations

Headers

Path Parameters

Body

Response