Skip to content

Commit bf0f8eb

Browse files
AaronDDMAaronDDM
authored
feat: add is_plaintext support for messages send and drafts create endpoints (#436)
- Add is_plaintext property to CreateDraftRequest and SendMessageRequest models - Property defaults to false (HTML) for backwards compatibility - When true, sends message body as plain text without HTML in MIME data - When false, sends message body as HTML with full MIME formatting - Include comprehensive test coverage for both endpoints - Add example demonstrating usage in examples/is_plaintext_demo/ - Update CHANGELOG.md with new feature
1 parent cc8fcc1 commit bf0f8eb

File tree

6 files changed

+580
-1
lines changed

6 files changed

+580
-1
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ Unreleased
55
----------
66
* Added Yahoo, Zoom, EWS as providers to models/auth.py
77
* Fixed grants.update() not using the correct "PATCH" method
8+
* Added support for `is_plaintext` property in messages send and drafts create endpoints
89

910
v6.11.1
1011
----------

‎examples/is_plaintext_demo/README.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# is_plaintext Demo
2+
3+
This example demonstrates the usage of the new `is_plaintext` property for messages and drafts in the Nylas API. This property controls whether message content is sent as plain text or HTML in the MIME data.
4+
5+
## Features Demonstrated
6+
7+
1. **Plain Text Messages**: Shows how to send messages with `is_plaintext=True` to send content as plain text without HTML in MIME data.
8+
2. **HTML Messages**: Demonstrates sending messages with `is_plaintext=False` to include HTML formatting in MIME data.
9+
3. **Backwards Compatibility**: Shows that existing code continues to work without specifying the `is_plaintext` property.
10+
4. **Draft Operations**: Demonstrates using `is_plaintext` with draft creation and updates.
11+
12+
## API Property Overview
13+
14+
### is_plaintext
15+
16+
- **Type**: `boolean`
17+
- **Default**: `false`
18+
- **Available in**:
19+
- `messages.send()` - Send message endpoint
20+
- `drafts.create()` - Create draft endpoint
21+
- `drafts.update()` - Update draft endpoint
22+
23+
When `is_plaintext` is:
24+
- `true`: The message body is sent as plain text and the MIME data doesn't include the HTML version of the message
25+
- `false`: The message body is sent as HTML and MIME data includes HTML formatting
26+
- Not specified: Uses API default behavior (same as `false`)
27+
28+
## Setup
29+
30+
1. Install the SDK in development mode from the repository root:
31+
```bash
32+
cd /path/to/nylas-python
33+
pip install -e .
34+
```
35+
36+
2. Set your environment variables:
37+
```bash
38+
export NYLAS_API_KEY="your_api_key"
39+
export NYLAS_GRANT_ID="your_grant_id"
40+
```
41+
42+
3. Run the example from the repository root:
43+
```bash
44+
python examples/is_plaintext_demo/is_plaintext_example.py
45+
```
46+
47+
## Example Output
48+
49+
```
50+
Demonstrating is_plaintext Property Usage
51+
=======================================
52+
53+
=== Sending Plain Text Message ===
54+
Sending message with is_plaintext=True...
55+
✓ Message request prepared with is_plaintext=True
56+
📧 Message configured to be sent as plain text (MIME without HTML version)
57+
58+
=== Sending HTML Message ===
59+
Sending message with is_plaintext=False (HTML)...
60+
✓ Message request prepared with is_plaintext=False
61+
🌐 Message configured to be sent as HTML (MIME includes HTML version)
62+
63+
=== Backwards Compatibility (No is_plaintext specified) ===
64+
Sending message without is_plaintext property...
65+
✓ Existing code continues to work without modification
66+
67+
=== Creating Plain Text Draft ===
68+
Creating draft with is_plaintext=True...
69+
✓ Draft request prepared with is_plaintext=True
70+
📝 Draft configured to be sent as plain text when sent
71+
72+
Example completed successfully!
73+
```
74+
75+
## Use Cases
76+
77+
### Plain Text (is_plaintext=true)
78+
- **Simple Notifications**: System alerts, password resets, account confirmations
79+
- **Text-Only Emails**: Newsletters or announcements that don't need formatting
80+
- **Lightweight Messaging**: Reduce message size and improve compatibility
81+
- **Accessibility**: Better support for screen readers and text-only email clients
82+
83+
### HTML (is_plaintext=false)
84+
- **Marketing Emails**: Rich formatting, images, and branded content
85+
- **Newsletters**: Complex layouts with multiple sections and styling
86+
- **Transactional Emails**: Formatted receipts, invoices, and reports
87+
- **Interactive Content**: Buttons, links, and styled call-to-action elements
88+
89+
## Code Examples
90+
91+
### Send Plain Text Message
92+
```python
93+
message_request = {
94+
"to": [{"email": "[email protected]", "name": "User"}],
95+
"subject": "Plain Text Notification",
96+
"body": "This is a plain text message.",
97+
"is_plaintext": True
98+
}
99+
100+
response = client.messages.send(
101+
identifier=grant_id,
102+
request_body=message_request
103+
)
104+
```
105+
106+
### Send HTML Message
107+
```python
108+
message_request = {
109+
"to": [{"email": "[email protected]", "name": "User"}],
110+
"subject": "HTML Newsletter",
111+
"body": "<h1>Welcome!</h1><p>This is <strong>HTML</strong> content.</p>",
112+
"is_plaintext": False
113+
}
114+
115+
response = client.messages.send(
116+
identifier=grant_id,
117+
request_body=message_request
118+
)
119+
```
120+
121+
### Create Plain Text Draft
122+
```python
123+
draft_request = {
124+
"to": [{"email": "[email protected]", "name": "User"}],
125+
"subject": "Draft Message",
126+
"body": "This draft will be sent as plain text.",
127+
"is_plaintext": True
128+
}
129+
130+
response = client.drafts.create(
131+
identifier=grant_id,
132+
request_body=draft_request
133+
)
134+
```
135+
136+
## Important Notes
137+
138+
- **Backwards Compatibility**: Existing code without `is_plaintext` continues to work unchanged
139+
- **Default Behavior**: When `is_plaintext` is not specified, it defaults to `false` (HTML)
140+
- **Content Type**: The property affects MIME structure, not just content rendering
141+
- **Safety**: The example includes commented API calls to prevent unintended message sends
142+
143+
## Error Handling
144+
145+
The example includes proper error handling for:
146+
- Missing environment variables
147+
- API authentication errors
148+
- Invalid request parameters
149+
- Network connectivity issues
150+
151+
## Documentation
152+
153+
For more information about the Nylas Python SDK and message properties, visit:
154+
- [Nylas Python SDK Documentation](https://developer.nylas.com/docs/sdks/python/)
155+
- [Nylas API Messages Reference](https://developer.nylas.com/docs/api/v3/ecc/#tag--Messages)
156+
- [Nylas API Drafts Reference](https://developer.nylas.com/docs/api/v3/ecc/#tag--Drafts)

0 commit comments

Comments
 (0)