Skip to content

Commit 80a265a

Browse files
natekimball-msftnatekimball-msft
committed
Add section in advanced sending for inline images
1 parent 90d5d91 commit 80a265a

File tree

6 files changed

+405
-46
lines changed

6 files changed

+405
-46
lines changed

‎articles/communication-services/quickstarts/email/send-email-advanced/includes/inline-attachments-java.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: include file
3+
description: Inline Attachments Java SDK include file
4+
author: natekimball-msft
5+
manager: koagbakp
6+
services: azure-communication-services
7+
ms.author: natekimball
8+
ms.date: 04/07/2023
9+
ms.topic: include
10+
ms.service: azure-communication-services
11+
---
12+
13+
## Send an email message with inline attachments
14+
15+
We can add an inline attachment by defining one or more EmailAttachment objects, defining a unique `ContentId` for each, and adding them to our EmailMessage object. Read the attachment file and encode it using Base64.
16+
17+
```java
18+
BinaryData jpgInlineAttachmentContent = BinaryData.fromFile(new File("./inline-attachment.png").toPath());
19+
EmailAttachment jpgInlineAttachment = new EmailAttachment(
20+
"inline-attachment.jpg",
21+
"image/jpeg",
22+
jpgInlineAttachmentContent
23+
).setContentId("my-inline-attachment-1");
24+
25+
BinaryData pngInlineAttachmentContent = BinaryData.fromFile(new File("./inline-attachment.png").toPath());
26+
EmailAttachment pngInlineAttachment = new EmailAttachment(
27+
"inline-attachment.png",
28+
"image/png",
29+
pngInlineAttachmentContent
30+
).setContentId("my-inline-attachment-2");
31+
```
32+
33+
Within the HTML body of the message, we can then embed an image by referencing its `ContentId` within the source of an `<img>` tag.
34+
35+
```java
36+
EmailMessage message = new EmailMessage()
37+
.setSenderAddress(senderAddress)
38+
.setToRecipients(recipientAddress)
39+
.setSubject("Welcome to Azure Communication Services Email")
40+
.setBodyPlainText("This email message is sent from Azure Communication Services Email using the Java SDK.");
41+
.setBodyHtml("<html><h1>HTML body inline images:</h1><img src=\"cid:my-inline-attachment-1\" /><img src=\"cid:my-inline-attachment-2\" /></html>")
42+
.setAttachments(jpgInlineAttachmentContent, pngInlineAttachmentContent);
43+
44+
SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null);
45+
PollResponse<EmailSendResult> response = poller.waitForCompletion();
46+
47+
System.out.println("Operation Id: " + response.getValue().getId());
48+
```
49+
50+
> [!NOTE]
51+
> Regular attachments can be combined with inline attachments, as well. Defining a `ContentId` will treat an attachment as inline, while an attachment without a `ContentId` will be treated as a regular attachment.
52+
53+
### Allowed MIME types
54+
55+
Although most modern clients support inline attachments, the rendering behavior of an inline attachment is largely dependent on the recipient's email client. For this reason, it is suggested to use more common image formats inline whenever possible, such as .png, .jpg, or .gif. For more information on acceptable MIME types for email attachments, see the [allowed MIME types](../../../../concepts/email/email-attachment-allowed-mime-types.md) documentation.
56+
57+
### Sample code
58+
59+
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/send-email-inline-attachments)
60+

