Add more to the API

[jwoertink]

The Sendgrid API has a lot more options than what we're passing currently https://docs.sendgrid.com/api-reference/mail-send/mail-send

Two big ones we miss out on are categories and attachments. There's a few small issues with adding these though. As I was digging around, I noticed some of the docs were actually wrong. For example, one key saying it was a string, but should have said object. The next hurdle is with most of these keys being optional, the compiler starts to get finicky with how they are added.

For example, with the dynamic templates: https://github.com/luckyframework/carbon_sendgrid_adapter/blob/a340557b1f2ef3f1282116a994fa5c5301ef21c3/src/carbon_sendgrid_extensions.cr#L8-L19

You can either define the content with local templates OR use the dynamic templates, but you can't use both. Sendgrid doesn't really like that. So for this, there's basically an if condition to say if these have a value, then do that otherwise fallback to local templates.

I wanted to avoid requiring you to override 50 methods just to get the customization you need on every single email, but the Crystal compiler doesn't really like when you try to define a hash of random unknown types. We can't use JSON::Any because that doesn't allow you to build dynamically e.g. json["extra_args"] = [] of String.

Proposal

I think maybe we could look at breaking this out more like the Bugsnag shard, and each key becomes a new class defined. Then this hash becomes something like Hash(String, Carbon::SendgridAdapter::Value). That could just be a module in each of these classes.

Now, how to hook it in.... I'm not so sure... What does this look like? :man_shrugging:

class SomeEmail < Carbon::Email
  def initialize(@recipient)
  end

  to @recipient
  subject "Hey"
  # does it look like this?
  categories Carbon::SendgridAdapter::Categories.new("1", "2")

  # maybe you take advantage of the new callbacks?
  before_send do
    # `append_data` would have to be a SendgridAdapter specific method
    adapter.append_data("categories", Carbon::SendgridAdapter::Categories.new("1", "2"))
  end
end

[jwoertink]

@robacarp had a good idea for a configure block that just hooks in to it.

class SomeEmail < BaseEmail
  some_specific_sendgrid_deal do |data|
     data.attachments << Sendgrid::Attachments.new("my_face.jpg")
   end

end

It would look something along these lines. That would be specific to this shard.