Skip to content

Commit ac7f9d6

Browse files
apattathapattath
authored
Update ACS Email swagger based on prior feedback from review board in preparation for GA (#21841)
* rename EmailMessage to Message and Sender to SenderEmail * Change EmailCustomHeaders to a dictionary of string, string * add x-ms-client-request-id header * update swagger version * Remove AttachmentType enum, change to use MIME type and update SendEmail sample * Add new version folder for updated swagger version * Restore files from 2021-10-01-preview version * Updating references and readme to point to the new preview version * Fix API version to 2023-01-15-preview instead of 2023-15-01-preview * Rename preview version folder * Revert name of Message object to EmailMessage, but retain name to be generated as message * remove retry-after header, update attachment description, change cc,bcc to lowercase * update samples based on changes so far * add x-ms-long-running-operation flag * Remove importance field from email message * update swagger to match LongRunningOperation pattern * update swagger version of CommunicationErrorResponse * Remove SendStatusResult object * rename title to EmailClient * Add more status retrieval samples * fix validation errors in swagger * update swagger based on REST API review feedback * Update casing for opreation status in all samples * update swagger based on ARB SDK Feedback * update get operation status reference schema * update property ContentBytesBase64 to ContentInBase64 * rename disableUserEngagementTracking property
1 parent 1eefb2f commit ac7f9d6

File tree

6 files changed

+535
-1
lines changed

6 files changed

+535
-1
lines changed

‎specification/communication/data-plane/Email/preview/2023-01-15-preview/CommunicationServicesEmail.json

Lines changed: 384 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,384 @@
1+
{
2+
"swagger": "2.0",
3+
"info": {
4+
"title": "EmailClient",
5+
"description": "Azure Communication Email Service",
6+
"version": "2023-01-15-preview"
7+
},
8+
"paths": {
9+
"/emails/operations/{operationId}": {
10+
"get": {
11+
"tags": [
12+
"EmailGetSendResult"
13+
],
14+
"summary": "Gets the status of the email send operation.",
15+
"operationId": "Email_GetSendResult",
16+
"produces": [
17+
"application/json"
18+
],
19+
"parameters": [
20+
{
21+
"in": "path",
22+
"name": "operationId",
23+
"description": "ID of the long running operation (GUID) returned from a previous call to send email",
24+
"required": true,
25+
"type": "string"
26+
},
27+
{
28+
"$ref": "#/parameters/ApiVersionParameter"
29+
}
30+
],
31+
"responses": {
32+
"default": {
33+
"description": "Error",
34+
"headers": {
35+
"x-ms-error-code": {
36+
"description": "Error code - this will be the same as the code in the error property in the response body.",
37+
"type": "string"
38+
}
39+
},
40+
"schema": {
41+
"$ref": "../../../../../common-types/data-plane/v1/types.json#/definitions/ErrorResponse"
42+
}
43+
},
44+
"200": {
45+
"description": "Message status was successfully retrieved.",
46+
"headers": {
47+
"retry-after": {
48+
"description": "This header will only be present when the status is a non-terminal status. It indicates the minimum amount of time in seconds to wait before polling for operation status again.",
49+
"type": "integer",
50+
"format": "int32"
51+
}
52+
},
53+
"schema": {
54+
"$ref": "#/definitions/EmailSendResult"
55+
}
56+
}
57+
},
58+
"x-ms-examples": {
59+
"Get Message Status FailedTerminalStatus": {
60+
"$ref": "./examples/GetOperationStatusReturnsFailedTerminalStatus.json"
61+
},
62+
"Get Message Status NonTerminalStatus": {
63+
"$ref": "./examples/GetOperationStatusReturnsNonTerminalStatus.json"
64+
},
65+
"Get Message Status SuccessTerminalStatus": {
66+
"$ref": "./examples/GetOperationStatusReturnsSuccessTerminalStatus.json"
67+
}
68+
}
69+
}
70+
},
71+
"/emails:send": {
72+
"post": {
73+
"tags": [
74+
"EmailSend"
75+
],
76+
"summary": "Queues an email message to be sent to one or more recipients",
77+
"operationId": "Email_Send",
78+
"consumes": [
79+
"application/json"
80+
],
81+
"produces": [
82+
"application/json"
83+
],
84+
"parameters": [
85+
{
86+
"in": "header",
87+
"name": "Operation-Id",
88+
"description": "This is the ID used by the status monitor for this long running operation.",
89+
"type": "string",
90+
"required": false,
91+
"format": "uuid"
92+
},
93+
{
94+
"in": "header",
95+
"name": "x-ms-client-request-id",
96+
"description": "Tracking ID sent with the request to help with debugging.",
97+
"type": "string",
98+
"required": false,
99+
"format": "uuid",
100+
"x-ms-client-name": "ClientRequestId"
101+
},
102+
{
103+
"$ref": "#/parameters/ApiVersionParameter"
104+
},
105+
{
106+
"in": "body",
107+
"name": "emailMessage",
108+
"description": "Message payload for sending an email",
109+
"required": true,
110+
"x-ms-client-name": "message",
111+
"schema": {
112+
"$ref": "#/definitions/EmailMessage"
113+
}
114+
}
115+
],
116+
"responses": {
117+
"default": {
118+
"description": "Error",
119+
"headers": {
120+
"x-ms-error-code": {
121+
"description": "Error code - this will be the same as the code in the error property in the response body.",
122+
"type": "string"
123+
}
124+
},
125+
"schema": {
126+
"$ref": "../../../../../common-types/data-plane/v1/types.json#/definitions/ErrorResponse"
127+
}
128+
},
129+
"202": {
130+
"description": "The service has accepted the request and will start processing the message later. It will return 'Accepted' immediately and include an 'Operation-Location' header. Client side should further query the operation/message status using the URL specified in 'Operation-Location' header. Once the send operation has succeeded, you can get additional status about email delivery through event grid events (for events reference, please refer to: https://learn.microsoft.com/en-us/azure/event-grid/communication-services-email-events)",
131+
"headers": {
132+
"Operation-Location": {
133+
"description": "Location url of where to poll the status of this operation from.",
134+
"type": "string"
135+
},
136+
"retry-after": {
137+
"description": "This header will only be present when the operation status is a non-terminal status. It indicates the minimum amount of time in seconds to wait before polling for operation status again.",
138+
"type": "integer",
139+
"format": "int32"
140+
}
141+
},
142+
"schema": {
143+
"$ref": "#/definitions/EmailSendResult"
144+
}
145+
}
146+
},
147+
"x-ms-long-running-operation": true,
148+
"x-ms-long-running-operation-options": {
149+
"final-state-via": "azure-async-operation"
150+
},
151+
"x-ms-examples": {
152+
"Send Email": {
153+
"$ref": "./examples/SendEmail.json"
154+
}
155+
}
156+
}
157+
}
158+
},
159+
"definitions": {
160+
"EmailSendResult": {
161+
"description": "Status of the long running operation",
162+
"required": [
163+
"id",
164+
"status"
165+
],
166+
"type": "object",
167+
"properties": {
168+
"id": {
169+
"description": "The unique id of the operation. Use a UUID.",
170+
"type": "string",
171+
"example": "8540c0de-899f-5cce-acb5-3ec493af3800"
172+
},
173+
"status": {
174+
"description": "Status of operation.",
175+
"enum": [
176+
"NotStarted",
177+
"Running",
178+
"Succeeded",
179+
"Failed",
180+
"Canceled"
181+
],
182+
"type": "string",
183+
"x-ms-enum": {
184+
"name": "EmailSendStatus",
185+
"modelAsString": true
186+
}
187+
},
188+
"error": {
189+
"description": "Error details when status is a non-success terminal state.",
190+
"$ref": "../../../../../common-types/data-plane/v1/types.json#/definitions/ErrorDetail"
191+
}
192+
}
193+
},
194+
"EmailMessage": {
195+
"description": "Message payload for sending an email",
196+
"required": [
197+
"senderAddress",
198+
"content",
199+
"recipients"
200+
],
201+
"type": "object",
202+
"properties": {
203+
"headers": {
204+
"description": "Custom email headers to be passed.",
205+
"type": "object",
206+
"additionalProperties": {
207+
"type": "string"
208+
}
209+
},
210+
"senderAddress": {
211+
"description": "Sender email address from a verified domain.",
212+
"type": "string",
213+
"example": "[email protected]"
214+
},
215+
"content": {
216+
"description": "Email content to be sent.",
217+
"$ref": "#/definitions/EmailContent"
218+
},
219+
"recipients": {
220+
"description": "Recipients for the email.",
221+
"$ref": "#/definitions/EmailRecipients"
222+
},
223+
"attachments": {
224+
"description": "List of attachments. Please note that we limit the total size of an email request (which includes attachments) to 10MB.",
225+
"type": "array",
226+
"items": {
227+
"$ref": "#/definitions/EmailAttachment"
228+
}
229+
},
230+
"replyTo": {
231+
"description": "Email addresses where recipients' replies will be sent to.",
232+
"type": "array",
233+
"items": {
234+
"$ref": "#/definitions/EmailAddress"
235+
}
236+
},
237+
"userEngagementTrackingDisabled": {
238+
"description": "Indicates whether user engagement tracking should be disabled for this request if the resource-level user engagement tracking setting was already enabled in the control plane.",
239+
"type": "boolean"
240+
}
241+
}
242+
},
243+
"EmailAddress": {
244+
"description": "An object representing the email address and its display name",
245+
"type": "object",
246+
"required": [
247+
"address"
248+
],
249+
"properties": {
250+
"address": {
251+
"description": "Email address.",
252+
"type": "string",
253+
"example": "[email protected]"
254+
},
255+
"displayName": {
256+
"description": "Email display name.",
257+
"type": "string",
258+
"example": "abc"
259+
}
260+
}
261+
},
262+
"EmailContent": {
263+
"description": "Content of the email.",
264+
"type": "object",
265+
"required": [
266+
"subject"
267+
],
268+
"properties": {
269+
"subject": {
270+
"description": "Subject of the email message",
271+
"type": "string",
272+
"example": "An exciting offer especially for you!"
273+
},
274+
"plainText": {
275+
"description": "Plain text version of the email message.",
276+
"type": "string",
277+
"example": "This exciting offer was created especially for you, our most loyal customer."
278+
},
279+
"html": {
280+
"description": "Html version of the email message.",
281+
"type": "string",
282+
"example": "<html><head><title>Exciting offer!</title></head><body><h1>This exciting offer was created especially for you, our most loyal customer.</h1></body></html>"
283+
}
284+
}
285+
},
286+
"EmailAttachment": {
287+
"description": "Attachment to the email.",
288+
"type": "object",
289+
"required": [
290+
"name",
291+
"contentType",
292+
"contentInBase64"
293+
],
294+
"properties": {
295+
"name": {
296+
"description": "Name of the attachment",
297+
"type": "string",
298+
"example": "attachment.pdf"
299+
},
300+
"contentType": {
301+
"description": "MIME type of the content being attached.",
302+
"type": "string",
303+
"example": "text/plain"
304+
},
305+
"contentInBase64": {
306+
"description": "Base64 encoded contents of the attachment",
307+
"type": "string",
308+
"example": "TWFueSBoYW5kcyBtYWtlIGxpZ2h0I"
309+
}
310+
}
311+
},
312+
"EmailRecipients": {
313+
"description": "Recipients of the email",
314+
"type": "object",
315+
"required": [
316+
"to"
317+
],
318+
"properties": {
319+
"to": {
320+
"description": "Email To recipients",
321+
"type": "array",
322+
"items": {
323+
"$ref": "#/definitions/EmailAddress"
324+
}
325+
},
326+
"cc": {
327+
"description": "Email CC recipients",
328+
"type": "array",
329+
"x-ms-client-name": "CC",
330+
"items": {
331+
"$ref": "#/definitions/EmailAddress"
332+
}
333+
},
334+
"bcc": {
335+
"description": "Email BCC recipients",
336+
"type": "array",
337+
"x-ms-client-name": "BCC",
338+
"items": {
339+
"$ref": "#/definitions/EmailAddress"
340+
}
341+
}
342+
}
343+
}
344+
},
345+
"parameters": {
346+
"ApiVersionParameter": {
347+
"in": "query",
348+
"name": "api-version",
349+
"description": "Version of API to invoke.",
350+
"required": true,
351+
"type": "string",
352+
"x-ms-parameter-location": "client"
353+
}
354+
},
355+
"securityDefinitions": {
356+
"Authorization": {
357+
"type": "apiKey",
358+
"name": "Authorization",
359+
"in": "header",
360+
"description": "An authentication string containing a signature generated using HMAC-SHA256 scheme."
361+
}
362+
},
363+
"security": [
364+
{
365+
"Authorization": []
366+
}
367+
],
368+
"x-ms-parameterized-host": {
369+
"hostTemplate": "{endpoint}",
370+
"useSchemePrefix": false,
371+
"parameters": [
372+
{
373+
"name": "endpoint",
374+
"description": "The communication resource, for example https://my-resource.communication.azure.com",
375+
"required": true,
376+
"type": "string",
377+
"format": "url",
378+
"in": "path",
379+
"x-ms-skip-url-encoding": true,
380+
"x-ms-parameter-location": "client"
381+
}
382+
]
383+
}
384+
}

0 commit comments

Comments
 (0)