Skip to content

Subscribe or unsubscribe contacts

POST
/organizations/{organizationId}/mailing-lists/{mailingListId}/contacts
curl --request POST \
--url https://api.sendwing.app/api/organizations/example/mailing-lists/example/contacts \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "subscribe": [ "example" ], "unsubscribe": [ "example" ] }'

Subscribes contacts to the list and unsubscribes them, by ID, up to 1000 at a time. Unsubscribing keeps the contact on the list as unsubscribed. A contact already in the state you ask for is left alone. Subscribing is refused, and listed in refused with the reason, for a contact whose own status isn’t subscribed and for one who unsubscribed from this list themselves: only they can subscribe again.

organizationId
required
string

The workspace, like org_…. An OAuth access token works in the one the member picked when connecting, which GET /me returns.

mailingListId
required
string

Like list_…

Media typeapplication/json
object
subscribe

Contacts to subscribe, by ID

Array<string>
<= 1000 items
unsubscribe

Contacts to unsubscribe, by ID

Array<string>
<= 1000 items

Example generated

{
"subscribe": [
"example"
],
"unsubscribe": [
"example"
]
}

What changed

Media typeapplication/json
object
subscribed
required

Contacts subscribed by this request

integer
>= -9007199254740991 <= 9007199254740991
unsubscribed
required

Contacts unsubscribed by this request

integer
>= -9007199254740991 <= 9007199254740991
refused
required

Contacts that can’t be subscribed, and why

Array<object>
object
id
required
string
reason
required
string
notFound
required

IDs that aren’t contacts in this workspace

Array<string>

Example generated

{
"subscribed": 1,
"unsubscribed": 1,
"refused": [
{
"id": "example",
"reason": "example"
}
],
"notFound": [
"example"
]
}

The request isn’t valid; issues lists each problem

Media typeapplication/json
object
error
required

What went wrong, in words you can show people

string
issues

For a 400: each invalid field, by its path in the request, like events.0.name

Array<object>
object
path
required
string
message
required
string
requestId

For a 5xx: quote it when contacting support

string

Example generated

{
"error": "example",
"issues": [
{
"path": "example",
"message": "example"
}
],
"requestId": "example"
}

The API key or access token is missing, invalid or expired

Media typeapplication/json
object
error
required

What went wrong, in words you can show people

string
issues

For a 400: each invalid field, by its path in the request, like events.0.name

Array<object>
object
path
required
string
message
required
string
requestId

For a 5xx: quote it when contacting support

string

Example generated

{
"error": "example",
"issues": [
{
"path": "example",
"message": "example"
}
],
"requestId": "example"
}

The API key’s permissions, or the app’s scopes and the member’s role, don’t allow this

Media typeapplication/json
object
error
required

What went wrong, in words you can show people

string
issues

For a 400: each invalid field, by its path in the request, like events.0.name

Array<object>
object
path
required
string
message
required
string
requestId

For a 5xx: quote it when contacting support

string

Example generated

{
"error": "example",
"issues": [
{
"path": "example",
"message": "example"
}
],
"requestId": "example"
}

Not found in this workspace

Media typeapplication/json
object
error
required

What went wrong, in words you can show people

string
issues

For a 400: each invalid field, by its path in the request, like events.0.name

Array<object>
object
path
required
string
message
required
string
requestId

For a 5xx: quote it when contacting support

string

Example generated

{
"error": "example",
"issues": [
{
"path": "example",
"message": "example"
}
],
"requestId": "example"
}

Too many requests; wait for the seconds in Retry-After

Media typeapplication/json
object
error
required

What went wrong, in words you can show people

string
issues

For a 400: each invalid field, by its path in the request, like events.0.name

Array<object>
object
path
required
string
message
required
string
requestId

For a 5xx: quote it when contacting support

string

Example generated

{
"error": "example",
"issues": [
{
"path": "example",
"message": "example"
}
],
"requestId": "example"
}