Update a message of a campaign
curl --request PATCH \
--url https://api.folk.app/v1/campaigns/{campaignId}/messages/{messageId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"subject": "Congrats on the round, Ana",
"body": "<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>"
}
'const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
subject: 'Congrats on the round, Ana',
body: JSON.stringify('<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>')
})
};
fetch('https://api.folk.app/v1/campaigns/{campaignId}/messages/{messageId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/campaigns/{campaignId}/messages/{messageId}"
payload = {
"subject": "Congrats on the round, Ana",
"body": "<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)require 'uri'
require 'net/http'
url = URI("https://api.folk.app/v1/campaigns/{campaignId}/messages/{messageId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"subject\": \"Congrats on the round, Ana\",\n \"body\": \"<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>\"\n}"
response = http.request(request)
puts response.read_bodypackage main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.folk.app/v1/campaigns/{campaignId}/messages/{messageId}"
payload := strings.NewReader("{\n \"subject\": \"Congrats on the round, Ana\",\n \"body\": \"<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>\"\n}")
req, _ := http.NewRequest("PATCH", 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))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.folk.app/v1/campaigns/{campaignId}/messages/{messageId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'subject' => 'Congrats on the round, Ana',
'body' => '<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"data": {
"id": "msg_1d2c3b4a-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"campaignId": "cmp_9b2f1c1e-2b8a-4d1e-8f5a-3c2d1e0f9a8b",
"step": 1,
"recipient": {
"contact": {
"id": "per_55175e81-9a52-4ac3-930e-82792c23499b",
"entityType": "person"
},
"name": "John Doe",
"email": "john.doe@example.com"
},
"sender": {
"id": "snd_4c3b2a19-8f7e-4d6c-9b5a-1e2f3d4c5b6a",
"email": "john.doe@example.com",
"displayName": "John Doe"
},
"subject": "Quick question, John",
"body": "<p>Hi John,</p><p>{{signature}}</p>",
"cc": [],
"bcc": [],
"status": "draft",
"notSentReason": null,
"unsubscribed": false
}
}{
"error": {
"code": "INVALID_REQUEST",
"message": "The request was invalid.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#bad-request",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "No valid API key provided.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#unauthorized",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "FORBIDDEN",
"message": "The API key doesn’t have permissions to perform the request.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#forbidden",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#not-found",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
"message": "A request with the same Idempotency-Key is still being processed. Retry once it has completed.",
"documentationUrl": "https://developer.folk.app/api-reference/idempotency#errors",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "UNPROCESSABLE_ENTITY",
"message": "Invalid query parameters",
"documentationUrl": "https://developer.folk.app/api-reference/errors#unprocessable-entity",
"details": {
"issues": [
{
"code": "too_small",
"minimum": 1,
"type": "number",
"inclusive": true,
"exact": false,
"message": "Number must be greater than or equal to 1",
"path": [
"limit"
]
}
]
},
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "TOO_MANY_REQUESTS",
"message": "You have exceeded your rate limit.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z",
"details": {
"policy": "burst",
"limit": 20,
"remaining": 0,
"windowSeconds": 2,
"retryAfter": "2025-10-01T12:00:02.000Z",
"policies": [
{
"policy": "default",
"limit": 600,
"remaining": 412,
"windowSeconds": 60,
"retryAfter": "2025-10-01T12:01:00.000Z"
},
{
"policy": "burst",
"limit": 20,
"remaining": 0,
"windowSeconds": 2,
"retryAfter": "2025-10-01T12:00:02.000Z"
}
]
}
}
}{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "An internal server error occurred.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#internal-server-error",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "The service is currently unavailable.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#service-unavailable",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}Campaigns
(Beta) Update a message of a campaign
Edit a message of a campaign in review, as the app does: only the fields given change. The content of a message is final, so {{variables}} are rejected, apart from {{signature}} and {{unsubscribeLink}}. A body read back ends with <p>{{signature}}</p> when signed: keep it to keep the message’s signature as it is, edited or not; a body without it has no signature. {{unsubscribeLink}} links to the unsubscribe page of that message.
A blank subject or body is rejected. A follow-up sent in the same thread takes no subject; a new subject on a message of the first step carries to the follow-ups of its thread. Edits are lost if the campaign goes back to draft, as its messages are generated again on the next review.
This endpoint is currently in open beta. The API surface may change as we iterate based on feedback.
PATCH
/
v1
/
campaigns
/
{campaignId}
/
messages
/
{messageId}
Update a message of a campaign
curl --request PATCH \
--url https://api.folk.app/v1/campaigns/{campaignId}/messages/{messageId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"subject": "Congrats on the round, Ana",
"body": "<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>"
}
'const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
subject: 'Congrats on the round, Ana',
body: JSON.stringify('<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>')
})
};
fetch('https://api.folk.app/v1/campaigns/{campaignId}/messages/{messageId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/campaigns/{campaignId}/messages/{messageId}"
payload = {
"subject": "Congrats on the round, Ana",
"body": "<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)require 'uri'
require 'net/http'
url = URI("https://api.folk.app/v1/campaigns/{campaignId}/messages/{messageId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"subject\": \"Congrats on the round, Ana\",\n \"body\": \"<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>\"\n}"
response = http.request(request)
puts response.read_bodypackage main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.folk.app/v1/campaigns/{campaignId}/messages/{messageId}"
payload := strings.NewReader("{\n \"subject\": \"Congrats on the round, Ana\",\n \"body\": \"<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>\"\n}")
req, _ := http.NewRequest("PATCH", 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))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.folk.app/v1/campaigns/{campaignId}/messages/{messageId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'subject' => 'Congrats on the round, Ana',
'body' => '<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"data": {
"id": "msg_1d2c3b4a-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"campaignId": "cmp_9b2f1c1e-2b8a-4d1e-8f5a-3c2d1e0f9a8b",
"step": 1,
"recipient": {
"contact": {
"id": "per_55175e81-9a52-4ac3-930e-82792c23499b",
"entityType": "person"
},
"name": "John Doe",
"email": "john.doe@example.com"
},
"sender": {
"id": "snd_4c3b2a19-8f7e-4d6c-9b5a-1e2f3d4c5b6a",
"email": "john.doe@example.com",
"displayName": "John Doe"
},
"subject": "Quick question, John",
"body": "<p>Hi John,</p><p>{{signature}}</p>",
"cc": [],
"bcc": [],
"status": "draft",
"notSentReason": null,
"unsubscribed": false
}
}{
"error": {
"code": "INVALID_REQUEST",
"message": "The request was invalid.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#bad-request",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "No valid API key provided.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#unauthorized",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "FORBIDDEN",
"message": "The API key doesn’t have permissions to perform the request.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#forbidden",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#not-found",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
"message": "A request with the same Idempotency-Key is still being processed. Retry once it has completed.",
"documentationUrl": "https://developer.folk.app/api-reference/idempotency#errors",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "UNPROCESSABLE_ENTITY",
"message": "Invalid query parameters",
"documentationUrl": "https://developer.folk.app/api-reference/errors#unprocessable-entity",
"details": {
"issues": [
{
"code": "too_small",
"minimum": 1,
"type": "number",
"inclusive": true,
"exact": false,
"message": "Number must be greater than or equal to 1",
"path": [
"limit"
]
}
]
},
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "TOO_MANY_REQUESTS",
"message": "You have exceeded your rate limit.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z",
"details": {
"policy": "burst",
"limit": 20,
"remaining": 0,
"windowSeconds": 2,
"retryAfter": "2025-10-01T12:00:02.000Z",
"policies": [
{
"policy": "default",
"limit": 600,
"remaining": 412,
"windowSeconds": 60,
"retryAfter": "2025-10-01T12:01:00.000Z"
},
{
"policy": "burst",
"limit": 20,
"remaining": 0,
"windowSeconds": 2,
"retryAfter": "2025-10-01T12:00:02.000Z"
}
]
}
}
}{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "An internal server error occurred.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#internal-server-error",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}{
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "The service is currently unavailable.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#service-unavailable",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z"
}
}Authorizations
API key for authentication
Headers
A unique key, such as a UUID, that makes retrying this request safe: a retry with the same key and body returns the original response without running the operation again. Keys are kept for 24 hours after the request completes.
Maximum string length:
255Example:
"8e03978e-40d5-43e8-bc93-6894a57f9324"
Path Parameters
The ID of the campaign.
Required string length:
40The ID of the message.
Required string length:
40Body
application/json
The final content of one message: only the fields given change.
The subject of the message, in plain text. A follow-up sent in the same thread has the first step's subject, so it takes none. Leave it out to keep the current one.
Maximum string length:
1000Example:
"Congrats on the round, Ana"
The body of the message, in HTML (or plain text with bodyFormat: "text"). Its content is final: {{variables}} are rejected, apart from {{signature}} and {{unsubscribeLink}}. End it with <p>{{signature}}</p> to keep the message's signature as it is, edited or not; a body without it has no signature. An unsubscribe link, for SendGrid senders only, is <a href="{{unsubscribeLink}}">. Leave it out to keep the current body.
Maximum string length:
200000Example:
"<p>Hi Ana, congrats on the round!</p><p>{{signature}}</p>"
How body is written. html (default) is read as HTML. text is plain text: a blank line starts a new paragraph, each further blank line adds an empty paragraph, a single newline is a line break, and < and & are literal characters. Bodies always read back as HTML.
Available options:
html, text Example:
"html"
Email addresses copied on the message. Leave it out to keep the current ones. At most 5 distinct addresses; duplicates are removed.
Maximum array length:
50Maximum string length:
254Example:
["jane.doe@example.com"]
Email addresses blind-copied on the message. Leave it out to keep the current ones. At most 5 distinct addresses; duplicates are removed.
Maximum array length:
50Maximum string length:
254Example:
["jane.doe@example.com"]
Response
The message, as updated.
A message of a campaign: the email of one step for one recipient, with the variables of the step filled in for that recipient. There is one message per recipient and per step.
Show child attributes
Show child attributes
Example:
{
"id": "msg_1d2c3b4a-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"campaignId": "cmp_9b2f1c1e-2b8a-4d1e-8f5a-3c2d1e0f9a8b",
"step": 1,
"recipient": {
"contact": {
"id": "per_55175e81-9a52-4ac3-930e-82792c23499b",
"entityType": "person"
},
"name": "John Doe",
"email": "john.doe@example.com"
},
"sender": {
"id": "snd_4c3b2a19-8f7e-4d6c-9b5a-1e2f3d4c5b6a",
"email": "john.doe@example.com",
"displayName": "John Doe"
},
"subject": "Quick question, John",
"body": "<p>Hi John,</p><p>{{signature}}</p>",
"cc": [],
"bcc": [],
"status": "draft",
"notSentReason": null,
"unsubscribed": false
}
Example:
["This field is deprecated"]