Skip to navigation

Update newsletter list OAuth Scope: newsletter_lists:write

Update a newsletter list belonging to a specific publication.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"
The prefixed ID of the publication object
newsletterListIdstringRequiredformat: "^(nl_list_[0-9a-fA-F\-]+)$"
The prefixed ID of the newsletter list object

Request

This endpoint expects an object.
namestringOptional
The name of the newsletter list.
descriptionstringOptional
A description of the newsletter list.
slugstringOptional
A unique slug for the newsletter list.
auto_subscribebooleanOptional
Whether new subscribers are automatically subscribed to this list.
show_in_preference_centerbooleanOptional

Whether the list appears on the subscriber Manage Preferences page, where subscribers can opt in to or out of it. Archived lists cannot be shown; archiving a list hides it.

statusenumOptional

The status of the newsletter list. Valid values are active and archived. Setting draft is not permitted.

Allowed values:
email_settingsobjectOptional
The sending identity for posts sent to this list. Only the provided fields within this object will be updated.
headersmap from strings to optional stringsOptional

Custom email headers for posts sent to this list. When provided, this replaces all existing headers on the list. Merges with publication headers at send time, with this list’s values winning on a key collision. Set a value to null to suppress a header inherited from the publication. System-managed headers (e.g. List-Unsubscribe, X-SMTPAPI) cannot be overridden. Headers SendGrid reserves, such as From, Reply-To and Subject, are rejected.

utm_sourcestringOptional

The utm_source appended to links in posts sent to this list.

utm_mediumstringOptional

The utm_medium appended to links in posts sent to this list.

utm_campaignstringOptional

The utm_campaign appended to links in posts sent to this list.

utm_params_enabledbooleanOptional
Whether UTM parameters are appended to links in posts sent to this list. When left unset on the list, falls back to the publication.
tier_idslist of stringsOptional
The prefixed IDs of the paid tiers that gate this list. When provided, this replaces the list's gating tiers. Pass an empty array to open the list to everyone, and omit it or pass null to leave the tiers unchanged. Each tier must belong to the publication. Tier gating is in beta and this field is ignored until it has been enabled for the publication.

Response

OK
dataobject

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error