SendGrid

Writes

• Send email

  acknowledged

  sendgrid-send-email

  Send one email to the addresses in to, from a sender verified in SendGrid, with a plain-text body and, if given, an HTML body. Every recipient is on the To line and sees the others; there is no cc or bcc. Counted in emails, one per recipient.

• Send template email

  acknowledged

  sendgrid-send-template-email

  Send one email built from a SendGrid dynamic template (id starts with d-, from list-templates) to the addresses in to, filling the template with dynamic_template_data. The subject and body come from the template's active version. Every recipient is on the To line and sees the others. Counted in emails, one per recipient.

• Upsert contacts

  read back

  sendgrid-upsert-contacts

  Add or update Marketing contacts by email, and add each to the lists in list_ids (list-lists); this is how a contact is put on a list. A field left out keeps its value. SendGrid queues the change as a background job and answers with job_id. Counted per contact.

• Delete contact

  read back

  sendgrid-delete-contact

  Delete one Marketing contact by id. Deleting every contact is not offered. SendGrid deletes it in a background job and answers with job_id.

• Create list

  read back

  sendgrid-create-list

  Create one Marketing contact list with a name.

• Rename list

  read back

  sendgrid-rename-list

  Rename one Marketing contact list. Its contacts are unchanged.

• Delete list

  read back

  sendgrid-delete-list

  Delete one Marketing contact list. The contacts on it are kept.

• Remove contact from list

  acknowledged

  sendgrid-remove-contact-from-list

  Take one contact off one Marketing list. The contact itself is kept.

• Add to unsubscribe group

  read back

  sendgrid-add-to-unsubscribe-group

  Unsubscribe one address from one unsubscribe group (list-unsubscribe-groups), so mail sent with that group no longer reaches it.

• Remove from unsubscribe group

  read back

  sendgrid-remove-from-unsubscribe-group

  Subscribe one address to one unsubscribe group again, so mail sent with that group reaches it. Do this when the person asked for it, never on your own.

• Add global unsubscribe

  read back

  sendgrid-add-global-unsubscribe

  Put one address on the global unsubscribe list, so SendGrid sends it no mail at all.

• Remove global unsubscribe

  read back

  sendgrid-remove-global-unsubscribe

  Take one address off the global unsubscribe list, so SendGrid sends it mail again. Do this when the person asked for it, never on your own.

Reads

• Search contacts

  sendgrid-search-contacts

  Find Marketing contacts with a SendGrid SGQL query, for example email LIKE 'ada%' or CONTAINS(list_ids, '<list id>'). Changes nothing (POST search). Returns at most 50 contacts and contact_count, the number that matched. There is no next page: narrow the query instead. Emails are stored in lower case, so write them in lower case. A query that runs over 20 seconds answers 408. A long result can be cut at the response limit.

• Get contacts by email

  sendgrid-get-contacts-by-email

  Get Marketing contacts by exact email address, primary or alternate. Changes nothing (POST search). Takes up to 100 addresses. Returns result, keyed by each address: the contact, or an error for an address with no contact. Answers 404 when no address matches.

• Get contact

  sendgrid-get-contact

  Get one Marketing contact by id: name, email, alternate emails, address fields, list_ids, segment_ids, custom_fields and timestamps. Answers 404 for a contact that does not exist or was deleted.

• Get contact job

  sendgrid-get-contact-job

  Get the status of a contacts job from upsert-contacts or delete-contact, by its job_id: status (pending, completed, errored or failed), job_type (upsert or delete) and counts of contacts requested, created, updated, deleted and errored.

• List lists

  sendgrid-list-lists

  List Marketing contact lists: id, name and contact_count, 50 a page. For the next page, pass the page_token from the _metadata.next URL; with no next, it was the last page.

• Get list

  sendgrid-get-list

  Get one Marketing contact list by id: its name and contact_count.

• List templates

  sendgrid-list-templates

  List dynamic transactional templates (ids start with d-), 20 a page: id, name, updated_at and each version's id, name, subject and whether it is active. For the next page, pass the page_token from _metadata.next. Legacy templates are not listed.

• Get template

  sendgrid-get-template

  Get one transactional template by id, with every version: subject, HTML and plain content, and which version is active. A template with large or many versions can be cut at the response limit.

• List unsubscribe groups

  sendgrid-list-unsubscribe-groups

  List the account's unsubscribe groups (suppression groups): id, name, description, whether it is the default and how many addresses left it. SendGrid returns every group in one response.

• Get email unsubscribe groups

  sendgrid-get-email-unsubscribe-groups

  Get every unsubscribe group for one address, each with suppressed true when the address has left that group.

• Get global unsubscribe

  sendgrid-get-global-unsubscribe

  Check whether one address is on the global unsubscribe list, which stops all mail to it. Returns recipient_email when it is, and an empty object when it is not.

• Get bounce

  sendgrid-get-bounce

  Get the bounce records for one address: when it bounced, the reason and the SMTP status. An empty list means SendGrid has no bounce for it. A bounced address gets no further mail until the bounce is removed in SendGrid.