Skip to content

Commit 1f2c00b

Browse files
yogeshmoYogesh Mohanraj
yogeshmo
and
Yogesh Mohanraj
authored
[Communication][Email] Addressing SDK Feedback for GA (Azure#28165)
* Regenerating SDK with new Swagger API version * Changing "attachementType" to "type" in tests and samples * Implementing SDK Feedback * Updating the CHANGELOG and the tests * Regenerating SDK with swagger changes * Removing patch file * Updating CHANGELOG * Removing unused import * Linting fixes * Updating contentInBase64 property * Minor fixes and removing old recordings --------- Co-authored-by: Yogesh Mohanraj <ymohanraj@microsoft.com>
1 parent 04aa7e9 commit 1f2c00b

File tree

36 files changed

+1195
-1376
lines changed

36 files changed

+1195
-1376
lines changed

‎sdk/communication/azure-communication-email/CHANGELOG.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,19 @@
33
## 1.0.0b2 (Unreleased)
44

55
### Features Added
6-
- Added the ability specify the API version by an optional `api_version` keyword parameter.
6+
- Adding support for AAD token authentication
7+
- Added the ability to specify the API version by an optional `api_version` keyword parameter.
78

89
### Breaking Changes
910
- Made the SDK Model-less. Objects are now constructed using a dictionary instead of a model.
11+
- Reworked the SDK to follow the LRO (long running operation) approach. The 'begin_send' method returns a poller that can be used to check for the status of sending the email and retrieve the result. The return object has been adjusted to fit this approach.
12+
- The `get_send_status` method has been removed.
13+
- The `sender` property has been changed to `senderAddress`.
14+
- The `email` property under the recipient object has been changed to `address`.
15+
- The `attachmentType` property under `attachments` has been changed to 'contentType'. This now accepts the attachment mime type.
16+
- The `contentBytesBase64` property under `attachments` has been changed to `contentInBase64`
17+
- Custom headers in the email message are now key/value pairs.
18+
- The importance property was removed. Email importance can now be specified through either the `x-priority` or `x-msmail-priority` custom headers.
1019

1120
### Bugs Fixed
1221

‎sdk/communication/azure-communication-email/README.md‎

Lines changed: 22 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,7 @@ This package contains a Python SDK for Azure Communication Services for Email.
44

55
## Key concepts
66

7-
The Azure Communication Email package is used to do following:
8-
- Send emails to multiple types of recipients
9-
- Query the status of a sent email message
7+
The Azure Communication Email package is used to send emails to multiple types of recipients.
108

119
## Getting started
1210

@@ -26,7 +24,7 @@ pip install azure-communication-email
2624

2725
## Examples
2826

29-
`EmailClient` provides the functionality to send email messages .
27+
`EmailClient` provides the functionality to send email messages.
3028

3129
## Authentication
3230

@@ -63,7 +61,7 @@ client = EmailClient(endpoint, credential);
6361

6462
### Send an Email Message
6563

66-
To send an email message, call the `send` function from the `EmailClient`.
64+
To send an email message, call the `begin_send` function from the `EmailClient`. This will return a poller. You can use this poller to check on the status of the operation and retrieve the result once it's finished.
6765

6866
```python
6967
message = {
@@ -75,15 +73,16 @@ message = {
7573
"recipients": {
7674
"to": [
7775
{
78-
"email": "customer@domain.com",
76+
"address": "customer@domain.com",
7977
"displayName": "Customer Name"
8078
}
8179
]
8280
},
83-
"sender": "sender@contoso.com"
81+
"senderAddress": "sender@contoso.com"
8482
}
8583

86-
response = client.send(message)
84+
poller = email_client.begin_send(message)
85+
result = poller.result()
8786
```
8887

8988
### Send an Email Message to Multiple Recipients
@@ -99,22 +98,23 @@ message = {
9998
},
10099
"recipients": {
101100
"to": [
102-
{"email": "customer@domain.com", "displayName": "Customer Name"},
103-
{"email": "customer2@domain.com", "displayName": "Customer Name 2"}
101+
{"address": "customer@domain.com", "displayName": "Customer Name"},
102+
{"address": "customer2@domain.com", "displayName": "Customer Name 2"}
104103
],
105104
"cc": [
106-
{"email": "ccCustomer@domain.com", "displayName": "CC Customer Name"},
107-
{"email": "ccCustomer2@domain.com", "displayName": "CC Customer Name 2"}
105+
{"address": "ccCustomer@domain.com", "displayName": "CC Customer Name"},
106+
{"address": "ccCustomer2@domain.com", "displayName": "CC Customer Name 2"}
108107
],
109108
"bcc": [
110-
{"email": "bccCustomer@domain.com", "displayName": "BCC Customer Name"},
111-
{"email": "bccCustomer2@domain.com", "displayName": "BCC Customer Name 2"}
109+
{"address": "bccCustomer@domain.com", "displayName": "BCC Customer Name"},
110+
{"address": "bccCustomer2@domain.com", "displayName": "BCC Customer Name 2"}
112111
]
113112
},
114-
"sender": "sender@contoso.com"
113+
"senderAddress": "sender@contoso.com"
115114
}
116115

