github.com/mailgun/mailgun-go/v3@v3.6.4/mailing_lists.go (about) 1 package mailgun 2 3 import ( 4 "context" 5 "strconv" 6 ) 7 8 // A mailing list may have one of three membership modes. 9 const ( 10 // ReadOnly specifies that nobody, including Members, may send messages to 11 // the mailing list. Messages distributed on such lists come from list 12 // administrator accounts only. 13 AccessLevelReadOnly = "readonly" 14 // Members specifies that only those who subscribe to the mailing list may 15 // send messages. 16 AccessLevelMembers = "members" 17 // Everyone specifies that anyone and everyone may both read and submit 18 // messages to the mailing list, including non-subscribers. 19 AccessLevelEveryone = "everyone" 20 ) 21 22 // Specify the access of a mailing list member 23 type AccessLevel string 24 25 // A List structure provides information for a mailing list. 26 // 27 // AccessLevel may be one of ReadOnly, Members, or Everyone. 28 type MailingList struct { 29 Address string `json:"address,omitempty"` 30 Name string `json:"name,omitempty"` 31 Description string `json:"description,omitempty"` 32 AccessLevel AccessLevel `json:"access_level,omitempty"` 33 CreatedAt RFC2822Time `json:"created_at,omitempty"` 34 MembersCount int `json:"members_count,omitempty"` 35 } 36 37 type listsResponse struct { 38 Items []MailingList `json:"items"` 39 Paging Paging `json:"paging"` 40 } 41 42 type mailingListResponse struct { 43 MailingList MailingList `json:"member"` 44 } 45 46 type ListsIterator struct { 47 listsResponse 48 mg Mailgun 49 err error 50 } 51 52 // ListMailingLists returns the specified set of mailing lists administered by your account. 53 func (mg *MailgunImpl) ListMailingLists(opts *ListOptions) *ListsIterator { 54 r := newHTTPRequest(generatePublicApiUrl(mg, listsEndpoint) + "/pages") 55 r.setClient(mg.Client()) 56 r.setBasicAuth(basicAuthUser, mg.APIKey()) 57 if opts != nil { 58 if opts.Limit != 0 { 59 r.addParameter("limit", strconv.Itoa(opts.Limit)) 60 } 61 } 62 url, err := r.generateUrlWithParameters() 63 return &ListsIterator{ 64 mg: mg, 65 listsResponse: listsResponse{Paging: Paging{Next: url, First: url}}, 66 err: err, 67 } 68 } 69 70 // If an error occurred during iteration `Err()` will return non nil 71 func (li *ListsIterator) Err() error { 72 return li.err 73 } 74 75 // Next retrieves the next page of items from the api. Returns false when there 76 // no more pages to retrieve or if there was an error. Use `.Err()` to retrieve 77 // the error 78 func (li *ListsIterator) Next(ctx context.Context, items *[]MailingList) bool { 79 if li.err != nil { 80 return false 81 } 82 li.err = li.fetch(ctx, li.Paging.Next) 83 if li.err != nil { 84 return false 85 } 86 cpy := make([]MailingList, len(li.Items)) 87 copy(cpy, li.Items) 88 *items = cpy 89 if len(li.Items) == 0 { 90 return false 91 } 92 return true 93 } 94 95 // First retrieves the first page of items from the api. Returns false if there 96 // was an error. It also sets the iterator object to the first page. 97 // Use `.Err()` to retrieve the error. 98 func (li *ListsIterator) First(ctx context.Context, items *[]MailingList) bool { 99 if li.err != nil { 100 return false 101 } 102 li.err = li.fetch(ctx, li.Paging.First) 103 if li.err != nil { 104 return false 105 } 106 cpy := make([]MailingList, len(li.Items)) 107 copy(cpy, li.Items) 108 *items = cpy 109 return true 110 } 111 112 // Last retrieves the last page of items from the api. 113 // Calling Last() is invalid unless you first call First() or Next() 114 // Returns false if there was an error. It also sets the iterator object 115 // to the last page. Use `.Err()` to retrieve the error. 116 func (li *ListsIterator) Last(ctx context.Context, items *[]MailingList) bool { 117 if li.err != nil { 118 return false 119 } 120 li.err = li.fetch(ctx, li.Paging.Last) 121 if li.err != nil { 122 return false 123 } 124 cpy := make([]MailingList, len(li.Items)) 125 copy(cpy, li.Items) 126 *items = cpy 127 return true 128 } 129 130 // Previous retrieves the previous page of items from the api. Returns false when there 131 // no more pages to retrieve or if there was an error. Use `.Err()` to retrieve 132 // the error if any 133 func (li *ListsIterator) Previous(ctx context.Context, items *[]MailingList) bool { 134 if li.err != nil { 135 return false 136 } 137 if li.Paging.Previous == "" { 138 return false 139 } 140 li.err = li.fetch(ctx, li.Paging.Previous) 141 if li.err != nil { 142 return false 143 } 144 cpy := make([]MailingList, len(li.Items)) 145 copy(cpy, li.Items) 146 *items = cpy 147 if len(li.Items) == 0 { 148 return false 149 } 150 return true 151 } 152 153 func (li *ListsIterator) fetch(ctx context.Context, url string) error { 154 r := newHTTPRequest(url) 155 r.setClient(li.mg.Client()) 156 r.setBasicAuth(basicAuthUser, li.mg.APIKey()) 157 158 return getResponseFromJSON(ctx, r, &li.listsResponse) 159 } 160 161 // CreateMailingList creates a new mailing list under your Mailgun account. 162 // You need specify only the Address and Name members of the prototype; 163 // Description, and AccessLevel are optional. 164 // If unspecified, Description remains blank, 165 // while AccessLevel defaults to Everyone. 166 func (mg *MailgunImpl) CreateMailingList(ctx context.Context, prototype MailingList) (MailingList, error) { 167 r := newHTTPRequest(generatePublicApiUrl(mg, listsEndpoint)) 168 r.setClient(mg.Client()) 169 r.setBasicAuth(basicAuthUser, mg.APIKey()) 170 p := newUrlEncodedPayload() 171 if prototype.Address != "" { 172 p.addValue("address", prototype.Address) 173 } 174 if prototype.Name != "" { 175 p.addValue("name", prototype.Name) 176 } 177 if prototype.Description != "" { 178 p.addValue("description", prototype.Description) 179 } 180 if prototype.AccessLevel != "" { 181 p.addValue("access_level", string(prototype.AccessLevel)) 182 } 183 response, err := makePostRequest(ctx, r, p) 184 if err != nil { 185 return MailingList{}, err 186 } 187 var l MailingList 188 err = response.parseFromJSON(&l) 189 return l, err 190 } 191 192 // DeleteMailingList removes all current members of the list, then removes the list itself. 193 // Attempts to send e-mail to the list will fail subsequent to this call. 194 func (mg *MailgunImpl) DeleteMailingList(ctx context.Context, addr string) error { 195 r := newHTTPRequest(generatePublicApiUrl(mg, listsEndpoint) + "/" + addr) 196 r.setClient(mg.Client()) 197 r.setBasicAuth(basicAuthUser, mg.APIKey()) 198 _, err := makeDeleteRequest(ctx, r) 199 return err 200 } 201 202 // GetMailingList allows your application to recover the complete List structure 203 // representing a mailing list, so long as you have its e-mail address. 204 func (mg *MailgunImpl) GetMailingList(ctx context.Context, addr string) (MailingList, error) { 205 r := newHTTPRequest(generatePublicApiUrl(mg, listsEndpoint) + "/" + addr) 206 r.setClient(mg.Client()) 207 r.setBasicAuth(basicAuthUser, mg.APIKey()) 208 response, err := makeGetRequest(ctx, r) 209 if err != nil { 210 return MailingList{}, err 211 } 212 213 var resp mailingListResponse 214 err = response.parseFromJSON(&resp) 215 return resp.MailingList, err 216 } 217 218 // UpdateMailingList allows you to change various attributes of a list. 219 // Address, Name, Description, and AccessLevel are all optional; 220 // only those fields which are set in the prototype will change. 221 // 222 // Be careful! If changing the address of a mailing list, 223 // e-mail sent to the old address will not succeed. 224 // Make sure you account for the change accordingly. 225 func (mg *MailgunImpl) UpdateMailingList(ctx context.Context, addr string, prototype MailingList) (MailingList, error) { 226 r := newHTTPRequest(generatePublicApiUrl(mg, listsEndpoint) + "/" + addr) 227 r.setClient(mg.Client()) 228 r.setBasicAuth(basicAuthUser, mg.APIKey()) 229 p := newUrlEncodedPayload() 230 if prototype.Address != "" { 231 p.addValue("address", prototype.Address) 232 } 233 if prototype.Name != "" { 234 p.addValue("name", prototype.Name) 235 } 236 if prototype.Description != "" { 237 p.addValue("description", prototype.Description) 238 } 239 if prototype.AccessLevel != "" { 240 p.addValue("access_level", string(prototype.AccessLevel)) 241 } 242 var l MailingList 243 response, err := makePutRequest(ctx, r, p) 244 if err != nil { 245 return l, err 246 } 247 err = response.parseFromJSON(&l) 248 return l, err 249 }