New subscriber endpoint (part 1)

[TylerMatteo]

Add new endpoint to ZAP Search API that creates a new contact in SendGrid and adds that user to the List for the current ZAP Search environment.

New endpoint should exist as a POST to /subscribers and take in a POST body with shape:

{
  "email": "john@example.com"
}

• [ ] Add SendGrid API key to ZAP Search back end as environment variable. API Key is availabe in SendGrid 1PW vault under "ZAP Search Staging SendGrid API Key"
• [ ] Add environment-specific List ID as environment variable

List names are zap-subscribers-staging for staging and zap-subscribers-production for production.

Validation

The endpoint should perform the following validations on the supplied POST body and return the given error codes

• [ ] Confirm that provided email is a valid email address string. If invalid, return 400 Bad Request error response
• [ ] Confirm that supplied email address is not already a subscriber. Because we use SG in other projects, we can't rely on simply looking for a SG contact with the supplied email. Instead, a subscriber is considered to already exist if we have a contact with the given email and that email is already on the list for the current environment. If subscriber already exists, return 409 Conflict error response

Adding subscriber

• [ ] Given a call with valid data, a contact is added to SG and the contact is added to the correct List. Return 200 success response code.

Once data is validated, the subscriber should be created and added to the list. See SendGrid docs for adding/updating a contact here. Note that request body can take in List IDs that the contact should be added to.

Note the following from SG's docs describing how contact creation is an asynchronous process:

Because the creation and update of contacts is an asynchronous process, the response will not contain immediate feedback on the processing of your upserted contacts. Rather, it will contain an HTTP 202 response indicating the contacts are queued for processing or an HTTP 4XX error containing validation errors. Should you wish to get the resulting contact's ID or confirm that your contacts have been updated or added, you can use the Get Contacts by Identifiers operation.

Our endpoint should still be synchronous, so endpoint code may require implementing polling with a max wait time. Let's start with 3 seconds and see how fast SG's APIs are.

[TylerMatteo]

@dhochbaum-dcp it might be worth testing how long it takes SG to actually create the contact by calling the endpoints with curl or something like Postman. If it's too long to have our endpoint by synchronous, we can pivot accordingly, but testing ahead of time could save you the effort of writing the polling code if we don't actually need it.