DOCSEARCHbyAlgolia
Submit Docs

sendgrid-go

repository·main·Indexed 21 days ago

https://github.com/sendgrid/sendgrid-go

A Go client library for interacting with the Twilio SendGrid Web API v3. It provides high-level helpers for common tasks such as sending emails via the mail helper, managing SecureWebhook features with the eventwebhook helper, and processing Inbound Parse webhook data with the inbound helper, as well as low-level access for direct API requests.

Tokens
75.3K
Snippets
196
Records
211
Agent score
74%

What's inside sendgrid-go

  2. Explore SendGrid Email Use Cases

    main
    The sendgrid-go repository provides documentation and examples for various common email implementation patterns. These include managing transactional templates, handling personalizations, using custom arguments, and managing attachments. You can find detailed guides for each of these specific workflows in the use-cases/ directory.

  3. Use the mail helper to build Mail objects

    main

    The mail helper package provides utilities to quickly and easily construct Mail objects required for sending emails via the Twilio SendGrid API. It simplifies the process of setting up the complex nested structures used in the SendGrid Mail Send API.

    To use this helper, ensure you have the rest dependency installed and your SENDGRID_API_KEY environment variable configured.

  4. Use the Event Webhook helper to manage SecureWebhook features

    main

    The eventwebhook helper provides functionality to enable or disable the SecureWebhook feature and retrieve the public key from Twilio SendGrid. This is useful for verifying the authenticity of event webhooks sent by SendGrid.

    Dependencies:

    • github.com/sendgrid/rest

  5. Manage Twilio SendGrid API Key via environment variables

    main

    It is recommended to use environment variables to store your SENDGRID_API_KEY rather than hardcoding it.

    When using os.Getenv("SENDGRID_API_KEY"), the code is looking for the name of the environment variable. If you hardcode the string, you are providing the actual API key value directly.

  6. Version management and SemVer

    main
    The library follows Semantic Versioning (MAJOR.MINOR.PATCH). It is highly recommended to pin or vendor the specific version you are using in your code to prevent breaking changes from automatic updates, especially during MAJOR version releases.

  7. Manage IP Access Settings

    main

    IP Access Management allows you to control which IP addresses can access your account via the UI or API. You can whitelist specific IPs, retrieve activity logs, or manage existing whitelist rules.

    Warning: It is possible to remove your own IP address from the whitelist, which will prevent you from accessing your account.

  8. Manage subuser link branding associations

    main

    Link branding can be associated with subusers from a parent account. This allows subusers to send mail using the parent's branded links.

    • Retrieve associated branding: Use GET /v3/whitelabel/links/subuser with a username query parameter.
    • Associate branding: Use POST /v3/whitelabel/links/{link_id}/subuser with a JSON body containing the username.
    • Disassociate branding: Use DELETE /v3/whitelabel/links/subuser with a username query parameter.
    // Associate a link branding with a subuser
request := sendgrid.GetRequest(apiKey, "/v3/whitelabel/links/{link_id}/subuser", host)
request.Method = "POST"
request.Body = []byte(` {\n  "username": "jane@example.com"\n}`)
response, err := sendgrid.API(request)

  9. Understand the ParsedEmail data structure

    main

    The ParsedEmail struct contains several fields for accessing different parts of the inbound email. Use the following guide to choose the correct field for your needs:

    FieldDescription
    Envelope.To / Envelope.FromExact email addresses. These are safe to use without further parsing.
    ParsedValuesPre-parsed fields provided by SendGrid. Recommended over Headers for consistency.
    TextBodyThe email body pre-parsed into a plain text string separated by \n.
    ParsedAttachmentsPopulated only when using ParseWithAttachments(). Provides File (the content), Size, Filename, and ContentType.
    BodyPopulated only if 'Raw' is enabled in the SendGrid Dashboard. Contains the raw HTML body.
    AttachmentsDEPRECATED. Use ParsedAttachments instead.
    HeadersDEPRECATED. Use ParsedValues instead. Raw headers may be inconsistent across email clients (e.g., Outlook.com).

    Note on Attachments: To access attachment data easily without requiring the 'Raw' setting in your SendGrid Dashboard, use ParsedAttachments via the ParseWithAttachments() function.

  10. Make API calls on behalf of a subuser

    main

    The on-behalf-of functionality allows you to perform actions for a specific subuser using your parent account credentials. This is useful for automation without changing authentication keys.

    Use sendgrid.GetRequestSubuser to implement this.

    Note: The v3/mail/send endpoint does not support the on-behalf-of header.

    request := sendgrid.GetRequestSubuser(
	os.Getenv("SENDGRID_API_KEY"), "/v3/tracking_settings/subscription", 
	"https://api.sendgrid.com", "SUBUSER_USERNAME",
)

  11. Manage Alerts

    main

    Alerts allow you to receive notifications regarding your email usage or statistics. There are two main types:

    • Usage alerts: Set a threshold to trigger a notification.
    • Stats notifications: Set a frequency (e.g., daily, weekly, monthly) to receive email statistics reports.

  12. Manage IP Pools

    main

    IP Pools allow you to group dedicated Twilio SendGrid IP addresses together to maintain separate reputations for different types of traffic (e.g., transactional vs. marketing). Each user can create up to 10 IP pools. IP pools can only be used with authenticated IP addresses. If no pool is specified for an email, SendGrid will use any available IP, including those in pools.

    Available operations:

    • Create a pool: POST /v3/ips/pools
    • Retrieve all pools: GET /v3/ips/pools
    • Update a pool name: PUT /v3/ips/pools/{pool_name}
    • Retrieve all IPs in a pool: GET /v3/ips/pools/{pool_name}
    • Delete a pool: DELETE /v3/ips/pools/{pool_name}
    // Example: Create an IP pool named 'marketing'
request := sendgrid.GetRequest(apiKey, "/v3/ips/pools", host)
request.Method = "POST"
request.Body = []byte(` {
  "name": "marketing"
}`) 
response, err := sendgrid.API(request)