117-
response = client.send(message)
116+
poller = email_client.begin_send(message)
117+
result = poller.result()
118118
```
119119

120120
### Send Email with Attachments
@@ -138,31 +138,23 @@ message = {
138138
"recipients": {
139139
"to": [
140140
{
141-
"email": "customer@domain.com",
141+
"address": "customer@domain.com",
142142
"displayName": "Customer Name"
143143
}
144144
]
145145
},
146-
"sender": "sender@contoso.com",
146+
"senderAddress": "sender@contoso.com",
147147
"attachments": [
148148
{
149149
"name": "attachment.txt",
150-
"attachmentType": "txt",
151-
"contentBytesBase64": file_bytes_b64.decode()
150+
"attachmentType": "text/plain",
151+
"contentInBase64": file_bytes_b64.decode()
152152
}
153153
]
154154
}
155155

156-
response = client.send(message)
157-
```
158-
159-
### Get Email Message Status
160-
161-
The result from the `send` call contains a `messageId` which can be used to query the status of the email.
162-
163-
```python
164-
response = client.send(message)
165-
status = client.get_send_status(response['messageId'])
156+
poller = email_client.begin_send(message)
157+
result = poller.result()
166158
```
167159

168160
## Troubleshooting

‎sdk/communication/azure-communication-email/azure/communication/email/_api_versions.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99

1010
class ApiVersion(str, Enum, metaclass=CaseInsensitiveEnumMeta):
1111
V2021_10_01_PREVIEW = "2021-10-01-preview"
12+
V2023_01_15_PREVIEW = "2023-01-15-preview"
1213

1314

14-
DEFAULT_VERSION = ApiVersion.V2021_10_01_PREVIEW
15+
DEFAULT_VERSION = ApiVersion.V2023_01_15_PREVIEW

‎sdk/communication/azure-communication-email/azure/communication/email/_email_client.py‎

Lines changed: 50 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@
66

