_ _
    ___  _ __   ___  ___  ___  ___ _ __ ___   __ _(_) |
   / _ \| '_ \ / _ \/ __|/ _ \/ __| '_ ` _ \ / _` | | |
  | (_) | | | |  __/\__ \  __/ (__| | | | | | (_| | | |
   \___/|_| |_|\___||___/\___|\___|_| |_| |_|\__,_|_|_|

onesecmail

The unofficial Python client for the 1secmail API.

Installation

Use the package manager pip to install onesecmail:

pip install onesecmail

Usage

Initialize a OneSecMail object using one of the class methods:

>>> from onesecmail import OneSecMail
>>> # Uses 1secmail's genRandomMailbox action to get a random adress:
>>> mailbox = OneSecMail.get_random_mailbox()
>>> print(mailbox)
<OneSecMail [p8qhrjor@wwjmp.com]>
>>> # Generates a random address using uuid.uuid4():
>>> mailbox = OneSecMail.generate_random_mailbox()
>>> print(mailbox)
<OneSecMail [c05a619fe9a544dab818bde19a74c714@1secmail.net]>
>>> # Creates a mailbox using a pre-determined address:
>>> mailbox = OneSecMail.from_address("c05a619fe9a544dab818bde19a74c714@1secmail.net")
>>> print(mailbox)
<OneSecMail [c05a619fe9a544dab818bde19a74c714@1secmail.net]>

To retrieve a specific email message, you can use the methods OneSecMail.get_message() or OneSecMail.get_message_as_dict():

>>> message = mailbox.get_message(212959953)
>>> print(message)
<EmailMessage; from='contact@yyyyyyyan.tech', subject='Hello!', date='2021-06-25 23:49:12+02:00'>
>>> message.body
'Hi\n'
>>> message_data = mailbox.get_message_as_dict(212959953)
>>> print(message_data)
{'id': 212959953,
 'from': 'contact@yyyyyyyan.tech',
 'subject': 'Hello!',
 'date': '2021-06-25 23:49:12',
 'attachments': [],
 'body': 'Hi!\n',
 'textBody': 'Hi!\n',
 'htmlBody': '',
 'to': '101c71a3206c42668ca7bda6fe225138@1secmail.com'}

To get all messages of a mailbox, use the OneSecMail.get_messages() method:

>>> messages = mailbox.get_messages()
>>> messages
[<EmailMessage; from='contact@yyyyyyyan.tech', subject='Random Email', date='2021-06-28 00:03:27+02:00'>,
 <EmailMessage; from='contact@yyyyyyyan.tech', subject='First Email', date='2021-06-28 01:06:27+02:00'>,
 <EmailMessage; from='yan@orestes.tech', subject='Second Email', date='2021-06-28 01:06:51+02:00'>]

You can also use the get_messages() method to search for email messages, by using validator functions/classes:

>>> from onesecmail.validators import FromAddressValidator
>>> from_validator = FromAddressValidator("contact@yyyyyyyan.tech")
>>> mailbox.get_messages(validators=[from_validator])
[<EmailMessage; from='contact@yyyyyyyan.tech', subject='Random Email', date='2021-06-28 00:03:27+02:00'>,
 <EmailMessage; from='contact@yyyyyyyan.tech', subject='First Email', date='2021-06-28 01:06:27+02:00'>]
>>> from onesecmail.validators import DateRangeValidator
>>> from datetime import datetime
>>> date_validator = DateRangeValidator(min_date=datetime.strptime("2021-06-28 01+02:00", "%Y-%m-%d %H%z"))
>>> mailbox.get_messages(validators=[from_validator, date_validator])
[<EmailMessage; from='contact@yyyyyyyan.tech', subject='First Email', date='2021-06-28 01:06:27+02:00'>]]
>>> from onesecmail.validators import SubjectValidator
>>> mailbox.get_messages(validators=[SubjectValidator("(First|Second) Email")])
[<EmailMessage; from='contact@yyyyyyyan.tech', subject='First Email', date='2021-06-28 01:06:27+02:00'>,
 <EmailMessage; from='yan@orestes.tech', subject='Second Email', date='2021-06-28 01:06:51+02:00'>]]

To download an attachment, use either the download_attachment() method available on both OneSecMail and EmailMessage classes:

>>> message = mailbox.get_message(213684185)
>>> message.attachments
[{'filename': 'attachment.c', 'contentType': 'text/x-csrc', 'size': 2636}]
# These do the same:
>>> message.download_attachment("attachment.c", "local-file.c")
>>> mailbox.download_attachment(213684185, "attachment.c", "local-file.c")

Contributing

Pull Requests are welcome, whether it's regarding features, tests or documentation.

Just make sure you install the pre-commit hooks in your cloned repo before commiting any changes:

git clone https://github.com/yyyyyyyan/onesecmail.git
cd onesecmail
pip install -r requirements_dev.txt
pre-commit install

License

This project is licensed under the MIT License - see the LICENSE file for details.