|
| 1 | +# Mailboxes |
| 2 | + |
| 3 | +This package works by listening for incoming emails from one of the supported drivers and then "reacting" to an incoming email. This happens in custom Mailbox classes - you can think of them as custom route handlers for your emails. |
| 4 | + |
| 5 | +## Defining Mailboxes |
| 6 | + |
| 7 | +You can define your mailboxes in one of your Laravel service providers. For example, within the `boot` method of your `AppServiceProvider`. |
| 8 | + |
| 9 | +```php |
| 10 | +use BeyondCode\Mailbox\InboundEmail; |
| 11 | +use BeyondCode\Mailbox\Facades\Mailbox; |
| 12 | + |
| 13 | +class AppServiceProvider extends ServiceProvider |
| 14 | +{ |
| 15 | + /** |
| 16 | + * Bootstrap any application services. |
| 17 | + * |
| 18 | + * @return void |
| 19 | + */ |
| 20 | + public function boot() |
| 21 | + { |
| 22 | + Mailbox::from(' [email protected]', function (InboundEmail $email) { |
| 23 | + // Handle the incoming email |
| 24 | + }); |
| 25 | + } |
| 26 | +} |
| 27 | +``` |
| 28 | + |
| 29 | +A single mailbox takes care of handling one specific kind of email. You can either define a closure as the second argument, or use an invokable class. This method/class will then get executed every time your application receives an incoming email that matches the mailbox pattern and subject. |
| 30 | + |
| 31 | +## Invokable classes |
| 32 | + |
| 33 | +Instead of the closure based approach, you can also pass a class name as the second argument of the mailbox create methods. This class will then be created and executed: |
| 34 | + |
| 35 | +```php |
| 36 | +Mailbox::from(' [email protected]', MyMailbox::class); |
| 37 | + |
| 38 | +class MyMailbox |
| 39 | +{ |
| 40 | + public function __invoke(InboundEmail $email) |
| 41 | + { |
| 42 | + // Handle the incoming email |
| 43 | + } |
| 44 | +} |
| 45 | +``` |
| 46 | + |
| 47 | +## Matching sender emails |
| 48 | + |
| 49 | +To create a mailbox that matches a specific sender email address, you may use the `Mailbox::from` method. |
| 50 | + |
| 51 | +This mailbox will be called whenever the sender of the email addresses matches. |
| 52 | + |
| 53 | +```php |
| 54 | +Mailbox::from(' [email protected]', MyMailbox::class); |
| 55 | +``` |
| 56 | + |
| 57 | +## Matching recipient emails |
| 58 | + |
| 59 | +To create a mailbox that matches a specific recipient email address, you may use the `Mailbox::to` method. |
| 60 | + |
| 61 | +This mailbox will be called whenever at least one of the email recipients matches. |
| 62 | + |
| 63 | +```php |
| 64 | +Mailbox::to(' [email protected]', MyMailbox::class); |
| 65 | +``` |
| 66 | + |
| 67 | +## Matching CC emails |
| 68 | + |
| 69 | +Similar to matching email recipients, you may also want to restrict your mailbox to the incoming emails CC attribute. Use the `Mailbox::cc` method for this. |
| 70 | + |
| 71 | +This mailbox will be called whenever at least one of the cc recipients matches. |
| 72 | + |
| 73 | +```php |
| 74 | +Mailbox::cc(' [email protected]', MyMailbox::class); |
| 75 | +``` |
| 76 | + |
| 77 | +## Matching the subject |
| 78 | + |
| 79 | +Instead of checking for the email recipients or sender you can also match against the email subject using the `Mailbox::subject` method. |
| 80 | + |
| 81 | +This mailbox will be called whenever the email subject matches. |
| 82 | + |
| 83 | +```php |
| 84 | +Mailbox::subject('Feedback Request', MyMailbox::class); |
| 85 | +``` |
| 86 | + |
| 87 | +## Catch-All |
| 88 | + |
| 89 | +In some cases you might want to create a mailbox that receives all incoming emails, no matter what they contain. |
| 90 | + |
| 91 | +You can use the `Mailbox::catchAll` method for this. This method only receives a closure/class name that will be called every time your application receives an email. |
| 92 | + |
| 93 | +```php |
| 94 | +Mailbox::catchAll(CatchAllMailbox::class); |
| 95 | +``` |
| 96 | + |
| 97 | +## Fallback |
| 98 | + |
| 99 | +Similar to the "catch-all" mailbox, you might also want to create a fallback mailbox that will be called when none of your other mailboxes match the incoming email. While the `catchAll` mailbox will be called for **every** incoming email, the `fallback` mailbox will only be called when no other mailbox matches. |
| 100 | + |
| 101 | +```php |
| 102 | +Mailbox::fallback(FallbackMailbox::class); |
| 103 | +``` |
| 104 | + |
| 105 | +## Using Parameters |
| 106 | + |
| 107 | +In addition to using fixed strings as your mailbox matching rules, you can also use parameters in curly braces - similar to the Laravel routing. |
| 108 | + |
| 109 | +Just wrap the part of the matching rule that you want to capture as a parameter in curly braces and the parameter value will be passed to your invokable class / callback method. |
| 110 | + |
| 111 | +```php |
| 112 | +Mailbox::from('{username}@domain.com', function (InboundEmail $email, $username) { |
| 113 | + |
| 114 | +}); |
| 115 | +``` |
| 116 | + |
| 117 | +## Regular Expression Constraints |
| 118 | + |
| 119 | +You may constrain the format of your mailbox parameters by defining a regular expression in your mailbox definition: |
| 120 | + |
| 121 | +```php |
| 122 | +Mailbox::from('{username}@domain.com', function (InboundEmail $email, $username) { |
| 123 | + |
| 124 | +})->where('username', '[A-Za-z]+') |
| 125 | +``` |
0 commit comments