Merge pull request #232730 from yogeshmo/email/429-no-retry

Adding documentation for making 429s non-retriable

Author: prmerger-automator[bot]

articles/communication-services/quickstarts/email/includes/send-email-java.md

@@ -222,6 +222,8 @@ Make these replacements in the code:
    mvn exec:java -D"exec.mainClass"="com.communication.quickstart.App" -D"exec.cleanupDaemonThreads"="false"
    ```
 
+If you see that your application is hanging it could be due to email sending being throttled. You can [handle this through logging or by implementing a custom policy](#throw-an-exception-when-email-sending-tier-limit-is-reached).
+
 ### Sample code
 
 You can download the sample app from [GitHub](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/send-email)
@@ -300,3 +302,39 @@ System.out.println("Operation Id: " + response.getValue().getId());
 For more information on acceptable MIME types for email attachments, see the [allowed MIME types](../../../concepts/email/email-attachment-allowed-mime-types.md) documentation.
 
 You can download the sample app demonstrating this action from [GitHub](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/send-email-advanced)
+
+### Throw an exception when email sending tier limit is reached
+
+The Email API has throttling with limitations on the number of email messages that you can send. Email sending has limits applied per minute and per hour as mentioned in [API Throttling and Timeouts](https://learn.microsoft.com/azure/communication-services/concepts/service-limits). When you have reached these limits, additional email sends with `beginSend` calls will receive an error response of “429: Too Many Requests”. By default, the SDK is configured to retry these requests after waiting a certain period of time. We recommend you [set up logging with the Azure SDK](https://learn.microsoft.com/azure/developer/java/sdk/logging-overview) to capture these response codes.
+
+Alternatively, you can manually define a custom policy as shown below. 
+
+```java
+import com.azure.core.http.HttpResponse;
+import com.azure.core.http.policy.ExponentialBackoff;
+
+public class CustomStrategy extends ExponentialBackoff {
+    @Override
+    public boolean shouldRetry(HttpResponse httpResponse) {
+        int code = httpResponse.getStatusCode();
+
+        if (code == HTTP_STATUS_TOO_MANY_REQUESTS) {
+            throw new RuntimeException(httpResponse);
+        }
+        else {
+            return super.shouldRetry(httpResponse);
+        }
+    }
+}
+```
+
+Add this retry policy to your email client. This will ensure that 429 response codes throw an exception rather than being retried.
+
+```java
+import com.azure.core.http.policy.RetryPolicy;
+
+EmailClient emailClient = new EmailClientBuilder()
+    .connectionString(connectionString)
+    .retryPolicy(new RetryPolicy(new CustomStrategy()))
+    .buildClient();
+```

articles/communication-services/quickstarts/email/includes/send-email-js.md

@@ -216,6 +216,9 @@ use the node command to run the code you added to the send-email.js file.
 ```console
 node ./send-email.js
 ```
+
+If you see that your application is hanging it could be due to email sending being throttled. You can [handle this through logging or by implementing a custom policy](#throw-an-exception-when-email-sending-tier-limit-is-reached).
+
 ### Sample code
 
 You can download the sample app from [GitHub](https://github.com/Azure-Samples/communication-services-javascript-quickstarts/tree/main/send-email)
@@ -308,3 +311,39 @@ const response = await emailClient.send(message);
 For more information on acceptable MIME types for email attachments, see the [allowed MIME types](../../../concepts/email/email-attachment-allowed-mime-types.md) documentation.
 
 You can download the sample app demonstrating this action from [GitHub](https://github.com/Azure-Samples/communication-services-javascript-quickstarts/tree/main/send-email-advanced/send-email-attachments)
+
+### Throw an exception when email sending tier limit is reached
+
+The Email API has throttling with limitations on the number of email messages that you can send. Email sending has limits applied per minute and per hour as mentioned in [API Throttling and Timeouts](https://learn.microsoft.com/azure/communication-services/concepts/service-limits). When you have reached these limits, additional email sends with `send` calls will receive an error response of “429: Too Many Requests”. By default, the SDK is configured to retry these requests after waiting a certain period of time. We recommend you [set up logging with the Azure SDK](https://learn.microsoft.com/javascript/api/overview/azure/logger-readme) to capture these response codes.
+
+There are per minute and per hour [limits to the amount of emails you can send using the Azure Communication Email Service](https://learn.microsoft.com/azure/communication-services/concepts/service-limits). When you have reached these limits, any further `beginSend` calls will recieve a `429: Too Many Requests` response. By default, the SDK is configured to retry these requests after waiting a certain period of time. We recommend you [set up logging with the Azure SDK](https://learn.microsoft.com/javascript/api/overview/azure/logger-readme) to capture these response codes.
+
+Alternatively, you can manually define a custom policy as shown below.
+
+```javascript
+const catch429Policy = {
+  name: "catch429Policy",
+  async sendRequest(request, next) {
+    const response = await next(request);
+    if (response.status === 429) {
+      throw new Error(response);
+    }
+    return response;
+  }
+};
+```
+
+Add this policy to your email client. This will ensure that 429 response codes throw an exception rather than being retried.
+
+```java
+const clientOptions = {
+  additionalPolicies: [
+    {
+      policy: catch429Policy,
+      position: "perRetry"
+    }
+  ]
+}
+
+const emailClient = new EmailClient(connectionString, clientOptions);
+```

articles/communication-services/quickstarts/email/includes/send-email-net.md

@@ -227,6 +227,8 @@ Run the application from your application directory with the `dotnet run` comman
 dotnet run
 ```
 