‎articles/communication-services/quickstarts/email/send-email-advanced/includes/inline-attachments-js.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: include file
3+
description: Inline Attachments JS SDK include file
4+
author: natekimball-msft
5+
manager: koagbakp
6+
services: azure-communication-services
7+
ms.author: natekimball
8+
ms.date: 04/07/2023
9+
ms.topic: include
10+
ms.service: azure-communication-services
11+
---
12+
13+
## Send an email message with inline attachments
14+
15+
We can add an inline attachment by defining one or more attachment objects, making sure to include a unique `contentId` for each, and adding them to our message. Read the attachment file and encode it using Base64.
16+
17+
```javascript
18+
const jpgFilePath = "./inline-attachment.jpg";
19+
const pngFilePath = "./inline-attachment.png";
20+
21+
const inlineAttachments = [
22+
{
23+
name: path.basename(jpgFilePath),
24+
contentId: "my-inline-attachment-1"
25+
contentType: "image/jpeg",
26+
contentInBase64: readFileSync(jpgFilePath, "base64"),
27+
},
28+
{
29+
name: path.basename(pngFilePath),
30+
contentId: "my-inline-attachment-2"
31+
contentType: "image/png",
32+
contentInBase64: readFileSync(pngFilePath, "base64"),
33+
}
34+
];
35+
```
36+
37+
Within the HTML body of the message, we can then embed an image by referencing its `contentId` within the source of an `<img>` tag.
38+
39+
```javascript
40+
const message = {
41+
sender: "<[email protected]>",
42+
content: {
43+
subject: "Welcome to Azure Communication Services Email",
44+
plainText: "This email message is sent from Azure Communication Services Email using the Javascript SDK.",
45+
html: "<html><h1>HTML body inline images:</h1><img src=\"cid:my-inline-attachment-1\" /><img src=\"cid:my-inline-attachment-2\" /></html>"
46+
},
47+
recipients: {
48+
to: [
49+
{
50+
address: "<[email protected]>",
51+
displayName: "Customer Name",
52+
}
53+
]
54+
},
55+
attachments: inlineAttachments
56+
};
57+
58+
const poller = await emailClient.beginSend(message);
59+
const response = await poller.pollUntilDone();
60+
```
61+
62+
> [!NOTE]
63+
> Regular attachments can be combined with inline attachments, as well. Defining a `contentId` will treat an attachment as inline, while an attachment without a `contentId` will be treated as a regular attachment.
64+
65+
### Allowed MIME types
66+
67+
Although most modern clients support inline attachments, the rendering behavior of an inline attachment is largely dependent on the recipient's email client. For this reason, it is suggested to use more common image formats inline whenever possible, such as .png, .jpg, or .gif. For more information on acceptable MIME types for email attachments, see the [allowed MIME types](../../../../concepts/email/email-attachment-allowed-mime-types.md) documentation.
68+
69+
### Sample code
70+
71+
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-inline-attachments)

