0
# pyobjc-framework-MailKit
1
2
Python bindings for Apple's MailKit framework, enabling developers to create mail extensions that integrate with macOS Mail applications. This framework provides comprehensive functionality for message handling, security operations (encryption/signing), compose session management, message actions (flagging, coloring), content blocking, and address annotation capabilities.
3
4
## Package Information
5
6
- **Package Name**: pyobjc-framework-MailKit
7
- **Language**: Python
8
- **Installation**: `pip install pyobjc-framework-MailKit`
9
- **Requirements**: macOS 12.0+, pyobjc-core, pyobjc-framework-Cocoa
10
11
## Core Imports
12
13
```python
14
import MailKit
15
```
16
17
Access specific classes:
18
19
```python
20
from MailKit import (
21
MEMessage, MEComposeSession, MEMessageAction,
22
MEExtensionManager, MEMessageSecurityInformation,
23
MEDecodedMessage, MEEmailAddress
24
)
25
```
26
27
## Basic Usage
28
29
```python
30
import MailKit
31
32
# Create a message security information object
33
security_info = MailKit.MEMessageSecurityInformation.alloc().initWithSigners_isEncrypted_signingError_encryptionError_(
34
signers=[],
35
isEncrypted=True,
36
signingError=None,
37
encryptionError=None
38
)
39
40
# Create a decoded message with security information
41
message = MailKit.MEDecodedMessage.alloc().initWithData_securityInformation_context_(
42
data=message_data,
43
securityInformation=security_info,
44
context=context
45
)
46
47
# Check message encryption state
48
if message_encryption_state == MailKit.MEMessageEncryptionStateEncrypted:
49
print("Message is encrypted")
50
51
# Handle message actions
52
if action_flag == MailKit.MEMessageActionFlagRed:
53
print("Message has red flag")
54
```
55
56
## Architecture
57
58
The MailKit framework follows Apple's Mail extension architecture:
59
60
- **Extension Types**: Message decoders, encoders, security handlers, action handlers, content blockers, and compose handlers
61
- **Protocol-Based Design**: Extensive use of protocols for defining extension capabilities
62
- **Asynchronous Operations**: Completion handler pattern for long-running operations
63
- **Security Integration**: Built-in support for message encryption, signing, and validation
64
- **Mail App Integration**: Direct integration with macOS Mail application workflows
65
66
## Capabilities
67
68
### Message Classes
69
70
Core classes for representing and manipulating mail messages, including message state, encryption information, and decoded message handling.
71
72
```python { .api }
73
class MEMessage: ...
74
class MEDecodedMessage: ...
75
class MEEmailAddress: ...
76
```
77
78
[Message Classes](./message-classes.md)
79
80
### Security and Encryption
81
82
Comprehensive security functionality including message signing, encryption, security information management, and security handler protocols.
83
84
```python { .api }
85
class MEMessageSecurityInformation:
86
def initWithSigners_isEncrypted_signingError_encryptionError_(
87
self, signers, isEncrypted: bool, signingError, encryptionError
88
): ...
89
def isEncrypted(self) -> bool: ...
90
def shouldBlockRemoteContent(self) -> bool: ...
91
92
class MEMessageSigner: ...
93
class MEEncodedOutgoingMessage: ...
94
class MEOutgoingMessageEncodingStatus: ...
95
```
96
97
[Security and Encryption](./security-encryption.md)
98
99
### Message Actions and Flags
100
101
Message action handling including flagging, coloring, and custom action decision workflows.
102
103
```python { .api }
104
class MEMessageAction: ...
105
class MEMessageActionDecision: ...
106
107
# Action flags
108
MEMessageActionFlagNone: int # = 0
109
MEMessageActionFlagDefaultColor: int # = 1
110
MEMessageActionFlagRed: int # = 2
111
MEMessageActionFlagOrange: int # = 3
112
MEMessageActionFlagYellow: int # = 4
113
MEMessageActionFlagGreen: int # = 5
114
MEMessageActionFlagBlue: int # = 6
115
MEMessageActionFlagPurple: int # = 7
116
MEMessageActionFlagGray: int # = 8
117
118
# Message colors
119
MEMessageActionMessageColorNone: int # = 0
120
MEMessageActionMessageColorGreen: int # = 1
121
MEMessageActionMessageColorYellow: int # = 2
122
MEMessageActionMessageColorOrange: int # = 3
123
MEMessageActionMessageColorRed: int # = 4
124
MEMessageActionMessageColorPurple: int # = 5
125
MEMessageActionMessageColorBlue: int # = 6
126
MEMessageActionMessageColorGray: int # = 7
127
```
128
129
[Message Actions](./message-actions.md)
130
131
### Compose Session Management
132
133
Email composition session handling including compose context, session handlers, and address annotation.
134
135
```python { .api }
136
class MEComposeSession: ...
137
class MEComposeContext:
138
def isEncrypted(self) -> bool: ...
139
def shouldEncrypt(self) -> bool: ...
140
def isSigned(self) -> bool: ...
141
def shouldSign(self) -> bool: ...
142
143
class MEAddressAnnotation: ...
144
```
145
146
[Compose Sessions](./compose-sessions.md)
147
148
### Extension Management
149
150
Extension manager for controlling Mail extensions, reloading content blockers, and managing visible messages.
151
152
```python { .api }
153
class MEExtensionManager:
154
def reloadContentBlockerWithIdentifier_completionHandler_(
155
self, identifier: str, completionHandler
156
): ...
157
def reloadVisibleMessagesWithCompletionHandler_(
158
self, completionHandler
159
): ...
160
161
class MEExtensionViewController: ...
162
```
163
164
[Extension Management](./extension-management.md)
165
166
### Protocols and Handlers
167
168
Protocol definitions for creating Mail extensions including message decoders, encoders, security handlers, action handlers, and content blockers.
169
170
```python { .api }
171
# Protocol: MEMessageDecoder
172
def decodedMessageForMessageData_(self, messageData): ...
173
174
# Protocol: MEMessageEncoder
175
def encodeMessage_composeContext_completionHandler_(
176
self, message, composeContext, completionHandler
177
): ...
178
179
# Protocol: MEMessageSecurityHandler
180
def primaryActionClickedForMessageContext_completionHandler_(
181
self, messageContext, completionHandler
182
): ...
183
184
# Protocol: MEMessageActionHandler
185
def decideActionForMessage_completionHandler_(
186
self, message, completionHandler
187
): ...
188
189
# Protocol: MEContentBlocker
190
def contentRulesJSON(self): ...
191
```
192
193
[Protocols and Handlers](./protocols-handlers.md)
194
195
## Constants and Enumerations
196
197
```python { .api }
198
# Message States
199
MEMessageStateReceived: int # = 0
200
MEMessageStateDraft: int # = 1
201
MEMessageStateSending: int # = 2
202
203
# Encryption States
204
MEMessageEncryptionStateUnknown: int # = 0
205
MEMessageEncryptionStateNotEncrypted: int # = 1
206
MEMessageEncryptionStateEncrypted: int # = 2
207
208
# Compose User Actions
209
MEComposeUserActionNewMessage: int # = 1
210
MEComposeUserActionReply: int # = 2
211
MEComposeUserActionReplyAll: int # = 3
212
MEComposeUserActionForward: int # = 4
213
214
# Error Domains
215
MEComposeSessionErrorDomain: str
216
MEMessageSecurityErrorDomain: str
217
218
# Error Codes
219
MEComposeSessionErrorCodeInvalidRecipients: int # = 0
220
MEComposeSessionErrorCodeInvalidHeaders: int # = 1
221
MEComposeSessionErrorCodeInvalidBody: int # = 2
222
MEMessageSecurityEncodingError: int # = 0
223
MEMessageSecurityDecodingError: int # = 1
224
225
# Type annotations for enums
226
from typing import NewType
227
MEMessageSecurityErrorCode = NewType('MEMessageSecurityErrorCode', int)
228
MEMessageActionFlag = NewType('MEMessageActionFlag', int)
229
MEComposeSessionErrorCode = NewType('MEComposeSessionErrorCode', int)
230
MEMessageActionMessageColor = NewType('MEMessageActionMessageColor', int)
231
MEMessageEncryptionState = NewType('MEMessageEncryptionState', int)
232
MEMessageState = NewType('MEMessageState', int)
233
MEComposeUserAction = NewType('MEComposeUserAction', int)
234
```
235
236
This framework enables developers to create sophisticated Mail app extensions that can handle all aspects of email processing, security, and user interaction within the macOS Mail ecosystem.