ser-mail-api 1.0.4

Secure Email Relay Mail API

Proofpoint Secure Email Relay Mail API Package

Library implements all the functions of the SER Email Relay API via Python.

Requirements:

• Python 3.9+
• requests
• requests-oauth2client
• pysocks

Installing the Package

You can install the tool using the following command directly from Github.

pip install git+https://github.com/pfptcommunity/ser-mail-api-python.git

or can install the tool using pip.

# When testing on Ubuntu 24.04 the following will not work:
pip install ser-mail-api

If you see an error similar to the following:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

You should use install pipx or you can configure your own virtual environment and use the command referenced above.

pipx install ser-mail-api

Creating an API client object

from ser_mail_api.v1 import *

if __name__ == "__main__":
    client = Client("<client_id>", "<client_secret>")

Sending an Email Message

import json

from ser_mail_api.v1 import *

if __name__ == "__main__":
    # Load API key
    with open("../ser.api_key", "r") as api_key_file:
        api_key_data = json.load(api_key_file)

    client = Client(api_key_data.get("client_id"), api_key_data.get("client_secret"))

    # Create a new Message object
    message = Message("This is a test email", MailUser("[e-mail]", "Joe Sender"))
    
    # Add content body
    message.add_content(Content("This is a test message", ContentType.Text))
    message.add_content(Content("<b>This is a test message</b>", ContentType.Html))
    
    # Add To
    message.add_to(MailUser("[e-mail]", "Recipient 1"))
    message.add_to(MailUser("[e-mail]", "Recipient 2"))
    
    # Add Cc
    message.add_cc(MailUser("[e-mail]", "Carbon Copy 1"))
    message.add_cc(MailUser("[e-mail]", "Carbon Copy 2"))
    
    # Add Bcc
    message.add_bcc(MailUser("[e-mail]", "Blind Carbon Copy 1"))
    message.add_bcc(MailUser("[e-mail]", "Blind Carbon Copy 2"))

    # Add Base64 encoded attachment
    message.add_attachment(Attachment("VGhpcyBpcyBhIHRlc3Qh", Disposition.Attachment, "test.txt", "text/plain"))

    # Add File attachment from disk, if disposition is not passed, the default is Disposition.Attachment
    message.add_attachment(FileAttachment(r"C:\temp\file.csv", Disposition.Attachment))

    # In the following example, we will create a byte stream from a string. This byte array is converted
    # to base64 encoding within the BinaryAttachment object
    text = "This is a sample text stream."

    # Convert the string into bytes
    bytes = text.encode("utf-8")

    # Add Byte array as attachment, if disposition is not passed, the default is Disposition.Attachment
    message.add_attachment(BinaryAttachment(bytes,"bytes.txt", "text/plain", Disposition.Attachment))

    result = client.send(message)

    print("HTTP Status", result.get_status())
    print("HTTP Reason", result.get_reason())

    print("Reason:", result.reason)
    print("Message ID:", result.message_id)
    print("Request ID:", result.request_id)

The following JSON data is a dump of the message object based on the code above.

{
  "attachments": [
    {
      "content": "VGhpcyBpcyBhIHRlc3Qh",
      "disposition": "attachment",
      "filename": "test.txt",
      "id": "d10205cf-a0a3-4b9e-9a57-253fd8e1c7df",
      "type": "text/plain"
    },
    {
      "content": "77u/IlVzZXIiLCJTZW50Q291bnQiLCJSZWNlaXZlZENvdW50Ig0KIm5vcmVwbHlAcHJvb2Zwb2ludC5jb20sIGxqZXJhYmVrQHBmcHQuaW8iLCIwIiwiMCINCg==",
      "disposition": "attachment",
      "filename": "file.csv",
      "id": "f66487f5-57c2-40e0-9402-5723a85c0df0",
      "type": "application/vnd.ms-excel"
    },
    {
      "content": "VGhpcyBpcyBhIHNhbXBsZSB0ZXh0IHN0cmVhbS4=",
      "disposition": "attachment",
      "filename": "byte_stream.txt",
      "id": "bc67d5fa-345a-4436-9979-5efa68223520",
      "type": "text/plain"
    }
  ],
  "content": [
    {
      "body": "This is a test message",
      "type": "text/plain"
    },
    {
      "body": "<b>This is a test message</b>",
      "type": "text/html"
    }
  ],
  "from": {
    "email": "[e-mail]",
    "name": "Joe Sender"
  },
  "headers": {
    "from": {
      "email": "[e-mail]",
      "name": "Joe Sender"
    }
  },
  "subject": "This is a test email",
  "tos": [
    {
      "email": "[e-mail]",
      "name": "Recipient 1"
    },
    {
      "email": "[e-mail]",
      "name": "Recipient 2"
    }
  ],
  "cc": [
    {
      "email": "[e-mail]",
      "name": "Carbon Copy 1"
    },
    {
      "email": "[e-mail]",
      "name": "Carbon Copy 2"
    }
  ],
  "bcc": [
    {
      "email": "[e-mail]",
      "name": "Blind Carbon Copy 1"
    },
    {
      "email": "[e-mail]",
      "name": "Blind Carbon Copy 2"
    }
  ],
  "replyTos": []
}

Proxy Support

Socks5 Proxy Example:

from ser_mail_api.v1 import *

if __name__ == '__main__':
    client = Client("<client_id>", "<client_secret>")
    credentials = "{}:{}@".format("proxyuser", "proxypass")
    client._session.proxies = {'https': "{}://{}{}:{}".format('socks5', credentials, '<your_proxy>', '8128')}

HTTP Proxy Example (Squid):

from ser_mail_api.v1 import *

if __name__ == '__main__':
    client = Client("<client_id>", "<client_secret>")
    credentials = "{}:{}@".format("proxyuser", "proxypass")
    client._session.proxies = {'https': "{}://{}{}:{}".format('http', credentials, '<your_proxy>', '3128')}

HTTP Timeout Settings

from ser_mail_api.v1 import *

if __name__ == '__main__':
    client = Client("<client_id>", "<client_secret>")
    # Timeout in seconds, connect timeout
    client.timeout = 600
    # Timeout advanced, connect / read timeout
    client.timeout = (3.05, 27)

Limitations

There are no known limitations.

For more information please see: https://api-docs.ser.proofpoint.com/docs/email-submission