‎articles/communication-services/quickstarts/email/send-email-advanced/includes/inline-attachments-net.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: include file
3+
description: Inline Attachments .NET SDK include file
4+
author: natekimball-msft
5+
manager: koagbakp
6+
services: azure-communication-services
7+
ms.author: natekimball
8+
ms.date: 04/07/2023
9+
ms.topic: include
10+
ms.service: azure-communication-services
11+
---
12+
13+
## Send an email message with inline attachments
14+
15+
We can add an inline attachment by defining one or more EmailAttachment objects, defining a unique `ContentId` for each, and adding them to our EmailMessage object. Read the attachment file and encode it using Base64.
16+
17+
```csharp
18+
var jpgFilePath = "./inline-attachment.jpg";
19+
byte[] jpgBytes = File.ReadAllBytes(jpgFilePath);
20+
var jpgBinaryData = new BinaryData(jpgBytes);
21+
var jpgInlineAttachment = new EmailAttachment(
22+
"inline-attachment.jpg",
23+
"image/jpeg",
24+
jpgBinaryData);
25+
jpgInlineAttachment.ContentId = "my-inline-attachment-1";
26+
27+
var pngFilePath = "./inline-attachment.png";
28+
byte[] pngBytes = File.ReadAllBytes(pngFilePath);
29+
var pngBinaryData = new BinaryData(pngBytes);
30+
var pngInlineAttachment = new EmailAttachment(
31+
"inline-attachment.png",
32+
"image/png",
33+
pngBinaryData);
34+
pngInlineAttachment.ContentId = "my-inline-attachment-2";
35+
```
36+
37+
Within the HTML body of the message, we can then embed an image by referencing its `ContentId` within the source of an `<img>` tag.
38+
39+
```csharp
40+
var emailContent = new EmailContent("Welcome to Azure Communication Services Email")
41+
{
42+
PlainText ="This email message is sent from Azure Communication Services Email using the .NET SDK.",
43+
Html = "<html><h1>HTML body inline images:</h1><img src=\"cid:my-inline-attachment-1\" /><img src=\"cid:my-inline-attachment-2\" /></html>"
44+
};
45+
46+
var emailMessage = new EmailMessage(
47+
senderAddress: "[email protected]"
48+
recipientAddress: "[email protected]"
49+
content: emailContent);
50+
51+
emailMessage.Attachments.Add(jpgInlineAttachment);
52+
emailMessage.Attachments.Add(pngInlineAttachment);
53+
54+
try
55+
{
56+
EmailSendOperation emailSendOperation = emailClient.Send(WaitUntil.Completed, emailMessage);
57+
Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");
58+
59+
/// Get the OperationId so that it can be used for tracking the message for troubleshooting
60+
string operationId = emailSendOperation.Id;
61+
Console.WriteLine($"Email operation id = {operationId}");
62+
}
63+
catch (RequestFailedException ex)
64+
{
65+
/// OperationID is contained in the exception message and can be used for troubleshooting purposes
66+
Console.WriteLine($"Email send operation failed with error code: {ex.ErrorCode}, message: {ex.Message}");
67+
}
68+
69+
```
70+
71+
> [!NOTE]
72+
> Regular attachments can be combined with inline attachments, as well. Defining a `ContentId` will treat an attachment as inline, while an attachment without a `ContentId` will be treated as a regular attachment.
73+
74+
### Allowed MIME types
75+
76+
Although most modern clients support inline attachments, the rendering behavior of an inline attachment is largely dependent on the recipient's email client. For this reason, it is suggested to use more common image formats inline whenever possible, such as .png, .jpg, or .gif. For more information on acceptable MIME types for email attachments, see the [allowed MIME types](../../../../concepts/email/email-attachment-allowed-mime-types.md) documentation.
77+
78+
### Sample code
79+
80+
You can download the sample app demonstrating this action from [GitHub](https://github.com/Azure-Samples/communication-services-dotnet-quickstarts/tree/main/SendEmailAdvanced/SendEmailWithInlineAttachments)

‎articles/communication-services/quickstarts/email/send-email-advanced/includes/inline-attachments-python.md

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
title: include file
3+
description: Inline Attachments Python SDK include file
4+
author: natekimball-msft
5+
manager: koagbakp
6+
services: azure-communication-services
7+
ms.author: natekimball
8+
ms.date: 04/07/2023
9+
ms.topic: include
10+
ms.service: azure-communication-services
11+
---
12+
13+
## Send an email message with inline attachments
14+
15+
We can add an inline attachment by defining one or more `attachments`, making sure to include a unique `contentId` for each, and adding them to our message. Read the attachment file and encode it using Base64. Decode the bytes as a string and pass it into the `attachment` object.
16+
17+
```python
18+
import base64
19+
20+
with open("./inline-attachment.jpg", "rb") as file:
21+
jpg_file_bytes_b64 = base64.b64encode(file.read())
22+
23+
with open("./inline-attachment.png", "rb") as file:
24+
png_file_bytes_b64 = base64.b64encode(file.read())
25+
26+
inlineAttachments = [
27+
{
28+
"name": "inline-attachment.jpg",
29+
"contentId": "my-inline-attachment-1",
30+
"contentType": "image/jpeg",
31+
"contentInBase64": jpg_file_bytes_b64.decode()
32+
},
33+
{
34+
"name": "inline-attachment.png",
35+
"contentId": "my-inline-attachment-2",
36+
"contentType": "image/png",
37+
"contentInBase64": png_file_bytes_b64.decode()
38+
}
39+
]
40+
```
41+
42+
Within the HTML body of the message, we can then embed an image by referencing its `contentId` within the source of an `<img>` tag.
43+
44+
```python
45+
message = {
46+
"content": {
47+
"subject": "Welcome to Azure Communication Services Email",
48+
"plainText": "This email message is sent from Azure Communication Services Email using the Python SDK.",
49+
"html": "<html><h1>HTML body inline images:</h1><img src=\"cid:my-inline-attachment-1\" /><img src=\"cid:my-inline-attachment-2\" /></html>"
50+
},
51+
"recipients": {
52+
"to": [
53+
{
54+
"address": "<[email protected]>",
55+
"displayName": "Customer Name"
56+
}
57+
]
58+
},
59+
"senderAddress": "<[email protected]>",
60+
"attachments": inlineAttachments
61+
}
62+
63+
poller = email_client.begin_send(message)
64+
result = poller.result()
65+
```
66+
67+
> [!NOTE]
68+
> Regular attachments can be combined with inline attachments, as well. Defining a `contentId` will treat an attachment as inline, while an attachment without a `contentId` will be treated as a regular attachment.
69+
70+
### Allowed MIME types
71+
72+
Although most modern clients support inline attachments, the rendering behavior of an inline attachment is largely dependent on the recipient's email client. For this reason, it is suggested to use more common image formats inline whenever possible, such as .png, .jpg, or .gif. For more information on acceptable MIME types for email attachments, see the [allowed MIME types](../../../../concepts/email/email-attachment-allowed-mime-types.md) documentation.
73+
74+
### Sample code
75+
76+
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/send-email-inline-attachments)
77+
78+

