|
| 1 | +--- |
| 2 | +title: Custom headers for Azure Email Communication Service |
| 3 | +titleSuffix: An Azure Communication Services concept document |
| 4 | +description: Learn about sending custom headers. |
| 5 | +author: anmolbohra |
| 6 | +manager: koagbakp |
| 7 | +services: azure-communication-services |
| 8 | +ms.author: anmolbohra |
| 9 | +ms.date: 01/09/2025 |
| 10 | +ms.topic: conceptual |
| 11 | +ms.service: azure-communication-services |
| 12 | +--- |
| 13 | +# Adding Reserved Custom headers |
| 14 | + |
| 15 | +Custom headers can be sent along with an email request. These headers are defined as a dictionary. There are some predefined custom headers which can be used to handle some of the email sending scenarios. |
| 16 | + |
| 17 | + |
| 18 | +| Custom Header Name | Property | |
| 19 | +| --- | --- | |
| 20 | +| x-ms-acsemail-ignore-duplicate-content-id | When this header is explicitly set to true, we don't validate duplicate content ID and will let the author manage duplicates. The default value of this header (if not present) is false. In this case, we return a 'Bad Request' when we encounter duplicate ContentID. | |
| 21 | +| x-ms-acsemail-suppress-invalid-attachment | By default, if the attachment is invalid, we return bad request. If this header is set to true and if an attachment is invalid, we continue with the request without the attachment. | |
| 22 | +| x-ms-acsemail-validate-message-id | When this header is explicitly set to true, we validate the internet message ID sent by the customer. The validations include checking for [RFC 2822 ](https://www.rfc-editor.org/rfc/rfc2822) Internet Message ID format and also if there's a duplicate already present. If it fails, we return bad request. If the header isn't set and the internet message ID validation fails, we remove the message ID and let the service create one. By default, we don't force this validation. < table>< thead>< tr>< th>Internet Message ID</ th>< th>Validity</ th></ tr></ thead>< tbody>< tr>< td> <[email protected]></ td>< td>Valid</ td></ tr>< tr>< td> <202501131823.34067409c4494c2c8b2de03ceb26f173-NVZOA====== @microsoft.com ></ td>< td>Valid</ td></ tr>< tr>< td> [email protected]</ a></ td>< td>Invalid</ td></ tr>< tr>< td> <guid ></ td>< td>Invalid</ td></ tr>< tr>< td> <guid.domain ></ td>< td>Invalid</ td></ tr></ tbody></ table> | |
| 23 | + |
| 24 | +## Send an email message with custom headers |
| 25 | + |
| 26 | +We can define custom headers by adding header details to emailMessage. |
| 27 | + |
| 28 | +```csharp |
| 29 | +// Create the email content |
| 30 | +var emailContent = new EmailContent("Welcome to Azure Communication Service Email APIs.") |
| 31 | +{ |
| 32 | + PlainText = "This email message is sent from Azure Communication Service Email.", |
| 33 | + Html = "<html><body><h1>Quick send email test</h1><br/><h4>This email message is sent from Azure Communication Service Email.</h4><p>This mail was sent using .NET SDK!!</p></body></html>" |
| 34 | +}; |
| 35 | + |
| 36 | +// Create the To list |
| 37 | +var toRecipients = new List<EmailAddress> |
| 38 | +{ |
| 39 | + new EmailAddress( "<[email protected]>"), |
| 40 | + new EmailAddress( "<[email protected]>"), |
| 41 | +}; |
| 42 | + |
| 43 | +// Add Custom headers |
| 44 | +var customHeaders = new Dictionary<string, string> |
| 45 | +{ |
| 46 | + {"x-ms-acsemail-suppress-invalid-attachment", "true"}, // if the attachment is of invalid type, this request will still be processed without the attachment. |
| 47 | +} |
| 48 | + |
| 49 | +var emailAttachment = new EmailAttachment("attachment.pdf", MediaTypeNames.Application.Pdf, contentBinaryData); |
| 50 | + |
| 51 | +EmailRecipients emailRecipients = new EmailRecipients(toRecipients); |
| 52 | + |
| 53 | +// Create the EmailMessage |
| 54 | +var emailMessage = new EmailMessage( |
| 55 | + senderAddress: "[email protected]" // The email address of the domain registered with the Communication Services resource |
| 56 | + emailRecipients, |
| 57 | + emailContent); |
| 58 | + |
| 59 | +// Add custom headers to the emailMessage |
| 60 | +emailMessage.Headers.Add(customHeaders); |
| 61 | +// Add attachment to the emailMessage |
| 62 | +emailMessage.Attachments.Add(emailAttachment); |
| 63 | + |
| 64 | +try |
| 65 | +{ |
| 66 | + EmailSendOperation emailSendOperation = emailClient.Send(WaitUntil.Completed, emailMessage); |
| 67 | + Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}"); |
| 68 | + |
| 69 | + /// Get the OperationId so that it can be used for tracking the message for troubleshooting |
| 70 | + string operationId = emailSendOperation.Id; |
| 71 | + Console.WriteLine($"Email operation id = {operationId}"); |
| 72 | +} |
| 73 | +catch (RequestFailedException ex) |
| 74 | +{ |
| 75 | + /// OperationID is contained in the exception message and can be used for troubleshooting purposes |
| 76 | + Console.WriteLine($"Email send operation failed with error code: {ex.ErrorCode}, message: {ex.Message}"); |
| 77 | +} |
| 78 | + |
| 79 | +``` |
| 80 | +Run the application from your application directory with the `dotnet run` command. |
| 81 | + |
| 82 | +```console |
| 83 | +dotnet run |
| 84 | +``` |
0 commit comments