txt: ## dist_zef-raku-community-modules-Email-SendGrid.md
  [![Actions Status](https://github.com/raku-community-modules/Email-SendGrid/actions/workflows/linux.yml/badge.svg)](https://github.com/raku-community-modules/Email-SendGrid/actions) [![Actions Status](https://github.com/raku-community-modules/Email-SendGrid/actions/workflows/macos.yml/badge.svg)](https://github.com/raku-community-modules/Email-SendGrid/actions) [![Actions Status](https://github.com/raku-community-modules/Email-SendGrid/actions/workflows/windows.yml/badge.svg)](https://github.com/raku-community-modules/Email-SendGrid/actions)
  
  # NAME
  
  Email::SendGrid - Basic email sending via the SendGrid API
  
  # DESCRIPTION
  
  A basic Raku module for sending email using the [SendGrid Web API (v3)](https://www.twilio.com/docs/sendgrid/for-developers/sending-email/api-getting-started).
  
  At the time of writing, SendGrid allows sending up to 100 emails a day free of charge. This module most certainly does not provide full coverage of the SendGrid API; if you need more, pull requests are welcome.
  
  # Usage
  
  Construct an `Eamil::SendGrid` object using your SendGrid API key:
  
  ```
  my $sendgrid = Email::SendGrid.new(api-key => 'your_key_here');
  
  ```
  
  Then call `send-mail` to send email:
  
  ```
  $sendgrid.send-mail:
    from => address('some@address.com', 'Sender name'),
    to => address('target@address.com', 'Recipient name'),
    subject => 'Yay, SendGrid works!',
    content => {
      'text/plain' => 'This is the plain text message',
      'text/html' => '<strong>HTML mail!</strong>'
    };
  
  ```
  
  It is not required to including a HTML version of the body. Optionally, pass `cc`, `bcc`, and `reply-to` to send these addresses. It is also possible to pass a list of up to 1000 addresses to `to`, `cc`, and `bcc`.
  
  If sending the mail fails, an exception will be thrown. Since `Cro::HTTP::Client` is used internally, it will be an exception from that.
  
  ```
  CATCH {
      default {
          note await .response.body;
      }
  }
  
  ```
  
  Pass `:async` to `send-mail` to get a `Promise` back instead. Otherwise, it will be ed for you by `send-mail`.
  
  # Class / Methods reference
  
  ## class Email::SendGrid
  
  A partial implementation of the SendGrid v3 API, sufficient for using it to do basic email sending. Construct it with your API key (passed as the api-key parameter), and optionally a from address to be used for all of the emails sent. Construct with :persistent to use a persistent Cro HTTP client (can give better throughput if sending many emails).
  
  Minimal validation of an email address - simply that it has an @ sign.
  
  ## class Email::SendGrid::Address
  
  Pairs together a name and email address, which are often needed together in the SendGrid API. A name is optional.
  
  Recipient lists may be an address or a list of addresses 1 to 1000 addresses.
  
  ### multi sub address
  
  ```
  multi sub address(
      $email
  ) returns Mu
  
  ```
  
  Construct an Email::SendGrid::Address object from just an email address.
  
  ### multi sub address
  
  ```
  multi sub address(
      $email,
      $name
  ) returns Mu
  
  ```
  
  Construct an Email::SendGrid::Address object from an email address and a name.
  
  ### has Str $.api-key
  
  The SendGrid API key.
  
  ### has Email::SendGrid::Address $.from
  
  The default from address to use.
  
  ### has Cro::HTTP::Client $.client
  
  The Cro HTTP client used for communication.
  
  ### method send-mail
  
  ```
  method send-mail(
      :$to! where { ... },
      :$cc where { ... },
      :$bcc where { ... },
      Email::SendGrid::Address :$from = Code.new,
      Email::SendGrid::Address :$reply-to,
      Str :$subject!,
      :%content!,
      :$async,
      :$sandbox
  ) returns Mu
  
  ```
  
  Send an email. The C, C, and C options may be a single Address object or a list of 1 to 1000 C objects. Only C is required; C is required if there is no object-level from address. Optionally, a C C may be provided. A C is required, as is a C<%content> hash that maps mime types into the matching bodies. If `async` is passed, the call to the API will take place asynchronously, and a C returned.
  
  # AUTHOR
  
  Jonathan Worthington
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2020 Jonathan Worthington
  
  Copyright 2024 Raku Community
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  