Fix issue #52: Add new way of sending mails to examples and README.md

Author: Ihor Bilous

README.md

@@ -174,6 +174,46 @@ mail = mt.MailFromTemplate(
 client.send(mail)
 ```
 
+### Sending email directly via SendingApi
+
+This approach is newer. It can be useful when you expect  the response to be model-based rather than dictionary-based, as in MailtrapClient.send().
+
+```python
+import os
+import mailtrap as mt
+
+client = mt.MailtrapClient(token=os.environ["MAILTRAP_API_KEY"])
+sending_api = client.sending_api
+
+# create mail object
+mail = mt.Mail(
+    sender=mt.Address(email="[email protected]", name="John Smith"),
+    to=[mt.Address(email="[email protected]")],
+    subject="You are awesome!",
+    text="Congrats for sending test email with Mailtrap!",
+)
+
+sending_api.send(mail)
+```
+#### Mailtrap sending responses difference
+
+#### 1. `client.send()`
+**Response:**
+```python
+{
+  "success": True,
+  "message_ids": ["5162954175"]
+}
+```
+
+#### 2. `client.sending_api.send()`
+**Response:**
+```python
+SendingMailResponse(success=True, message_ids=["5162955057"])
+```
+
+The same situation applies to both `client.batch_send()` and `client.sending_api.batch_send()`.
+
 ### All usage examples
 
 Refer to the [examples](examples) folder for the source code of this and other advanced examples.

examples/sending/advanced_sending.py

@@ -23,8 +23,6 @@ def get_client(type_: SendingType) -> mt.MailtrapClient:
             sandbox=True,
             inbox_id="<YOUR_INBOX_ID>",
         )
-    else:
-        raise ValueError(f"Invalid sending type: {type_}")
 
 
 # Image should be in the same level in directory like this python file.

examples/sending/batch_advanced_sending.py

@@ -23,8 +23,6 @@ def get_client(type_: SendingType) -> mt.MailtrapClient:
             sandbox=True,
             inbox_id="<YOUR_INBOX_ID>",
         )
-    else:
-        raise ValueError(f"Invalid sending type: {type_}")
 
 
 # Image should be in the same level in directory like this python file.
@@ -82,7 +80,10 @@ def get_client(type_: SendingType) -> mt.MailtrapClient:
     ),
     requests=[
         mt.BatchEmailRequest(
-            to=[mt.Address(email="<RECEIVER_EMAIL>")],
+            to=[mt.Address(email="<RECEIVER_EMAIL_1>")],
+        ),
+        mt.BatchEmailRequest(
+            to=[mt.Address(email="<RECEIVER_EMAIL_2>")],
         ),
     ],
 )

examples/sending/batch_minimal_sending.py

@@ -1,4 +1,5 @@
 import mailtrap as mt
+from mailtrap.models.mail.batch_mail import BatchSendResponse
 
 API_TOKEN = "<YOUR_API_TOKEN>"
 
@@ -18,8 +19,6 @@ def get_client(type_: SendingType) -> mt.MailtrapClient:
         return mt.MailtrapClient(
             token=API_TOKEN, sandbox=True, inbox_id="<YOUR_INBOX_ID>"
         )
-    else:
-        raise ValueError(f"Invalid sending type: {type_}")
 
 
 batch_mail = mt.BatchSendEmailParams(
@@ -31,7 +30,10 @@ def get_client(type_: SendingType) -> mt.MailtrapClient:
     ),
     requests=[
         mt.BatchEmailRequest(
-            to=[mt.Address(email="<RECEIVER_EMAIL>")],
+            to=[mt.Address(email="<RECEIVER_EMAIL_1>")],
+        ),
+        mt.BatchEmailRequest(
+            to=[mt.Address(email="<RECEIVER_EMAIL_2>")],
         ),
     ],
 )
@@ -44,6 +46,14 @@ def batch_send(
     return client.batch_send(mail)
 
 
+def batch_send_via_sending_api(
+    client: mt.MailtrapClient, mail: mt.BaseMail
+) -> BatchSendResponse:
+    """Another way to batch_send email via Sending API"""
+    return client.sending_api.batch_send(mail)
+
+
 if __name__ == "__main__":
     client = get_client(SendingType.DEFAULT)
     print(batch_send(client, batch_mail))
+    print(batch_send_via_sending_api(client, batch_mail))

examples/sending/batch_sending_with_template.py

@@ -18,8 +18,6 @@ def get_client(type_: SendingType) -> mt.MailtrapClient:
         return mt.MailtrapClient(
             token=API_TOKEN, sandbox=True, inbox_id="<YOUR_INBOX_ID>"
         )
-    else:
-        raise ValueError(f"Invalid sending type: {type_}")
 
 
 batch_mail = mt.BatchSendEmailParams(
@@ -37,10 +35,10 @@ def get_client(type_: SendingType) -> mt.MailtrapClient:
     ),
     requests=[
         mt.BatchEmailRequest(
-            to=[mt.Address(email="<RECEIVER_EMAIL>")],
-            subject="You are awesome!",
-            text="Congrats for sending test email with Mailtrap!",
-            category="Integration Test",
+            to=[mt.Address(email="<RECEIVER_EMAIL_1>")],
+        ),
+        mt.BatchEmailRequest(
+            to=[mt.Address(email="<RECEIVER_EMAIL_2>")],
         ),
     ],
 )

examples/sending/minimal_sending.py

@@ -1,4 +1,5 @@
 import mailtrap as mt
+from mailtrap.models.mail.mail import SendingMailResponse
 
 API_TOKEN = "<YOUR_API_TOKEN>"
 
@@ -18,8 +19,6 @@ def get_client(type_: SendingType) -> mt.MailtrapClient:
         return mt.MailtrapClient(
             token=API_TOKEN, sandbox=True, inbox_id="<YOUR_INBOX_ID>"
         )
-    else:
-        raise ValueError(f"Invalid sending type: {type_}")
 
 
 mail = mt.Mail(
@@ -34,6 +33,14 @@ def send(client: mt.MailtrapClient, mail: mt.BaseMail) -> mt.SEND_ENDPOINT_RESPO
     return client.send(mail)
 
 
+def send_via_sending_api(
+    client: mt.MailtrapClient, mail: mt.BaseMail
+) -> SendingMailResponse:
+    """Another way to send email via Sending API"""
+    return client.sending_api.send(mail)
+
+
 if __name__ == "__main__":
     client = get_client(SendingType.DEFAULT)
     print(send(client, mail))
+    print(send_via_sending_api(client, mail))

examples/sending/sending_with_template.py

@@ -18,8 +18,6 @@ def get_client(type_: SendingType) -> mt.MailtrapClient:
         return mt.MailtrapClient(
             token=API_TOKEN, sandbox=True, inbox_id="<YOUR_INBOX_ID>"
         )
-    else:
-        raise ValueError(f"Invalid sending type: {type_}")
 
 
 mail = mt.MailFromTemplate(