Stampie is a simple API Wrapper for different email providers such as Postmark and SendGrid.

Overview

Stampie

CI

Stampie is a simple API Wrapper for different email providers such as Postmark and SendGrid.

It is very easy to use and to integrate into your application as demonstrated below with a SendGrid mailer.

Providers



// composer autoloading.
require 'vendor/autoload.php';

class Message extends \Stampie\Message
{
	public function getFrom() { return '[email protected]'; }
	public function getSubject() { return 'You are trying out Stampie'; }
	public function getText() { return 'So what do you think about it?'; }
}

$adapter = new Http\Adapter\Guzzle6\Client();
$mailer = new Stampie\Mailer\SendGrid($adapter, 'username:password');

// Throws an HttpException for error
// messages not recognized by SendGrid api or ApiException for known errors.
$mailer->send(new Message('[email protected]'));

This simple example shows a few different things about how Stampie works under the hood and is developed. Because others are so much better than us to do HTTP communication, Stampie uses the HTTPlug abstraction so you are free to choose between any library like Buzz or Guzzle. See the full list here: https://packagist.org/providers/php-http/client-implementation

Every mailer takes a $serverToken as the second argument in their constructor. This is what is used for authentication. In the Postmark mailer this is a hash but in SendGrid it is a username:password pattern that is split into two pieces and send as arguments. A mailer is responsible for formatting the request needed for a given API.

A Message or MessageInterface is a simple storage class that holds information about the message sent to an API such as the email address this is from and who should receive it together with html and text bodies.

Last there is an Interface for every type of class or abstract implementation that should be used when adding new Mailer's or Adapter's.

Installation

Stampie is not hard coupled to Guzzle or any other library that sends HTTP messages. It uses an abstraction called HTTPlug. This will give you the flexibility to choose what PSR-7 implementation and HTTP client to use.

If you just want to get started quickly you should run the following command:

composer require stampie/stampie php-http/curl-client php-http/message guzzlehttp/psr7

Why requiring so many packages?

Stampie has a dependency on the virtual package php-http/client-implementation which requires to you install an adapter, but we do not care which one. That is an implementation detail in your application. We also need a PSR-7 implementation and a message factory.

You do not have to use the php-http/curl-client if you do not want to. You may use the php-http/guzzle6-adapter or any other library in this list. Read more about the virtual packages, why this is a good idea and about the flexibility it brings at the HTTPlug docs.

Documentation

There is generated API documentation for all tags and released versions. Those can be found at stampie.github.io/Stampie/api/main/.

Extensions

  • Stampie Extra provides extensions to Stampie using the Symfony EventDispatcher component.

Framework integration

Stampie is itself completely decoupled and does not depend on any framework.

Integrations

Testing

Stampie is Continuous Integration tested with GitHub Actions and aims for a high coverage percentage.

Developing

As mentioned above if integrating new mailers or adapters please rely on the interfaces or abstract classes already in this package. Furthermore unit tests should be provided as well.

Feedback

This is a project created to test TDD along the way and maybe have some scars from that. But you are always welcome to send feedback or GitHub, Twitter, GitHub issue or Pull Request. Same goes if something is wrong or you have ideas for a better or smarter implementation.

