fix(tem): blocklist (#4288)

Author: ldecarvalho-doc

faq/transactional-email.mdx

@@ -37,11 +37,11 @@ Setting up an [MX record](/transactional-email/concepts#mx-record) is highly rec
 
 ## What happens to automatically configured DNS records when I delete a domain in the Transactional Email service?
 
-When a domain is removed from Scalway's Transactional Email platform, [autoconfigured DNS records](/transactional-email/how-to/autoconfigure-domain/) are not automatically deleted in the Domains & DNS section. If you no longer use the domain for sending emails, you must manually delete or modify these records. It is recommended to verify the associated DNS records to ensure they are correctly configured or removed.
+When a domain is removed from Scalway's Transactional Email platform, [autoconfigured DNS records](/transactional-email/how-to/autoconfigure-domain/) are not automatically deleted in the Domains & DNS section. You must manually delete or modify these records if you no longer use the domain to send emails. Verifying the associated DNS records is recommended to ensure they are correctly configured or removed.
 
 ## What is the impact on the Transactional Email service if a DNS zone is deleted in Scaleway Domains & DNS?
 
-If a DNS zone is deleted while [autoconfig is enabled](/transactional-email/how-to/autoconfigure-domain/), the DNS records will be added to the parent zone. This ensures that the domain remains validated on the Transactional Email platform, allowing continued use of the service without interruption.
+If a DNS zone is deleted while [autoconfig is enabled](/transactional-email/how-to/autoconfigure-domain/), the DNS records will be added to the parent zone. This ensures that the domain remains validated on the Transactional Email platform, allowing continued service use without interruption.
 
 ## What are the limitations and restrictions when using Transactional Email?
 
@@ -51,4 +51,10 @@ Find out about [limits and quotas](/transactional-email/reference-content/tem-ca
 
 At the end of the month, you are billed for the number of emails you sent.
 If the number of emails you have sent exceeds the number of emails included in your offer, you will be billed for the excess emails. For example, if you use the free tier of 300 emails per month, and you end up sending 305 emails, you will only be billed for five emails out of the 305 you have sent.
-Check out our [dedicated page](https://www.scaleway.com/en/pricing/?tags=managedservices-transactionalemail-transactionalemail) for more information about Transactional Email's pricing.
+Check out our [dedicated page](https://www.scaleway.com/en/pricing/?tags=managedservices-transactionalemail-transactionalemail) for more information about Transactional Email's pricing.
+
+## Can I unblock an address that was automatically added to a TEM blocklist before the 48-hour period ends?
+Yes, you can manually unblock any address, even if it is still under the temporary block period. You can unblock up to five addresses every 24 hours.
+
+## What happens if an address on a TEM blocklist becomes valid again?
+You can manually unblock the address. Make sure you confirm that the initial cause of the bounce was resolved before doing so to avoid further issues.

menu/navigation.json

@@ -2507,6 +2507,10 @@
                     "label": "Create and manage an email webhook",
                     "slug": "create-webhooks"
                   },
+                  {
+                    "label": "Manage blocklists",
+                    "slug": "manage-blocklists"
+                  },
                   {
                     "label": "Delete your domain",
                     "slug": "delete-tem-domain"

pages/iam/reference-content/permission-sets.mdx

@@ -103,6 +103,8 @@ Below is a list of the permission sets available at Scaleway.
 | ObservabilityFullAccess      | Full access to create, read, list, edit and delete Observability                      |
 | TransactionalEmailReadOnly   | List and read access to Transactional Email                                   |
 | TransactionalEmailFullAccess | Full access to create, read, list, edit and delete Transactional Email                |
+| TransactionalEmailBlocklistFullAccess  | Full access to blocklists in Transactional Email.                               |
+| TransactionalEmailBlocklistReadOnly | Read access to blocklists in Transactional Email.               |
 | TransactionalEmailDomainReadOnly  |  Read access to domains in Transactional Email. Does not include permissions for e-mails        |
 | TransactionalEmailDomainFullAccess | Full access to domains in Transactional Email. Does not include permissions for e-mails              |
 | TransactionalEmailEmailReadOnly | Read access to e-mails in Transactional Email. Does not include permissions for domain configuration               |

pages/transactional-email/concepts.mdx

@@ -16,6 +16,10 @@ categories:
 
 An aggregate report (`rua`) is a periodic summary that provides data about a domain's email authentication activity. It includes information such as the volume of emails received, the percentage of emails that pass or fail DMARC checks, and the sources of failed authentication.
 
+## Blocklist
+
+Blocklist is a feature that allows you to manage email addresses that generate errors, or “bounces”. Emails are automatically blocked when a mailbox does not exist, or is full, to prevent sending emails to a recipient address that is not reachable.
+
 ## Deliverability
 
 Deliverability is the ability for an email to arrive in a recipient’s email inbox.
@@ -27,7 +31,7 @@ A Domain Keys Identified Mail (DKIM) record is an email security standard. It pr
 ## DMARC record
 
 DMARC stands for **D**omain-bassed **M**essage **A**uthentication **R**eporting and **C**onformance. It is an email authentication protocol that helps prevent email spoofing and phishing attacks by verifying that the sender's domain is legitimate.
-DMARC builds upon two other email authentication protocols: [SPF](#spf-record) and [DKIM](#dkim-record). It allows domain owners to publish policies in their Domain Name System (DNS) records specifying how emails sent from their domain should be handled if they fail authentication checks.
+DMARC builds upon other email authentication protocols: [SPF](#spf-record) and [DKIM](#dkim-record). It allows domain owners to publish policies in their Domain Name System (DNS) records specifying how emails sent from their domain should be handled if they fail authentication checks.
 
 ## DNS propagation
 
@@ -49,6 +53,7 @@ There are seven types of flags:
 - **Send before expiration**: This indicates that you have requested to send your email before a specific date (defined by you), and that your email expires after that date. This is useful if you are sending an email containing a password renewal link, for example.
 - **Soft bounce**: This means that a non-critical error occurred while sending your email. Soft bounced emails are retried. Find out more about [soft bounces](#soft-bounce).
 - **Spam**: This means that your email has been considered spam.
+- **Blocklisted**: This means that the email was blocked by a blocklist before the sending attempt.
 
 ## Forensic report
 
@@ -168,6 +173,8 @@ These are the different event types:
 - `email_delivered`: The email was successfully sent and accepted by the destination server. This event confirms that the email has reached the recipient's inbox.
 - `email_spam`: The email was identified as spam by Scaleway or the destination server. This event indicates that the email was classified as spam, either by an automated filter or by the recipient.
 - `email_mailbox_not_found`: The email was definitively rejected with a "mailbox not found" error. This indicates that the recipient's email address does not exist or is no longer active.
+- `email_blocklisted` - An email was blocked by an active blocklist.
+- `blocklist_created` - A blocklist is created for an email address. Any new emails sent by the address will be blocked.
 
 <Message type="note">
   Refer to the [Transactional Email API documentation](https://www.scaleway.com/en/developers/api/transactional-email/) for more information about event types.

pages/transactional-email/how-to/create-webhooks.mdx

@@ -23,6 +23,8 @@ You can set up webhooks for Scaleway Transactional Email and subscribe them to [
   Currently, webhooks are integrated exclusively with the Scaleway Topics and Events. Billing for webhooks is based on the Scaleway [Topics and Events billing](https://www.scaleway.com/en/pricing/managed-databases/#messaging-and-queuing).
 </Message>
 
+<Macro id="requirements" />
+
 - A Scaleway account logged into the [console](https://console.scaleway.com)
 - [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
 - [Configured your domain(s) with Transactional Email](/transactional-email/how-to/configure-domain-with-transactional-email/)

pages/transactional-email/how-to/manage-blocklists.mdx

@@ -0,0 +1,67 @@
+---
+meta:
+  title: How to manage Transactional Email blocklists
+  description: This page provides instructions how to improve the quality of your email deliveries and maintain your domain's reputation score with TEM blocklists.
+content:
+  h1: How to manage Transactional Email blocklists
+  paragraph: This page provides instructions how to improve the quality of your email deliveries and maintain your domain's reputation score with TEM blocklists.
+tags: blocklist reputation transactional
+dates:
+  validation: 2025-01-20
+  posted: 2025-01-20
+categories:
+  - managed-services
+---
+
+The Transactional Email blocklist feature allows your to manage email addresses that generate errors, or “bounces”. Emails are automatically blocked when a mailbox does not exist, or is full, to prevent sending emails to a recipient address that is not reachable.
+
+<Macro id="requirements" />
+
+- A Scaleway account logged into the [console](https://console.scaleway.com)
+- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization. For blocklists your can apply the `TransactionalEmailBlocklistFullAccess` permission
+- [Configured your domain(s) with Transactional Email](/transactional-email/how-to/configure-domain-with-transactional-email/)
+
+## How to monitor temporary blocklists
+
+If any of your emails bounced, you will see a temporary blocklist entry, with a duration of 48 hours, containing the details of the email that bounced and the reason, or flag. Some examples of bounce reasons are:
+
+  - `Mailbox not found` - when mailbox does not exist
+  - `Mailbox full` - when the mailbox is full.
+
+The temporary blocklist entry is created automatically to prevent repeated attempts to send emails, which could damage your reputation.
+
+To see the blocklist:
+
+1. Click **Transactional Email** in the **Managed Services** section of the [console](https://console.scaleway.com/) side menu. Your domains display.
+2. Click the domain whose blocklist you want to manage. An overview of your domain appears.
+3. Click the **Blocklist** tab. Your blocklist displays, detailing the recipient email, the flags, the date the block began, and when it ends.
+
+<Message type="tip">
+  You can [create webhooks](/transactional-email/how-to/create-webhooks) for the following blocklist events:
+    - `email_blocklisted` - An email was blocked by an active blocklist.
+    - `blocklist_created` - A blocklist was created for an email address. Any new emails sent by the address will be blocked.
+
+  By setting up a blocklist webhook, you can track changes to your blocklist in real time.
+</Message>
+
+## How to unblock an email address
+
+You can unblock any address that was added to the blocklist. This is useful in cases where:
+
+- A temporary error has been corrected. The recipient has freed up space in their mailbox, for example.
+- An address becomes valid again after an update.
+
+<Message type="note">
+  You can unblock up to five addresses every 24 hours.
+</Message>
+
+1. Click **Transactional Email** in the **Managed Services** section of the [console](https://console.scaleway.com/) side menu. Your domains display.
+2. Click the domain whose blocklist you want to manage. An overview of your domain appears.
+3. Click the **Blocklist** tab. Your blocklist displays.
+4. Click **Unblock** next to the email address you wish to unblock. A pop-up appears to warn you to:
+
+    <Message type="important">
+      Make sure the issue causing the email's rejection is resolved before unblocking it to protect your reputation score and ensure optimal email deliverability.
+    </Message>
+5. Type **UNBLOCK** and click **Unblock** if you wish to continue.
+    The email address is removed from your blocklist.