77
import sys
88
from typing import Any, Union, IO
9-
from uuid import uuid4
109
from azure.core.credentials import AzureKeyCredential
1110
from azure.core.credentials import TokenCredential
11+
from azure.core.polling import LROPoller
1212
from azure.core.tracing.decorator import distributed_trace
13-
from ._shared.utils import parse_connection_str, get_authentication_policy, get_current_utc_time
13+
from ._shared.utils import parse_connection_str, get_authentication_policy
1414
from ._generated._client import AzureCommunicationEmailService
1515
from ._version import SDK_MONIKER
1616
from ._api_versions import DEFAULT_VERSION
@@ -80,24 +80,28 @@ def from_connection_string(
8080
return cls(endpoint, AzureKeyCredential(access_key), **kwargs)
8181

8282
@distributed_trace
83-
def send(
83+
def begin_send(
8484
self,
85-
email_message: Union[JSON, IO],
86-
**kwargs
87-
) -> JSON:
85+
message: Union[JSON, IO],
86+
**kwargs: Any
87+
) -> LROPoller[JSON]:
8888
# cSpell:disable
8989
"""Queues an email message to be sent to one or more recipients.
9090
91-
:param email_message: The message payload for sending an email. Required.
92-
:type email_message: JSON
93-
:return: JSON object
94-
:rtype: JSON
91+
Queues an email message to be sent to one or more recipients.
92+
93+
:param message: Message payload for sending an email. Required.
94+
:type message: JSON
95+
:keyword str continuation_token: A continuation token to restart a poller from a saved state.
96+
:return: An instance of LROPoller that returns JSON object
97+
:rtype: ~azure.core.polling.LROPoller[JSON]
98+
:raises ~azure.core.exceptions.HttpResponseError:
9599
96-
Example:
100+
Example:
97101
.. code-block:: python
98102
99103
# JSON input template you can fill out and use as your body input.
100-
email_message = {
104+
message = {
101105
"content": {
102106
"subject": "str", # Subject of the email message. Required.
103107
"html": "str", # Optional. Html version of the email message.
@@ -107,98 +111,72 @@ def send(
107111
"recipients": {
108112
"to": [
109113
{
110-
"email": "str", # Email address. Required.
114+
"address": "str", # Email address. Required.
111115
"displayName": "str" # Optional. Email display name.
112116
}
113117
],
114-
"cc": [
118+
"bcc": [
115119
{
116-
"email": "str", # Email address. Required.
120+
"address": "str", # Email address. Required.
117121
"displayName": "str" # Optional. Email display name.
118122
}
119123
],
120-
"bcc": [
124+
"cc": [
121125
{
122-
"email": "str", # Email address. Required.
126+
"address": "str", # Email address. Required.
123127
"displayName": "str" # Optional. Email display name.
124128
}
125129
]
126130
},
127-
"sender": "str", # Sender email address from a verified domain. Required.
131+
"senderAddress": "str", # Sender email address from a verified domain.
132+
Required.
128133
"attachments": [
129134
{
130-
"attachmentType": "str", # The type of attachment file.
131-
Required. Known values are: "avi", "bmp", "doc", "docm", "docx", "gif",
132-
"jpeg", "mp3", "one", "pdf", "png", "ppsm", "ppsx", "ppt", "pptm",
133-
"pptx", "pub", "rpmsg", "rtf", "tif", "txt", "vsd", "wav", "wma", "xls",
134-
"xlsb", "xlsm", and "xlsx".
135-
"contentBytesBase64": "str", # Base64 encoded contents of
136-
the attachment. Required.
135+
"contentInBase64": "str", # Base64 encoded contents of the
136+
attachment. Required.
137+
"contentType": "str", # MIME type of the content being
138+
attached. Required.
137139
"name": "str" # Name of the attachment. Required.
138140
}
139141
],
140142
"disableUserEngagementTracking": bool, # Optional. Indicates whether user
141143
engagement tracking should be disabled for this request if the resource-level
142144
user engagement tracking setting was already enabled in the control plane.
143-
"headers": [
144-
{
145-
"name": "str", # Header name. Required.
146-
"value": "str" # Header value. Required.
147-
}
148-
],
149-
"importance": "normal", # Optional. Default value is "normal". The
150-
importance type for the email. Known values are: "high", "normal", and "low".
145+
"headers": {
146+
"str": "str" # Optional. Custom email headers to be passed.
147+
},
151148
"replyTo": [
152149
{
153-
"email": "str", # Email address. Required.
150+
"address": "str", # Email address. Required.
154151
"displayName": "str" # Optional. Email display name.
155152
}
156153
]
157154
}
158155
159-
# response body for status code(s): 200
156+
# response body for status code(s): 202
160157
response == {
161-
"messageId": "str", # System generated id of an email message sent. Required.
158+
"id": "str", # The unique id of the operation. Use a UUID. Required.
159+
"status": "str", # Status of operation. Required. Known values are:
160+
"NotStarted", "Running", "Succeeded", "Failed", and "Canceled".
161+
"error": {
162+
"additionalInfo": [
163+
{
164+
"info": {}, # Optional. The additional info.
165+
"type": "str" # Optional. The additional info type.
166+
}
167+
],
168+
"code": "str", # Optional. The error code.
169+
"details": [
170+
...
171+
],
172+
"message": "str", # Optional. The error message.
173+
"target": "str" # Optional. The error target.
174+
}
162175
}
163176
"""
164177
# cSpell:enable
165178

166-
return self._generated_client.email.send(
167-
repeatability_request_id=uuid4(),
168-
repeatability_first_sent=get_current_utc_time(),
169-
email_message=email_message,
170-
**kwargs
171-
)
172-
173-
@distributed_trace
174-
def get_send_status(
175-
self,
176-
message_id: str,
177-
**kwargs
178-
) -> JSON:
179-
"""Gets the status of a message sent previously.
180-
181-
:param message_id: System generated message id (GUID) returned from a previous call to send email
182-
:type message_id: str
183-
:return: JSON object
184-
:rtype: JSON
185-
186-
Example:
187-
.. code-block:: python
188-
189-
# response body
190-
response == {
191-
"messageId": "str", # System generated id of an email message sent.
192-
Required.
193-
"status": "str" # The type indicating the status of a request. Required.
194-
Known values are: "queued", "outForDelivery", and "dropped".
195-
}
196-
"""
197-
198-
return self._generated_client.email.get_send_status(
199-
message_id=message_id,
200-
**kwargs
201-
)
179+
return self._generated_client.email.begin_send(message=message, **kwargs)
202180

203181
def __enter__(self) -> "EmailClient":
204182
self._generated_client.__enter__()

‎sdk/communication/azure-communication-email/azure/communication/email/_generated/_client.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,11 @@ class AzureCommunicationEmailService: # pylint: disable=client-accepts-api-vers
2929
:param endpoint: The communication resource, for example
3030
https://my-resource.communication.azure.com. Required.
3131
:type endpoint: str
32-
:keyword api_version: Api Version. Default value is "2021-10-01-preview". Note that overriding
32+
:keyword api_version: Api Version. Default value is "2023-01-15-preview". Note that overriding
3333
this default value may result in unsupported behavior.
3434
:paramtype api_version: str
35+
:keyword int polling_interval: Default waiting time between two polls for LRO operations if no
36+
Retry-After header is present.
3537
"""
3638

3739
def __init__( # pylint: disable=missing-client-constructor-parameter-credential

‎sdk/communication/azure-communication-email/azure/communication/email/_generated/_configuration.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,14 +23,14 @@ class AzureCommunicationEmailServiceConfiguration(Configuration): # pylint: dis
2323
:param endpoint: The communication resource, for example
2424
https://my-resource.communication.azure.com. Required.
2525
:type endpoint: str
26-
:keyword api_version: Api Version. Default value is "2021-10-01-preview". Note that overriding
26+
:keyword api_version: Api Version. Default value is "2023-01-15-preview". Note that overriding
2727
this default value may result in unsupported behavior.
2828
:paramtype api_version: str
2929
"""
3030

3131
def __init__(self, endpoint: str, **kwargs: Any) -> None:
3232
super(AzureCommunicationEmailServiceConfiguration, self).__init__(**kwargs)
33-
api_version = kwargs.pop("api_version", "2021-10-01-preview") # type: str
33+
api_version = kwargs.pop("api_version", "2023-01-15-preview") # type: str
3434

3535
if endpoint is None:
3636
raise ValueError("Parameter 'endpoint' must not be None.")

‎sdk/communication/azure-communication-email/azure/communication/email/_generated/_version.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@
66
# Changes may cause incorrect behavior and will be lost if the code is regenerated.
77
# --------------------------------------------------------------------------
88

9-
VERSION = "1.0.0b1"
9+
VERSION = "1.0.0b2"

‎sdk/communication/azure-communication-email/azure/communication/email/_generated/aio/_client.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,11 @@ class AzureCommunicationEmailService: # pylint: disable=client-accepts-api-vers
2929
:param endpoint: The communication resource, for example
3030
https://my-resource.communication.azure.com. Required.
3131
:type endpoint: str
32-
:keyword api_version: Api Version. Default value is "2021-10-01-preview". Note that overriding
32+
:keyword api_version: Api Version. Default value is "2023-01-15-preview". Note that overriding
3333
this default value may result in unsupported behavior.
3434
:paramtype api_version: str
35+
:keyword int polling_interval: Default waiting time between two polls for LRO operations if no
36+
Retry-After header is present.
3537
"""
3638

3739
def __init__( # pylint: disable=missing-client-constructor-parameter-credential

0 commit comments

Comments
 (0)