‎articles/communication-services/quickstarts/email/send-email-advanced/send-email-with-inline-attachments.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: Quickstart - Send email with inline attachments using Azure Communication Service
3+
titleSuffix: An Azure Communication Services Quickstart
4+
description: Learn how to send an email message with inline attachments using Azure Communication Services.
5+
author: natekimball-msft
6+
manager: koagbakp
7+
services: azure-communication-services
8+
ms.author: natekimball
9+
ms.date: 04/07/2023
10+
ms.topic: quickstart
11+
ms.service: azure-communication-services
12+
ms.custom: devx-track-dotnet, devx-track-extended-java, devx-track-js, devx-track-python
13+
zone_pivot_groups: acs-js-csharp-java-python
14+
---
15+
16+
# Quickstart: Send email with inline attachments
17+
18+
In this quick start, you'll learn about how to send email with inline attachments using our Email SDKs.
19+
20+
::: zone pivot="programming-language-csharp"
21+
[!INCLUDE [prepend-net](./includes/prepend-net.md)]
22+
[!INCLUDE [inline-attachments-net](./includes/inline-attachments-net.md)]
23+
::: zone-end
24+
25+
::: zone pivot="programming-language-javascript"
26+
[!INCLUDE [prepend-js](./includes/prepend-js.md)]
27+
[!INCLUDE [inline-attachments-js](./includes/inline-attachments-js.md)]
28+
::: zone-end
29+
30+
::: zone pivot="programming-language-java"
31+
[!INCLUDE [prepend-java](./includes/prepend-java.md)]
32+
[!INCLUDE [inline-attachments-java](./includes/inline-attachments-java.md)]
33+
::: zone-end
34+
35+
::: zone pivot="programming-language-python"
36+
[!INCLUDE [prepend-python](./includes/prepend-python.md)]
37+
[!INCLUDE [inline-attachments-python](./includes/inline-attachments-python.md)]
38+
::: zone-end
39+
40+
## Troubleshooting
41+
42+
### Email Delivery
43+
44+
To troubleshoot issues related to email delivery, you can [get status of the email delivery](../handle-email-events.md) to capture delivery details.
45+
46+
> [!IMPORTANT]
47+
> The success result returned by polling for the status of the send operation only validates the fact that the email has successfully been sent out for delivery. To get additional information about the status of the delivery on the recipient end, you will need to reference [how to handle email events](../handle-email-events.md).
48+
49+
### Email Throttling
50+
51+
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](../send-email-advanced/throw-exception-when-tier-limit-reached.md).
52+
53+
> [!NOTE]
54+
> This sandbox setup is to help developers start building the application. You can gradually request to increase the sending volume once the application is ready to go live. Submit a support request to raise your desired sending limit if you require sending a volume of messages exceeding the rate limits.
55+
56+
## Clean up Azure Communication Service resources
57+
58+
If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about [cleaning up resources](../../create-communication-resource.md#clean-up-resources).
59+
60+
## Next steps
61+
62+
In this quick start, you learned how to manually poll for status when sending email using Azure Communication Services.
63+
64+
You may also want to:
65+
66+
- Learn how to [manually poll for email status](./manually-poll-for-email-status.md)
67+
- Learn more about [sending email to multiple recipients](./send-email-to-multiple-recipients.md)
68+
- Familiarize yourself with [email client library](../../../concepts/email/sdk-features.md)

0 commit comments

Comments
 (0)