API Endpoint

To start sending emails, after you created a template, you should invoke the POST /api/send endpoint, for example:

bash
curl -XPOST \
  -H 'Authorization: Bearer xxxxx' \
  -H "Content-type: application/json" \
  -d '{"recipient":"foo@example.org","subject":"My first email","template":"welcome"}' \
  http://localhost:8000/api/send

That’s it. These above are the only 4 required fields, explained:

Name	Description
`recipient`	The email recipient. It could be a single value or an array of values when using `recipients` instead.
`subject`	The subject of the email.
`template`	The slug of the template to be used.

Sender

By default MailCarrier will use, as sender, the values defined by your environment variables MAIL_FROM_ADDRESS and MAIL_FROM_NAME (which can be empty).
You can override these values at runtime when making an API call by defining the sender property:

js
{
  // Other variables
  "sender": "sender@example.org"
}

Or, specifying the name too:

js
{
  // Other variables
  "sender": {
    "email": "sender@example.org",
    "name": "Sender name"
  }
}

Trigger

You can specify a trigger to know what application sent that specific email. It’s just a plain text field, used only for display and search purposes, but can be very useful when using MailCarrier in a multi-services architecture to keep track of who-sent-what.

js
{
  // Other variables
  "trigger": "App 1"
}

Cc & Bcc

You can specify a cc or bcc by providing their relative keys to your payload:

js
{
  // Other variables
  "cc": "cc@example.org",
  "bcc": "bcc@example.org"
}

Authentication

By default the API endpoint is protected by Laravel Sanctum, an authentication system based on tokens.
To generate a new token you can run the mailcarrier:token command and specify a name (e.g. My service) to quickly understand who’s using it.

js
php artisan mailcarrier:token

Other authentication methods

If you don’t like the default token-based authentication system or want to use something else, you can install one of the several authentication packages available for Laravel or build your own.

For example, you may want to add Machine-to-Machine SSO authentication such as FusionAuth: just follow the README instructions and update the MAILCARRIER_AUTH_GUARD env.