Download the PHP package popphp/pop-mail without Composer

pop-mail

• Overview
• Install
• Quickstart
• Messages
• Mailer
• Transports
  • Mailgun
  • Sendgrid
  • Office 365
  • AWS SES
  • Google
  • SMTP
  • Sendmail
• Clients
  • Office 365 Client
  • Google Client
  • IMAP/POP3
• Mail Queues
• Saving Mail

Overview

pop-mail is the main mail component for the Pop PHP Framework. It provides a robust set of features to manage the many aspects of sending and receiving mail over the internet. It provides functionality for the following:

• Messages
  • Create mail messages with multiple mime types and attachments
  • Send the messages through the mailer object, or save mail messages to be sent later
  • Send the messages through a queue with multiple recipients
• Mail Transports
  • Manage sending mail messages from a server-to-server application connection*
  • Send emails to a queue of recipients, with individual message customization
  • The available mail transports are interchangeable:
  • Mailgun Transport: utilizes the Mailgun API
  • Sendgrid Transport: utilizes the Sendgrid API
  • Office 365 Transport: utilizes the Office 365 Mail API
  • AWS SES Transport: utilizes the AWS SDK
  • Google Transport: utilizes the Gmail API
  • SMTP Transport: utilizes a standard SMTP connection
  • Sendmail Transport: utilizes a basic Sendmail connection
• Mail Clients
  • Manage mailboxes, their messages, data, attachments and statuses from a server-to-server application connection*
  • Office 365 Client: utilizes the Office 365 Mail API
  • Google Client: utilizes the Gmail API
  • IMAP/POP3 Client: utilizes a standard IMAP or POP3 connection (for security purposes, IMAP & POP3 are not as widely supported anymore and their usage has been deprecated in some popular enterprise mail platforms)

* - NOTE: The main use-case for this component is that of a server-to-server application connection. This means that the component would be used with an application that has been granted the appropriate access and permissions to act on behalf of the user or users whose emails are being managed by the application. This component is not geared towards an individual user mail application use-case. Please refer to the online documentation, guidelines and polices for whichever mail platforms to which you are attempting to connect your application using this component. Please take care in granting access and assigning permissions to your application instance. Always follow the recommended security policies and guidelines of your chosen mail platform.

pop-mail is a component of the Pop PHP Framework.

Install

Install pop-mail using Composer.

composer require popphp/pop-mail

Or, require it in your composer.json file

"require": {
    "popphp/pop-mail" : "^4.0.0"
}

Top

Quickstart

Example 1: Sending a message via the Mailgun API

Example 2: Sending a message via an SMTP connection

Top

Messages

Message objects can be created and passed to a mailer object to be sent by an application.

Create a simple text mail message:

Create a mail message with both text and HTML parts:

Create a mail message with a file attachment:

Create a mail message with a file attachment from a stream of file contents:

Top

Mailer

Once a message object is created, it can be passed to a mailer object to be sent. The mailer object will require a transport object to perform the required tasks to send the message through the provided mail platform.

Top

Transports

The available transports all share the same interface and are interchangeable. However, they each require different configuration that adheres to the specifications of their mail platform.

Mailgun

The Mailgun transport requires an api_url and api_key. The API key is obtained from the Mailgun administration portal. The Mailgun API URL is typically a string comprised of your approved mail domain, for example:

Top

Sendgrid

The Sendgrid transport requires an api_url and api_key. These values are obtained from the Sendgrid administration portal.

Top

Office 365

The Office 365 transport requires a few more configuration options that are obtained for the approved application from within the Office 365 administration portal. You will need the following:

• Client ID
• Client Secret
• Scope (This is typically something like https://graph.microsoft.com/.default)
• Tenant ID
• Account ID (This is typically the object_id of the user mailbox that is being used)

You can create an Office 365 transport object and then request and store the required token for future requests:

When calling the Office 365 transport object at a later time, you can reuse the token (if it hasn't expired):

If the token has expired, the transport object will automatically refresh it. At this point, you can fetch the new token and its expiration from the transport object and store them.

Top

AWS SES

The AWS SES transport requires a key and secret that are obtained from the AWS SES admin console.

Top

Google

The Google transport requires a number of configuration steps to be performed in the Google administration portal and cloud console. This includes setting up the approved application as a service account and its necessary requirements. When that is complete, you should be prompted to download a JSON file with the appropriate credentials and data for your application:

You can pass the JSON file directly into Google transport object, along with the user email being used. From there, you can request and store the required token for future requests:

When calling the Google transport object at a later time, you can reuse the token (if it hasn't expired):

If the token has expired, the transport object will automatically refresh it. At this point, you can fetch the new token and its expiration from the transport object and store them.

Top

SMTP

The SMTP transport requires the standard configuration parameters for a typical SMTP connection:

Sendmail

Sendmail is the most basic transport. It is not used very often and is not recommended, but could be utilized within testing and dev environments. It leverages the sendmail application running on the server, so it is required that it be set up and configured properly on the server and within PHP for use with PHP's mail function. If needed, you can pass a string of $params into the constructor that will be passed on to the mail function call.

Top

Clients

The available mail clients can be used for monitoring mailboxes and their message content from within an application.

Office 365 Client

Like the Office 365 transport, the Office 365 clients requires a few configuration options that are obtained for the approved application from within the Office 365 administration portal. You will need the following:

• Client ID
• Client Secret
• Scope (This is typically something like https://graph.microsoft.com/.default)
• Tenant ID
• Account ID (This is typically the object_id of the user mailbox that is being used)

You can create an Office 365 client object and then request and store the required token for future requests:

When calling the Office 365 client object at a later time, you can reuse the token (if it hasn't expired):

If the token has expired, the client object will automatically refresh it. At this point, you can fetch the new token and its expiration from the client object and store them.

From there you can interact with the client to fetch messages and their content.

Get messages

Search for unread messages only, limit 5:

Get a message

When the messages are returned, they will have any ID associated with them. Use that to get an individual message:

You can get the raw message as well:

Get a message's attachments

Get an attachment

When the message's attachments are returned, they will have any ID associated with them. Use that to get an individual message attachment:

Top

Google Client

Like the Google transport, the Google client requires a number of configuration steps to be performed in the Google administration portal and cloud console. This includes setting up the approved application as a service account and its necessary requirements. When that is complete, you should be prompted to download a JSON file with the appropriate credentials and data for your application:

You can pass the JSON file directly into Google client object, along with the user email being used. From there, you can request and store the required token for future requests:

When calling the Google client object at a later time, you can reuse the token (if it hasn't expired):

If the token has expired, the client object will automatically refresh it. At this point, you can fetch the new token and its expiration from the client object and store them.

From there you can interact with the client to fetch messages and their content.

Get messages

Search for unread messages only, limit 5:

Get a message

When the messages are returned, they will have any ID associated with them. Use that to get an individual message:

You can get the raw message as well:

Get a message's attachments

Get an attachment

When the message's attachments are returned, they will have any ID associated with them. Use that to get an individual message attachment:

Top

IMAP/POP3

IMAP & POP3 clients are available, but are becoming less supported. Their usage has been deprecated in some popular enterprise mail platforms. Use with caution.

Top

Mail Queues

You can create a mail queue to manage and send messages to multiple recipients at the same time. The benefit is that the body of the messages can contain placeholders that can be swapped for individual user data for customization and a better user experience.

Top

Saving Mail

By saving mail messages to a storage location within your application, you can call them up at a later date and time to send them from that location.

Top