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.