+If you see that your application is hanging it could be due to email sending being throttled. You can [handle this through logging or by implementing a custom policy](#throw-an-exception-when-email-sending-tier-limit-is-reached).
+
 ### Sample code
 
 You can download the sample app from [GitHub](https://github.com/Azure-Samples/communication-services-dotnet-quickstarts/tree/main/SendEmail)
@@ -393,4 +395,37 @@ For more information on acceptable MIME types for email attachments, see the [al
 
 You can download the sample app demonstrating this action from [GitHub](https://github.com/Azure-Samples/communication-services-dotnet-quickstarts/tree/main/SendEmailAdvanced/SendEmailWithAttachments)
 
+### Throw an exception when email sending tier limit is reached
+
+The Email API has throttling with limitations on the number of email messages that you can send. Email sending has limits applied per minute and per hour as mentioned in [API Throttling and Timeouts](https://learn.microsoft.com/azure/communication-services/concepts/service-limits). When you have reached these limits, additional email sends with `SendAsync` calls will receive an error response of “429: Too Many Requests”. By default, the SDK is configured to retry these requests after waiting a certain period of time. We recommend you [set up logging with the Azure SDK](https://learn.microsoft.com/dotnet/azure/sdk/logging) to capture these response codes.
+
+Alternatively, you can manually define a custom policy as shown below.
+
+```csharp
+using Azure.Core.Pipeline;
+
+public class Catch429Policy : HttpPipelineSynchronousPolicy
+{
+    public override void OnReceivedResponse(HttpMessage message)
+    {
+        if (message.Response.Status == 429)
+        {
+            throw new Exception(message.Response);
+        }
+        else
+        {
+            base.OnReceivedResponse(message);
+        }
+    }
+}
+```
+
+Add this policy to your email client. This will ensure that 429 response codes throw an exception rather than being retried.
+
+```csharp
+EmailClientOptions emailClientOptions = new EmailClientOptions();
+emailClientOptions.AddPolicy(new Catch429Policy(), HttpPipelinePosition.PerRetry);
+
+EmailClient emailClient = new EmailClient(connectionString, emailClientOptions);
+```
 

articles/communication-services/quickstarts/email/includes/send-email-python.md

@@ -231,7 +231,6 @@ Make these replacements in the code:
 - Replace `<[email protected]>` with the email address you would like to send a message to.
 - Replace `<[email protected]>` with the MailFrom address of your verified domain.
 
-
 ### Get the status of the email delivery
 
 We can poll for the status of the email delivery by setting a loop on the operation status object returned from the EmailClient's `begin_send` method:
@@ -271,6 +270,8 @@ Run the application from your application directory with the `python` command.
 python send-email.py
 ```
 
+If you see that your application is hanging it could be due to email sending being throttled. You can [handle this through logging or by implementing a custom policy](#throw-an-exception-when-email-sending-tier-limit-is-reached).
+
 ### Sample code
 
 You can download the sample app from [GitHub](https://github.com/Azure-Samples/communication-services-python-quickstarts/tree/main/send-email)
@@ -347,3 +348,17 @@ message = {
 For more information on acceptable MIME types for email attachments, see the [allowed MIME types](../../../concepts/email/email-attachment-allowed-mime-types.md) documentation.
 
 You can download the sample app demonstrating this action from [GitHub](https://github.com/Azure-Samples/communication-services-python-quickstarts/tree/main/send-email-advanced)
+
+### Throw an exception when email sending tier limit is reached
+
+The Email API has throttling with limitations on the number of email messages that you can send. Email sending has limits applied per minute and per hour as mentioned in [API Throttling and Timeouts](https://learn.microsoft.com/azure/communication-services/concepts/service-limits). When you have reached these limits, additional email sends with `SendAsync` calls will receive an error response of “429: Too Many Requests”. By default, the SDK is configured to retry these requests after waiting a certain period of time. We recommend you [set up logging with the Azure SDK](https://learn.microsoft.com/azure/developer/python/sdk/azure-sdk-logging) to capture these response codes.
+
+Alternatively, you can manually define a custom policy as shown below. This will ensure that 429 response codes throw an exception rather than being retried.
+
+```python
+def callback(response):
+    if response.http_response.status_code == 429:
+        raise Exception(response.http_response)
+
+email_client = EmailClient.from_connection_string(<connection_string>, raw_response_hook=callback)
+```