Comments
  • Attachments

    Attachments

    Adds support for file attachments in messages.

    I've only been able to test it with Postmark, since I don't have an account with the others, but in theory it works with them too – I've poured over the docs for each of them, so it should be correct for all of them.

    There are unit tests for everything new I've added, and I've updated any existing tests for things I've modified. I've tried to match the coding standards already in place, let me know if I've done something differently!

    ~~Major caveat: Buzz isn't supported by this for mailers that use raw POST messages (SendGrid and MailGun). I couldn't figure out in the few minutes I spent looking at it how to just upload files with POST in Buzz (and I'm not the only one). If anyone can figure it out please let me know, but for now this just ignores the attachments and continues like before if you use Buzz. Guzzle should be fine, and Postmark and Mandrill just base64 encode attachments so they should work on Buzz still. Summary: Buzz + SendGrid/MailGun = no attachments~~ Buzz should be working too.

    (There was also an issue preventing the Postmark tests being run – they were being manually included into a different file, so weren't being run. I've fixed that, but they weren't passing, so they pass now too!)

    cc: #2


    Postmark example:

    // Usual setup
    $adapter = new \Stampie\Adapter\Guzzle(new \Guzzle\Service\Client());
    $mailer  = new \Stampie\Mailer\Postmark($adapter, 'apikey');
    $to = new \Stampie\Identity('[email protected]');
    
    $message = new CustomMessage($to); // Implements \Stampie\Message\AttachmentContainerInterface
    $message->setAttachments(array(
        new \Stampie\Attachment('path/to/file.jpg', 'attachment.jpg', 'image/jpg'), // Normal attachment
        new \Stampie\Attachment('path/to/other.jpg', 'other.jpg', 'image/jpg', 'cid:[email protected]'), // Can be embedded using <img src="cid:[email protected]">
    ));
    $mailer->send($message);
    
    opened by adamaveray 22
  • Use HTTPlug

    Use HTTPlug

    This PR removes the HTTP adapters and instead we rely on the HTTP client abstraction HTTPlug. This comes with many benefits:

    • we support far more adapters (like Guzzle 6)
    • we do use PSR7
    • We have less code to test and maintain
    opened by Nyholm 14
  • Adding GuzzleHttp support

    Adding GuzzleHttp support

    Hi @henrikbjorn,

    As GuzzleHttp is out and namespaces change a bit, do you plan to support guzzlehttp/guzzle; which namespace is \GuzzleHttp, and has a modified API compared to guzzle 3.*?

    Tried to do something, but Unit tests are kind of blocking me at this point... :)

    opened by Ninir 14
  • Mandrill Cc/Bcc handling

    Mandrill Cc/Bcc handling

    Hi,

    This adds the implementation of Cc/Bcc for Mandrill. There were 2 ways to do it, as exposed on the Mandrill API doc:

    • Updating the identity to set a type, which is then parsed by Mandrill.
    • Adding a bcc_address option

    I found the first one more maintainable. Not sure how to handle tests in a proper way.

    opened by Ninir 11
  • Make MailerInterface lightweight

    Make MailerInterface lightweight

    This remove the setHttpClient, setServerToken and getServerToken from MailerInterface.

    The MailerInterface contract is now only about sending messages without exposing implementation details to clients.

    Also the MailerInterface::send method no longer returns a boolean. If no exception is thrown, then the message was successfully sent.

    Close #93.

    Todo

    • [x] Update mailers to not return a boolean.
    • [x] Introduce our own exception interface.
    • [x] Add changelog entries.
    opened by fbourigault 10
  • Returning Stampie\Adapter\Response object on successful response.

    Returning Stampie\Adapter\Response object on successful response.

    On receiving a successful response for an email, we send back a boolean true.

    There is a need sometimes to log futther Instead we can send back the Response object and let the 'Message ID' from postmark. Returning back the response object will give more leverage to the calling function.

    Thanks, -Ketan.

    opened by ketanshah79 8
  • Add SparkPost mailer

    Add SparkPost mailer

    One thing I wasn't sure about is what to do with ['options' => ['transactional' => true]] in the payload data.

    It's explained on https://developers.sparkpost.com/api/transmissions.html#transmissions-create-post

    In my case, all mail is transactional, but others using Stampie may be using it for marketing purposes.

    Is there a clean way of making that parameter configurable? Maybe in the message metadata, but that feels sort of dirty.

    opened by simshaun 7
  • [BC break] Simplify the MailerInterface

    [BC break] Simplify the MailerInterface

    @Stampie/collaborators this discussion is about a BC breaking change, so a decision has to be taken before releasing the 1.0 version. If no decision is taken, the release itself will force the decision to be no (at least until 2.0).

    The current MailerInterface looks like this: https://github.com/Stampie/Stampie/blob/293be7036b977be7fbb15e2fcf2140255de2b0c7/lib/MailerInterface.php#L12-L35

    I suggest to simplify it to this:

    interface MailerInterface
    {
        /**
         * @param MessageInterface $message
         *
         * @throws Exception on failure
         */
        public function send(MessageInterface $message): void;
    }
    

    Here are my reasoning for the different changes:

    • forcing the usage of a server token makes it harder to implement things. Each adapter has a different meaning for it (being an API key, a username+password, etc...), meaning that using the getter and setter requires checking the implementation being used anyway (and so the fact that the methods are in the interface is useless). I think the authentication should be an implementation detail of the Mailer: each mailer would be free to take one or multiple parameters for the auth (allowing to split the username and password for instance, which might make it easier to use env variables for instance), and also to decide whether the auth credentials should be mutable and exposed to consuming code (IMO, they should not)
    • the fact that the mailer uses a HTTPlug client should be an implementation detail as well (for instance, in Stampie extra, it does not use a HTTP client, but another Stampie mailer, for which it can fortunately forward the setter, but this is weird), and I see no reason to make it mutable either (so it should be a constructor argument)
    • instantiating a new mailer currently creates a broken object (as mandatory dependencies are not passed in the constructor)
    • the configuration API of mailers is already wider than the MailerInterface (they all have a setMessageFactory setter for instance)
    • returning a boolean from send makes debugging harder because you don't have an explanation on failure. And in practice, our own implementations are already all throwing exceptions on failures instead of returning true. So our signature is already @return true @throws ApiException @throws HttpException in practice. Returning true and never false looks weird. Even if we reject the change from @return true to @return void (with or without return type depending on PHP support), we should at least update the interface to document our actual contract.

    what do you think @Stampie/collaborators ?

    opened by stof 6
  • Verify success from the response content when from API response code is ...

    Verify success from the response content when from API response code is ...

    ...HTTP 200 OK

    Sample 200 OK responses from Mandrill:

    [
        {
            "email": "[email protected]",
            "status": "sent",
            "_id": "e985ec5dbced4fcd9eae1226ec475a55",
            "reject_reason": null
        }
    ]
    
    [
        {
            "email": "[email protected]",
            "status": "rejected",
            "_id": "e985ec5dbced4fcd9eae1226ec475a55",
            "reject_reason": "invalid-sender"
        }
    ]
    
    opened by birla 5
  • MailGun: Bad request error

    MailGun: Bad request error

    I'm getting the following error on using MailGun:

    Fatal error:  Uncaught exception 'Guzzle\Http\Exception\ClientErrorResponseException' with message 'Client error response
    [status code] 400
    [reason phrase] BAD REQUEST
    [url] https://api.mailgun.net/v2/mg.mydomain.com/messages' in vendor\guzzle\guzzle\src\Guzzle\Http\Exception\BadResponseException.php:43
    
    Stack trace:
    
    #0 vendor\guzzle\guzzle\src\Guzzle\Http\Message\Request.php(145): Guzzle\Http\Exception\BadResponseException::factory(Object(Guzzle\Http\Message\EntityEnclosingRequest), Object(Guzzle\Http\Message\Response))
    
    #1 [internal function]: Guzzle\Http\Message\Request::onRequestError(Object(Guzzle\Common\Event), 'request.error', Object(Symfony\Component\EventDispatcher\EventDispatcher))
    
    #2 vendor\symfony\event-dispatcher\Symfony\Component\EventDispatcher\EventDispatcher.php(164): call_user_func(Array, Object(Guzzle\Common\Event), 'request.error', Object(Symfony\Component\EventDispatcher\EventDispatcher))
    
    #3 vendor\symfony\eve in vendor\guzzle\guzzle\src\Guzzle\Http\Exception\BadResponseException.php on line 43
    

    The code is working fine with Mandrill.

    opened by birla 5
  • Tests cleanup

    Tests cleanup

    This aim to clean the test suite to reduce tests complexity.

    @stof is it what you have in mind for #96?

    • [x] Rewrite MailGun tests.
    • [x] Rewrite Mandrill tests.
    • [x] Rewrite Postmark tests.
    • [x] Rewrite SendGrid tests.
    opened by fbourigault 4
Releases(v1.1.0)
Library for using online Email providers

Stampie Stampie is a simple API Wrapper for different email providers such as Postmark and SendGrid. It is very easy to use and to integrate into your

Stampie 288 Dec 31, 2022
SendPortal - Open-source self-hosted email marketing, subscriber and list management, email campaigns and more

SendPortal includes subscriber and list management, email campaigns, message tracking, reports and multiple workspaces/domains in a modern, flexible and scalable application.

Mettle 1.2k Jan 4, 2023
This package adds support for verifying new email addresses: when a user updates its email address, it won't replace the old one until the new one is verified.

Laravel Verify New Email Laravel supports verifying email addresses out of the box. This package adds support for verifying new email addresses. When

Protone Media 300 Dec 30, 2022
Magento 2 Email Catcher or Email Logger Module.

Magento 2 Module Experius email catcher / - logger

Experius 49 Dec 16, 2021
Cross-language email validation. Backed by a database of over 38 000 throwable email domains.

Cross-language temporary (disposable/throwaway) email detection library. Covers 38038+ fake email providers.

Francois-Guillaume Ribreau 1.4k Jan 9, 2023
Mail sending module for Mezzio and Laminas MVC with support for file attachment and template email composition

This module provides an easy and flexible way to send emails from Mezzio and Laminas MVC applications (formerly known as Zend Expressive and Zend MVC). It allows you to pre-configure emails and transports, and then send those emails at runtime.

null 82 Jan 16, 2022
Fetch is a library for reading email and attachments, primarily using the POP and IMAP protocols

Fetch Fetch is a library for reading email and attachments, primarily using the POP and IMAP protocols. Installing N.b. A note on Ubuntu 14.04 (probab

Tedious Developments 501 Jan 4, 2023
📧 Handy email creation and transfer library for PHP with both text and MIME-compliant support.

?? Handy email creation and transfer library for PHP with both text and MIME-compliant support.

Nette Foundation 401 Dec 22, 2022
Omnisend: Ecommerce Email Marketing and SMS Platform

Omnisend Omnisend: Ecommerce Email Marketing and SMS Platform Version v1.x Support all PHP Version >=5.6 v2.x Support all PHP Version >=7.0 Installati

Hung Nguyen 3 Jan 6, 2022
EMAIL, PASSWORD AND USERNAME GENERATOR

Email-Generator EMAIL, PASSWORD AND USERNAME GENERATOR Install on desktop : Install XAMPP Added environment variable system path => C:\xampp\php downl

Alex 2 Jan 8, 2022
PHPMailer – A full-featured email creation and transfer class for PHP

PHPMailer – A full-featured email creation and transfer class for PHP Features Probably the world's most popular code for sending email from PHP! Used

PHPMailer 19.1k Jan 2, 2023
A ready-to-use PHP script for sending Emails with an HTML Template will use a Gmail account as the sender and you will not need any email server. Powered by PHPMailer.

Gmail Email Sender by PHP A ready-to-use PHP script for sending Emails with an HTML Template will use a Gmail account as the sender and you will not n

Max Base 4 Oct 29, 2022
The classic email sending library for PHP

PHPMailer – A full-featured email creation and transfer class for PHP Features Probably the world's most popular code for sending email from PHP! Used

PHPMailer 19k Jan 1, 2023
PHP library for parsing plain text email content.

EmailReplyParser EmailReplyParser is a PHP library for parsing plain text email content, based on GitHub's email_reply_parser library written in Ruby.

William Durand 606 Dec 8, 2022
Send email across all platforms using one interface

Send email across all platforms using one interface. Table Of Content Requirements Installation Providers AmazonSES Mailgun Mailjet Mandrill Postmark

Omnimail 329 Dec 30, 2022
Small PHP library to valid email addresses using a number of methods.

Email Validator Small PHP library to valid email addresses using a number of methods. Features Validates email address Checks for example domains (e.g

James Jackson 154 Dec 31, 2022
Sending Email via Microsoft Exchange Web Services made Easy!

Send Mail via Exchange Web Services! Sending Email via Microsoft Exchange Web Services (EWS) made easy! Installation Install via Composer composer req

Raju Rayhan 19 Jul 19, 2022
Mailcoach is a self-hosted email list manager - in a modern jacket.

Welcome to Mailcoach Mailcoach is a self-hosted email list manager - in a modern jacket. It features: Subscribers and lists management Subscribe, doub

Spatie 3 Jan 31, 2022
An AngularJS / Laravel app - Keyword Based Email forwarder | read/write emails through IMAP

@MailTree Simple mail forwarder. Based on the specific email body/subject keywords forward mails to the list of predefined users. Install Imap Install

Dren Kajmakchi 4 Aug 21, 2018