# Add recipients ## API Overview > \[!WARNING] > > This covers the obsolete Legacy Marketing Campaigns API. > \[!NOTE] > > For the most up-to-date information on the Contacts API, please visit the [new Marketing Campaigns Contacts API](/docs/sendgrid/api-reference/contacts). The Contacts Recipients API allows you to manage your recipients. You can add, retrieve, update, and delete recipients, as well as get a count of all recipients and all billable recipients. ## Operation overview ```json {"path":"https://api.sendgrid.com/v3/contactdb/recipients","method":"post","servers":[{"url":"https://api.sendgrid.com","description":"The Twilio SendGrid v3 API"}]} ``` **This endpoint allows you to add a Marketing Campaigns recipient.** You can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides. The rate limit is three requests every 2 seconds. You can upload 1000 contacts per request. So the maximum upload rate is 1500 recipients per second. ## Operation details ### Authentication API Key ### Headers ```json [{"in":"header","name":"Authorization","required":true,"default":"Bearer <>","schema":{"type":"string"}},{"name":"on-behalf-of","in":"header","description":"The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be \"account-id\" followed by the customer account's ID (e.g., `on-behalf-of: account-id `). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: `). See [**On Behalf Of**](/docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.","required":false,"schema":{"type":"string"},"refName":"#/components/parameters/OnBehalfOf","modelName":"__components_parameters_OnBehalfOf"}] ``` ### Request body ```json {"schema":{"type":"array","example":[{"email":"example@example.com","first_name":"","last_name":"User","age":25},{"email":"example2@example.com","first_name":"Example","last_name":"User","age":25}],"items":{"type":"object","required":["email"],"properties":{"email":{"type":"string","description":"The email address of the recipient.","format":"email"},"first_name":{"type":"string","description":"The first name of the recipient."},"last_name":{"type":"string","description":"The last name of the recipient."},"age":{"type":"integer"}}}},"encodingType":"application/json"} ``` ### Responses ```json [{"responseCode":"201","schema":{"description":"","content":{"application/json":{"schema":{"title":"ContactDB: Recipient response","type":"object","required":["error_count","new_count","persisted_recipients","updated_count"],"example":{"error_count":1,"error_indices":[2],"new_count":2,"persisted_recipients":["YUBh","bWlsbGVyQG1pbGxlci50ZXN0"],"updated_count":0,"errors":[{"message":"Invalid email.","error_indices":[2]}]},"refName":"ContactdbRecipientResponse201","modelName":"ContactdbRecipientResponse201","properties":{"error_count":{"type":"number","default":0,"description":"The number of errors found while adding recipients."},"error_indices":{"type":"array","default":[],"description":"The indices of the recipient(s) sent that caused the error. ","items":{"type":"number"}},"new_count":{"type":"number","default":0,"description":"The count of new recipients added to the contactdb."},"persisted_recipients":{"type":"array","default":[],"description":"The recipient IDs of the recipients that already existed from this request.","items":{"type":"string"}},"updated_count":{"type":"number","default":0,"description":"The recipients who were updated from this request."},"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"error_indices":{"type":"array","items":{"type":"number"}}}}}}},"examples":{"response":{"value":{"error_count":1,"error_indices":[2],"new_count":2,"persisted_recipients":["YUBh","bWlsbGVyQG1pbGxlci50ZXN0"],"updated_count":0,"errors":[{"message":"Invalid email.","error_indices":[2]}]}}}}}}},{"responseCode":"400","schema":{"description":"The request body is not valid json","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}},"examples":{"response":{"value":{"errors":[{"field":null,"message":"Request body is not valid json"}]}}}}}}},{"responseCode":"401","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}},"examples":{"response":{"value":{"errors":[{"field":null,"message":"authorization required"}]}}}}}}}] ``` Add recipients ```js const client = require("@sendgrid/client"); client.setApiKey(process.env.SENDGRID_API_KEY); const data = [ { email: "example@example.com", first_name: "", last_name: "User", age: 25, }, { email: "example2@example.com", first_name: "Example", last_name: "User", age: 25, }, ]; const request = { url: `/v3/contactdb/recipients`, method: "POST", body: data, }; client .request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) .catch((error) => { console.error(error); }); ``` ```python import os from sendgrid import SendGridAPIClient sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY")) data = [ { "email": "example@example.com", "first_name": "", "last_name": "User", "age": 25, }, { "email": "example2@example.com", "first_name": "Example", "last_name": "User", "age": 25, }, ] response = sg.client.contactdb.recipients.post(request_body=data) print(response.status_code) print(response.body) print(response.headers) ``` ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using SendGrid; public class Program { public static async Task Main() { string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY"); var client = new SendGridClient(apiKey); var data = @"[ { ""email"": ""example@example.com"", ""first_name"": """", ""last_name"": ""User"", ""age"": 25 }, { ""email"": ""example2@example.com"", ""first_name"": ""Example"", ""last_name"": ""User"", ""age"": 25 } ]"; var response = await client.RequestAsync( method: SendGridClient.Method.POST, urlPath: "contactdb/recipients", requestBody: data); Console.WriteLine(response.StatusCode); Console.WriteLine(response.Body.ReadAsStringAsync().Result); Console.WriteLine(response.Headers.ToString()); } } ``` ```java import com.sendgrid.*; import java.io.IOException; import org.json.JSONArray; import java.util.HashMap; import java.util.Arrays; public class Example { public static void main(String[] args) throws IOException { try { SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY")); Request request = new Request(); request.setMethod(Method.POST); request.setEndpoint("/contactdb/recipients"); request.setBody(new JSONArray(Arrays.asList( new HashMap() { { put("email", "example@example.com"); put("first_name", ""); put("last_name", "User"); put("age", 25); } }, new HashMap() { { put("email", "example2@example.com"); put("first_name", "Example"); put("last_name", "User"); put("age", 25); } })) .toString()); Response response = sg.api(request); System.out.println(response.getStatusCode()); System.out.println(response.getBody()); System.out.println(response.getHeaders()); } catch (IOException ex) { throw ex; } } } ``` ```go package main import ( "fmt" "github.com/sendgrid/sendgrid-go" "os" ) func main() { apiKey := os.Getenv("SENDGRID_API_KEY") host := "https://api.sendgrid.com" request := sendgrid.GetRequest(apiKey, "/v3/contactdb/recipients", host) request.Method = "POST" request.Body = []byte(`[ { "email": "example@example.com", "first_name": "", "last_name": "User", "age": 25 }, { "email": "example2@example.com", "first_name": "Example", "last_name": "User", "age": 25 } ]`) response, err := sendgrid.API(request) if err != nil { fmt.Println(err.Error()) os.Exit(1) } else { fmt.Println(response.StatusCode) fmt.Println(response.Body) fmt.Println(response.Headers) } } ``` ```php /sendgrid-php.php'; $apiKey = getenv("SENDGRID_API_KEY"); $sg = new \SendGrid($apiKey); $request_body = json_decode('[ { "email": "example@example.com", "first_name": "", "last_name": "User", "age": 25 }, { "email": "example2@example.com", "first_name": "Example", "last_name": "User", "age": 25 } ]'); try { $response = $sg->client ->contactdb() ->recipients() ->post($request_body); print $response->statusCode() . "\n"; print_r($response->headers()); print $response->body() . "\n"; } catch (Exception $ex) { echo "Caught exception: " . $ex->getMessage(); } ``` ```ruby require 'sendgrid-ruby' include SendGrid sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY']) data = JSON.parse('[ { "email": "example@example.com", "first_name": "", "last_name": "User", "age": 25 }, { "email": "example2@example.com", "first_name": "Example", "last_name": "User", "age": 25 } ]') response = sg.client.contactdb.recipients.post(request_body: data) puts response.status_code puts response.headers puts response.body ``` ```bash curl -X POST "https://api.sendgrid.com/v3/contactdb/recipients" \ --header "Authorization: Bearer $SENDGRID_API_KEY" \ --header "Content-Type: application/json" \ --data '[{"email": "example@example.com", "first_name": "", "last_name": "User", "age": 25}, {"email": "example2@example.com", "first_name": "Example", "last_name": "User", "age": 25}]' ```