Setup

Before you get started.

GovDelivery Implementation Consultants will walk you and your team through all the steps for a successful launch. Most implementations run approximately 8 - 12 weeks from start to finish, with regular meetings between the GovDelivery team and your agency's software development team during this time.

Keep reading for a preview of what to expect and ways to prepare.

What's in this section.

What your agency will do What GovDelivery will do
Setup your subdomain to send messages Create a staging and production environment
Setup your "from" address Provide authorization tokens
Setup your auto-response message Provide Stage and Production endpoints
Update firewall rules

What your agency will do

1. Create and set up your subdomain.

The subdomain is where your email messages will be sent from (e.g. messages.statedept.gov). It should relate to your main domain (e.g. statedept.gov), but be separate to avoid inundating your primary domain. Dedicated subdomains keep your messages well-managed, organized, efficient, and the delivery of your message successful.

Create a subdomain dedicated to sending your email messages (e.g. messages.statedept.gov), update the SPF records to include GovDelivery, and add a GovDelivery-specific MX record (provided during implementation) so that traffic is managed through the GovDelivery sending infrastructure.

Alternatively, we offer use of GovDelivery's public domain (public.govdelivery.com) in combination with a unique “from” address. If the subdomain cannot be updated, then the GovDelivery public domain is used.

2. Setup your “from” address.

Every email is sent from a “from” address. This is the part of an email address before the @ symbol.

Choose a “from” address that reflects what’s in the email and gives citizens confidence that the source is official. For example, newsletter@messages.statedept.gov or notifications@messages.dmv.gov. For customers using the GovDelivery public domain, we’ll help you choose a unique “from” address.

3. Setup your auto-response message.

Often, citizens want to respond directly to the email that gave them the information. Their response will go to the “from” address, which is usually an unmaintained email.

Instead of citizens sending an email to get no response, you can set up an auto-response message that redirects them. Good auto-responses include a welcoming greeting, frequent questions and their answers, proper channels of contact, and a call to action.

4. Update firewall rules.

Don’t worry, this isn’t a security breach--we take security extremely seriously. However, the TMS API is an application outside of your internal network. Most firewalls are set up to allow use of just a few trusted websites (like Google or email) and block other sites not within the firewall rules. Unless a site is first cleared as a trusted source, it’s kept out. That means the firewall may block TMS as a perceived threat.

We encourage keeping a strong, secure firewall and only add your TMS staging and production sites to the list of allowed sites. Add tms.govdelivery.com and stage-tms.govdelivery.com to your firewall rules. You will also need to add tms.govdelivery.com/webhooks if you plan to enable webhooks (optional).

Once these steps are complete, you are ready to implement the API calls.

What the GovDelivery team will do.

1. Create a staging and production environment.

We'll provide two environments for your team to integrate your application against our TMS platform. The Staging environment is used during the development phase of your integration. Within the Staging environment you can send test messages and load test your application. Testing is helpful for surfacing small details that easily fall through the cracks or exposing bigger message errors.

The production environment is where messages are directly sent to actual recipients. We recommend first sending in the staging environment, and then sending in the production environment.

2. Provide authorization tokens.

Access to TMS is only granted with a secure authentication token. Your TMS staging and production environments each have unique authentication tokens.

Once your environments are created, we’ll provide your tokens as well as the endpoint to the API. Be careful who gets access to your token. Only share with trusted team members who need it to perform their duties.

Never include your token in an email, and double-check that sample code doesn’t expose your authentication token. This is the most common way authentication tokens are compromised, exposing agencies to security risk.

If a token is lost or otherwise compromised, please contact our team immediately to block the compromised token and provide a replacement.

3. Confirm subdomain and DKIM configuration.

Once your subdomain is setup, we’ll confirm it by checking the SPF record was updated to include GovDelivery and a GovDelivery-specific MX record is applied so that message traffic is sent through GovDelivery’s infrastructure.

In addition, we'll create a DKIM key for the new subdomain. DKIM (DomainKey Identified Mail) is a method of digital verification used to ensure that an email message is authentically associated with the domain name it is sent from.

It gives email service providers better confidence in our messaging which translates into better and faster deliverability, and also creates a layer of security. Once the key has been created and verified we will provide it to your team to update your DNS.