Newsletter

Main

Light

Accent

Card

Main

Light

Accent

1. Create the Newsletter data entity with private fields.
2. Create a role that can create Master Data documents.
3. Generate an API key dedicated to the newsletter.
4. Add the credentials to your project.

Authenticated newsletter subscriptions are available from @faststore/core 4.10.2 (FastStore v4) and 3.100.9 (FastStore v3). Earlier versions send the subscription without credentials and only work if the entity fields are public, which is no longer allowed. To update, see Updating the @faststore/cli package version.

Don't make the Newsletter fields public. Public fields can be read without credentials, which would expose your subscribers' personal data. Starting October 26, 2026, Master Data no longer allows creating public fields. For more information, see Master Data: Temporary restriction on public fields.

For more details about Master Data data entities, see the data entity article.

1. In the VTEX Admin, go to Store Settings > Storefront > Master Data.
2. In Master Data, click Applications > Advanced Settings > Data structure.
3. Click the Data Entities tab.
4. Click Add new.
5. Complete the fields of the Data Entity section with the following information:

   Field name	Value
   Acronym	NL
   Name	Newsletter
   Primary key type	Generate a unique GUID

   Leave Allow all document query without filter unchecked. It lets anyone list every record in the entity through the API without credentials, and the newsletter doesn't need it.
6. In the Fields tab, click New Field and create the following fields:

   Name	Display Name	Type	Description
   email	Email	Email	Customer's email address.
   isNewsletterOptIn	Receive newsletter?	Boolean	Whether the customer wants to receive the newsletter.
   name	Name	Varchar 750	Customer's name. Optional in the form.

   For each field, click the gear icon (⚙️) to open the field configuration options and:
   • Check Is nullable? for the email and name fields.
   • In the Search and filter settings section, check Is searchable? and Is filterable?.
   • Leave Make readable without credentials, Allow editing without credentials, and Allow filtering without credentials unchecked.
7. Click Save and you will be redirected back to the Data Entity tab.
8. In the row of the new NL entity, click the diskette 💾 to publish the created data entity.
9. Click OK.
10. Click the Applications tab to return to the Master Data homepage.
11. Click Reload applications.

1. In the VTEX Admin, go to Account Settings > User Roles.
2. Click New role and name it, for example, FS newsletter.
3. Add the Dynamic Storage product to the role.
4. Under Resources, select only the Insert or update document (not remove) permission.
5. Save the role.

Master Data permissions apply to all data entities in the account, not only to NL. Use this role only for the newsletter API key, and don't add it to keys or users that have other purposes.

1. In the VTEX Admin, go to Account > API Keys.
2. In the Generated tab, click Generate Key.
3. Complete the fields with the following:

   Field name	Description	Value example
   Key identification	Name that identifies the key	FS NEWSLETTER API KEY
   Roles	Select the role for the key	Select only the role created in Step 2, FS newsletter

4. Click Generate.

The App Key and App Token are displayed only once. Copy and securely save both credentials immediately, as you'll need them in the next step.

1. In the FastStore WebOps dashboard, go to the Settings tab.
2. In the Variables and Secrets section, add each credential below. For each one, set Type to secret (not text), fill in Key and Value, and click Add.

   Key	Value
   FS_NEWSLETTER_APP_KEY	YOUR_APP_KEY
   FS_NEWSLETTER_APP_TOKEN	YOUR_APP_TOKEN

3. Wait 5 minutes and click Redeploy. Variables and secrets only take effect in the next successful deployment.

Don't prefix these variables with NEXT_PUBLIC_, which would send them to the browser. Never commit API credentials to your repository, including in vtex.env.

1. In Master Data, open the NL entity in the Data Entities tab.
2. In the Data Entity section, uncheck Allow all document query without filter.
3. For each field, uncheck Make readable without credentials, Allow editing without credentials, and Allow filtering without credentials.
4. Save and publish the entity, and then click Reload applications.
5. Subscribe to the newsletter on your store to confirm that the document is created.

Change the fields to private only after the new version is deployed with the credentials configured. Otherwise, newsletter subscriptions will fail until the deploy is complete.