Resubscribe Recipient
curl --request POST \
--url https://api.example.com/email/lists/{list_id}/recipients/resubscribe \
--header 'Content-Type: application/json' \
--data '
{
"external_id": "<string>",
"email": "<string>",
"name": "<string>",
"attributes": {},
"consent": {
"source": "<string>",
"recorded_at": "<string>",
"ip": "<string>",
"user_agent": "<string>"
}
}
'import requests
url = "https://api.example.com/email/lists/{list_id}/recipients/resubscribe"
payload = {
"external_id": "<string>",
"email": "<string>",
"name": "<string>",
"attributes": {},
"consent": {
"source": "<string>",
"recorded_at": "<string>",
"ip": "<string>",
"user_agent": "<string>"
}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
external_id: '<string>',
email: '<string>',
name: '<string>',
attributes: {},
consent: {
source: '<string>',
recorded_at: '<string>',
ip: '<string>',
user_agent: '<string>'
}
})
};
fetch('https://api.example.com/email/lists/{list_id}/recipients/resubscribe', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/email/lists/{list_id}/recipients/resubscribe",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'external_id' => '<string>',
'email' => '<string>',
'name' => '<string>',
'attributes' => [
],
'consent' => [
'source' => '<string>',
'recorded_at' => '<string>',
'ip' => '<string>',
'user_agent' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/email/lists/{list_id}/recipients/resubscribe"
payload := strings.NewReader("{\n \"external_id\": \"<string>\",\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"attributes\": {},\n \"consent\": {\n \"source\": \"<string>\",\n \"recorded_at\": \"<string>\",\n \"ip\": \"<string>\",\n \"user_agent\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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))
}HttpResponse<String> response = Unirest.post("https://api.example.com/email/lists/{list_id}/recipients/resubscribe")
.header("Content-Type", "application/json")
.body("{\n \"external_id\": \"<string>\",\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"attributes\": {},\n \"consent\": {\n \"source\": \"<string>\",\n \"recorded_at\": \"<string>\",\n \"ip\": \"<string>\",\n \"user_agent\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/email/lists/{list_id}/recipients/resubscribe")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_id\": \"<string>\",\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"attributes\": {},\n \"consent\": {\n \"source\": \"<string>\",\n \"recorded_at\": \"<string>\",\n \"ip\": \"<string>\",\n \"user_agent\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"status": "<string>",
"recipient": {
"via": "<string>",
"source": "<string>",
"recorded_at": "<string>",
"ip": "<string>",
"user_agent": "<string>"
}
}Mailing Lists
Resubscribe Recipient
Record an explicit opt-in the person made in your app — the only call that undoes an unsubscribe
POST
/
email
/
lists
/
{list_id}
/
recipients
/
resubscribe
Resubscribe Recipient
curl --request POST \
--url https://api.example.com/email/lists/{list_id}/recipients/resubscribe \
--header 'Content-Type: application/json' \
--data '
{
"external_id": "<string>",
"email": "<string>",
"name": "<string>",
"attributes": {},
"consent": {
"source": "<string>",
"recorded_at": "<string>",
"ip": "<string>",
"user_agent": "<string>"
}
}
'import requests
url = "https://api.example.com/email/lists/{list_id}/recipients/resubscribe"
payload = {
"external_id": "<string>",
"email": "<string>",
"name": "<string>",
"attributes": {},
"consent": {
"source": "<string>",
"recorded_at": "<string>",
"ip": "<string>",
"user_agent": "<string>"
}
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
external_id: '<string>',
email: '<string>',
name: '<string>',
attributes: {},
consent: {
source: '<string>',
recorded_at: '<string>',
ip: '<string>',
user_agent: '<string>'
}
})
};
fetch('https://api.example.com/email/lists/{list_id}/recipients/resubscribe', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/email/lists/{list_id}/recipients/resubscribe",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'external_id' => '<string>',
'email' => '<string>',
'name' => '<string>',
'attributes' => [
],
'consent' => [
'source' => '<string>',
'recorded_at' => '<string>',
'ip' => '<string>',
'user_agent' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/email/lists/{list_id}/recipients/resubscribe"
payload := strings.NewReader("{\n \"external_id\": \"<string>\",\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"attributes\": {},\n \"consent\": {\n \"source\": \"<string>\",\n \"recorded_at\": \"<string>\",\n \"ip\": \"<string>\",\n \"user_agent\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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))
}HttpResponse<String> response = Unirest.post("https://api.example.com/email/lists/{list_id}/recipients/resubscribe")
.header("Content-Type", "application/json")
.body("{\n \"external_id\": \"<string>\",\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"attributes\": {},\n \"consent\": {\n \"source\": \"<string>\",\n \"recorded_at\": \"<string>\",\n \"ip\": \"<string>\",\n \"user_agent\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/email/lists/{list_id}/recipients/resubscribe")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_id\": \"<string>\",\n \"email\": \"<string>\",\n \"name\": \"<string>\",\n \"attributes\": {},\n \"consent\": {\n \"source\": \"<string>\",\n \"recorded_at\": \"<string>\",\n \"ip\": \"<string>\",\n \"user_agent\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"status": "<string>",
"recipient": {
"via": "<string>",
"source": "<string>",
"recorded_at": "<string>",
"ip": "<string>",
"user_agent": "<string>"
}
}When someone clicks the unsubscribe link in an email, Shipstar marks them
Matching is by
unsubscribed and no upsert, add or restore ever changes that row again — a bulk sync must never be able to undo an opt-out by accident. Two things can: the person clicking Resubscribe on the unsubscribe confirmation page, and this call, which records an opt-in the signed-in person made in your product (turning a “Product updates” switch back on, re-ticking a newsletter box).
It is deliberately different from an upsert: one recipient per call, and a consent block that says where and when the person opted in. That block is stored on the recipient as its consent record and returned on every recipient read, so you can show your auditors who opted in, how and when.
What happens, by the recipient’s current status:
| Status before | Result | status in the response | Webhook |
|---|---|---|---|
unsubscribed | Active again | resubscribed | mailing_list.resubscribed |
| Not on the list, or erased earlier | Added as active; a hashed opt-out left by an erase is cleared | added | mailing_list.resubscribed if a hash was cleared |
removed (you took them off) | Active again | reactivated | — |
active | Nothing to change; name, attributes and the consent record are still applied | already_active | — |
external_id first, then by email. Sending a new email for an existing external_id changes the address in place (and rotates that person’s unsubscribe link). Activating a recipient counts against the list’s plan cap exactly like an upsert.
Call this from the code path where the person flips the switch, not from your nightly sync. Your sync should keep using upsert and treat
skipped_unsubscribed as the person’s final word until they opt in again — and should subscribe to the mailing_list.resubscribed webhook so an opt-in made on Shipstar’s confirmation page flips your own flag too. See Hearing about unsubscribes and resubscribes.Authentication
This endpoint requires an API token passed as a Bearer token in theAuthorization header.
Authorization: Bearer YOUR_API_TOKEN
Path Parameters
Body
At least one ofemail and external_id. Without an email, an unknown external_id is a 404 — there is nothing to add.
Email address (case-insensitive). Required to add someone who is not on the list; changes the address of an
external_id-keyed recipient.Where and when the person opted in on your side.
Request
curl -X POST "https://api.shipstar.ai/api/v1/email/lists/a1b2c3d4-e5f6-7890-abcd-ef1234567890/recipients/resubscribe" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"external_id": "usr_42",
"email": "sam@example.com",
"consent": {
"source": "Product updates switch, account settings",
"recorded_at": "2026-11-13T17:06:12Z",
"ip": "203.0.113.5",
"user_agent": "Mozilla/5.0"
}
}'
const listId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const response = await fetch(`https://api.shipstar.ai/api/v1/email/lists/${listId}/recipients/resubscribe`, {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
external_id: 'usr_42',
email: 'sam@example.com',
consent: {
source: 'Product updates switch, account settings',
recorded_at: new Date().toISOString(),
ip: request.ip,
user_agent: request.headers['user-agent']
}
})
});
const result = await response.json();
import requests
from datetime import datetime, timezone
list_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
response = requests.post(
f'https://api.shipstar.ai/api/v1/email/lists/{list_id}/recipients/resubscribe',
headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
json={
'external_id': 'usr_42',
'email': 'sam@example.com',
'consent': {
'source': 'Product updates switch, account settings',
'recorded_at': datetime.now(timezone.utc).isoformat(),
'ip': request.client.host,
'user_agent': request.headers.get('user-agent'),
},
},
)
result = response.json()
Response
The recipient as List Recipients returns it, now
active, including the consent record just written:Show consent
Show consent
200
{
"status": "resubscribed",
"recipient": {
"id": "5b2f8c1e-4d3a-4f6b-9e2d-1a2b3c4d5e6f",
"email": "sam@example.com",
"name": "Sam Lee",
"external_id": "usr_42",
"attributes": {"plan": "pro"},
"status": "active",
"status_changed_at": "2026-11-13T17:06:13Z",
"consent": {
"via": "api",
"source": "Product updates switch, account settings",
"recorded_at": "2026-11-13T17:06:12Z",
"ip": "203.0.113.5",
"user_agent": "Mozilla/5.0"
},
"is_active": true,
"created_at": "2026-09-01T08:00:00Z",
"updated_at": "2026-11-13T17:06:13Z"
}
}
Errors
Error bodies carry a stablecode next to the human-readable detail.
| Status | code | Meaning |
|---|---|---|
| 400 | recipient_cap_exceeded | Activating this recipient would exceed the list’s plan cap; the body also has active_count, limit and incoming |
| 401 | — | Invalid or expired API token |
| 404 | — | Mailing list not found in the token’s project |
| 404 | recipient_not_found | external_id only, and nobody on the list has it |
| 409 | external_id_conflict | The email belongs to a recipient with a different external_id |
| 409 | email_conflict | The new email is already another recipient’s address on this list |
| 422 | invalid_email | The email address failed validation |
| 422 | — | Invalid request body (no identifier, missing consent.source, oversize attributes) |
Rate Limits
This endpoint is limited to 30 requests per minute per IP.Was this page helpful?