[5.2] Allowing passing along transmission options to SparkPost

[djtarazona]

This PR allows specifying an options array in Laravel's services.php to be included in the transmission API request.

'sparkpost' => [
    'secret' => env('SPARKPOST_SECRET'),
    'options' => [
        'open_tracking' => false,
        'click_tracking' => false,
        'transactional' => true,
    ],
],

This is useful for enabling / disabling SparkPost features such as open and click tracking. SparkPost defaults to modifying URLs for click tracking. In my particular Laravel project, we only send transactional emails and would rather not have SparkPost change our links for click tracking. Unfortunately, the only way to disable this functionality (without using SparkPost templates) is to include click_tracking: false in the options JSON attribute for the transmission API request.

Being able to set other options such as marking an email as transactional may be useful to developers as well. Right now, developers would have to extend / override SparkPostTransport for this functionality.

[slakbal]

@djtarazona this rocks! Only a laravel documentation update at the Sparkpost driver section now required. Will save lots of people lots of problems.

[kJamesy]

How do I set this at runtime when queueing messages?

[djtarazona]

@kJamesy setting the options at runtime isn't easy as they can only be set when SparkPostTransport is instantiated which the Laravel Transport Manager will do for you when you attempt to use the SparkPost transport.

[djtarazona]

@kJamesy I opened a PR #16254 to make setting the options at runtime easier.

[kJamesy]

Much obliged.
At what point should I do setOptions()?
Tried it in the build() method of my Mail class but this didn't do the trick whilst queuing.

[djtarazona]

Unfortunately I don't think Mailables have access to the transport that is being used. Mailables describe how to build an email, not how a transport should be used.

I believe you'll have to set the options on the SparkPost transport before you attempt to send the email.

// Set SparkPost transport options before sending email
app('swift.transport')->driver('sparkpost')->setOptions([
    'open_tracking' => false,
    'click_tracking' => false,
    'transactional' => true,
]);

// Send email
Mail::to($request->user())->send(new OrderShipped($order));

If you use the mailer's queue() method, this will be more challenging as the mail sending will be processed on a queue and will lose the settings you set at runtime during the HTTP request. In this case, I suggest creating a Job that is dispatched on the queue and use the send() method (rather than queue()) in the job handler.

Does that help?

Being able to set the transport options on the Mailable class would require more API changes and I'm not sure if Taylor wants Mailables to be tightly coupled to transports (as the options wouldn't apply if a different transport is used such as Mailgun).

[kJamesy]

Yeah, makes sense. Many thanks

[wgmv]

Hi, I have a question regarding the options in services.php. I have set up the options as suggested above:

'sparkpost' => [
        'secret'  => env('SPARKPOST_SECRET'),
        'options' => [
            'open_tracking'  => false,
            'click_tracking' => false,
            'transactional'  => true,
        ],
    ],

but still links get replaced by sparkpost (http://go.sparkpostmail1.com.....) Any suggestions? Does anything else need to be configured? Using laravel 5.4.11, sparkpost free account

PS: also the laravel docs do not mention these options

[CyrilMazur]

@wgmv I dug into the SparkPostTransport class history and found that @taylorotwell removed this feature at this commit 5dace8f#diff-a92e9ec1ecc36811d8edb01394beb2f6

I am still able to set SparkPost options at run time like so:

app('swift.transport')->driver('sparkpost')->setOptions([
    'open_tracking' => false,
    'click_tracking' => false,
    'transactional' => true,
]);

Update:

My bad, Taylor didn't remove the feature, the behaviour is just different, starting from 5.4.0 we need to wrap the config into an additional "options" array like so:

'sparkpost' => [
    'secret' => env('SPARKPOST_SECRET'),
    'options' => [
        'options' => [
            'open_tracking' => false,
            'click_tracking' => false,
            'transactional' => true,
        ]
    ],
],

[djtarazona]

Yes, I think we noticed this in another issue/thread. I consider it a bug and am hoping we can get it fixed. Anyone willing to open a PR? Or maybe @taylorotwell can quick fix?

[CyrilMazur]

I wouldn't call it a bug, it's more a small breaking change between 5.3 and 5.4. Actually it's not bad as it is because that allows us to also specify additional options that are outside of the "options" array, like so:

'sparkpost' => [
    'secret' => env('SPARKPOST_SECRET'),
    'options' => [
        'options' => [
            'open_tracking' => false,
            'click_tracking' => false,
            'transactional' => true,
        ],
        'return_path' => 'bounce@mydomain.com',
        'metadata' => [
            'foo' => 'bar',
        ],
    ],
],

Personally I'm happy I can specify return_path (improves deliverability). Some developers may be happy to pass metadata too.

What's lacking is proper documentation. And maybe the top level "options" array should be renamed to avoid confusion with the SparkPost options array.

[djtarazona]

Got it. Ya better documentation and/or renaming the sparkpost.options key to something else seems like the way to go.